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)

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)

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)

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)

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 to interface 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()

Loads config dict from environmental variables (if set):

  • CAN_INTERFACE
  • CAN_CHANNEL
  • CAN_BITRATE
can.util.load_file_config(path=None)

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)

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)
add_listener(listener)

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)

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
stop(timeout=5)

Stop notifying Listeners when new Message objects arrive and call stop() on each Listener.

Parameters:timeout (float) – Max time in seconds to wait for receive threads to finish. Should be longer than timeout given at instantiation.

Errors

class can.CanError

Indicates an error with the CAN network.