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.

• Bus
• Thread safe bus
• Message
• Listeners
• Asyncio support
• Broadcast Manager
• Bit Timing Configuration
• Internal API

Utilities

can.detect_available_configs(interfaces=None)

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 (Union[None, str, Iterable[str]]) – 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 the constructor of can.BusABC.

Notifier

The Notifier object is used as a message distributor for a bus. Notifier creates a thread to read messages from the bus and distributes them to listeners.

class can.Notifier(bus, listeners, timeout=1.0, loop=None)

Manages the distribution of Message instances to listeners.

Supports multiple buses and listeners.

Note

Remember to call stop() after all messages are received as many listeners carry out flush operations to persist data.

Parameters

• bus (Union[BusABC, List[BusABC]]) – A Bus or a list of buses to listen to.

• listeners (Iterable[Union[Listener, Callable[[Message], None]]]) – An iterable of Listener or callables that receive a Message and return nothing.

• timeout (float) – An optional maximum number of seconds to wait for any Message.

• loop (Optional[AbstractEventLoop, None]) – An asyncio event loop to schedule the listeners in.

add_bus(bus)

Add a bus for notification.

Parameters

bus (BusABC) – CAN bus instance.

Return type

None

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 (Listener) – Listener to be added to the list to be notified

Return type

None

exception: Optional[Exception]

Exception raised in thread

remove_listener(listener)

Remove a listener from the notification list. This method throws an exception if the given listener is not part of the stored listeners.

Parameters

listener (Listener) – Listener to be removed from the list to be notified

Raises

ValueError – if listener was never added to this notifier

Return type

None

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.

Return type

None

Errors

There are several specific Exception classes to allow user code to react to specific scenarios related to CAN busses:

Exception (Python standard library)
 +-- ...
 +-- CanError (python-can)
     +-- CanInterfaceNotImplementedError
     +-- CanInitializationError
     +-- CanOperationError
     +-- CanTimeoutError

Keep in mind that some functions and methods may raise different exceptions. For example, validating typical arguments and parameters might result in a ValueError. This should always be documented for the function at hand.

exception can.exceptions.CanError(message='', error_code=None)

Bases: Exception

Base class for all CAN related exceptions.

If specified, the error code is automatically appended to the message:

>>> # With an error code (it also works with a specific error):
>>> error = CanOperationError(message="Failed to do the thing", error_code=42)
>>> str(error)
'Failed to do the thing [Error Code 42]'
>>>
>>> # Missing the error code:
>>> plain_error = CanError(message="Something went wrong ...")
>>> str(plain_error)
'Something went wrong ...'

Parameters

• error_code (Optional[int, None]) – An optional error code to narrow down the cause of the fault

• error_code – An optional error code to narrow down the cause of the fault

exception can.exceptions.CanInitializationError(message='', error_code=None)

Bases: can.exceptions.CanError

Indicates an error the occurred while initializing a can.BusABC.

If initialization fails due to a driver or platform missing/being unsupported, a can.CanInterfaceNotImplementedError is raised instead. If initialization fails due to a value being out of range, a ValueError is raised.

Example scenarios:

• Try to open a non-existent device and/or channel

• Try to use an invalid setting, which is ok by value, but not ok for the interface

• The device or other resources are already used

exception can.exceptions.CanInterfaceNotImplementedError(message='', error_code=None)

Bases: can.exceptions.CanError, NotImplementedError

Indicates that the interface is not supported on the current platform.

Example scenarios:

• No interface with that name exists

• The interface is unsupported on the current operating system or interpreter

• The driver could not be found or has the wrong version

exception can.exceptions.CanOperationError(message='', error_code=None)

Bases: can.exceptions.CanError

Indicates an error while in operation.

Example scenarios:

• A call to a library function results in an unexpected return value

• An invalid message was received

• The driver rejected a message that was meant to be sent

• Cyclic redundancy check (CRC) failed

• A message remained unacknowledged

• A buffer is full

exception can.exceptions.CanTimeoutError(message='', error_code=None)

Bases: can.exceptions.CanError, TimeoutError

Indicates the timeout of an operation.

Example scenarios:

• Some message could not be sent after the timeout elapsed

• No message was read within the given time

can.exceptions.error_check(error_message=None, exception_type=<class 'can.exceptions.CanOperationError'>)

Catches any exceptions and turns them into the new type while preserving the stack trace.

Return type

Generator[None, None, None]