Library API¶
The main objects are the BusABC
and the Message
.
A form of CAN interface is also required.
Hint
Check the backend specific documentation for any implementation specific details.
Utilities¶
Utilities and configuration file parsing.
-
can.util.
channel2int
(channel)[source]¶ Try to convert the channel to an integer.
Parameters: channel – Channel string (e.g. can0, CAN1) or integer Returns: Channel integer or None if unsuccessful Return type: int
-
can.util.
dlc2len
(dlc)[source]¶ Calculate the data length from DLC.
Parameters: dlc (int) – DLC (0-15) Returns: Data length in number of bytes (0-64) Return type: int
-
can.util.
len2dlc
(length)[source]¶ Calculate the DLC from data length.
Parameters: length (int) – Length in number of bytes (0-64) Returns: DLC (0-15) Return type: int
-
can.util.
load_config
(path=None, config=None)[source]¶ Returns a dict with configuration details which is loaded from (in this order):
- config
- can.rc
- Environment variables CAN_INTERFACE, CAN_CHANNEL, CAN_BITRATE
- Config files
/etc/can.conf
or~/.can
or~/.canrc
where the latter may add or replace values of the former.
Interface can be any of the strings from
can.VALID_INTERFACES
for example: kvaser, socketcan, pcan, usb2can, ixxat, nican, virtual.Note
The key
bustype
is copied tointerface
if that one is missing and does never appear in the result.Parameters: - path – Optional path to config file.
- config – A dict which may set the ‘interface’, and/or the ‘channel’, or neither. It may set other values that are passed through.
Returns: A config dictionary that should contain ‘interface’ & ‘channel’:
{ 'interface': 'python-can backend interface to use', 'channel': 'default channel to use', # possibly more }
Note
None
will be used if all the options are exhausted without finding a value.All unused values are passed from
config
over to this.Raises: NotImplementedError if the
interface
isn’t recognized
-
can.util.
load_environment_config
()[source]¶ Loads config dict from environmental variables (if set):
- CAN_INTERFACE
- CAN_CHANNEL
- CAN_BITRATE
-
can.util.
load_file_config
(path=None)[source]¶ Loads configuration from file with following content:
[default] interface = socketcan channel = can0
Parameters: path – path to config file. If not specified, several sensible default locations are tried depending on platform.
-
can.util.
set_logging_level
(level_name=None)[source]¶ Set the logging level for the “can” logger. Expects one of: ‘critical’, ‘error’, ‘warning’, ‘info’, ‘debug’, ‘subdebug’
-
can.
detect_available_configs
()¶ Detect all configurations/channels that the interfaces could currently connect with.
This might be quite time consuming.
Automated configuration detection may not be implemented by every interface on every platform. This method will not raise an error in that case, but with rather return an empty list for that interface.
Parameters: interfaces – either - the name of an interface to be searched in as a string, - an iterable of interface names to search in, or - None to search in all known interfaces. Return type: list[dict] Returns: an iterable of dicts, each suitable for usage in can.interface.Bus
’s constructor.
Notifier¶
The Notifier object is used as a message distributor for a bus.
-
class
can.
Notifier
(bus, listeners, timeout=1)[source]¶ Bases:
object
Manages the distribution of Messages from a given bus/buses to a list of listeners.
Parameters: - bus (can.BusABC) – The Bus or a list of buses to listen to.
- listeners (list) – An iterable of
Listener
- timeout (float) – An optional maximum number of seconds to wait for any message.
-
add_listener
(listener)[source]¶ Add new Listener to the notification list. If it is already present, it will be called two times each time a message arrives.
Parameters: listener (can.Listener) – Listener to be added to the list to be notified
-
exception
= None¶ Exception raised in thread
-
remove_listener
(listener)[source]¶ Remove a listener from the notification list. This method trows an exception if the given listener is not part of the stored listeners.
Parameters: listener (can.Listener) – Listener to be removed from the list to be notified Raises: ValueError – if listener was never added to this notifier