Listeners

Listener

The Listener class is an “abstract” base class for any objects which wish to register to receive notifications of new messages on the bus. A Listener can be used in two ways; the default is to call the Listener with a new message, or by calling the method on_message_received.

Listeners are registered with Notifier object(s) which ensure they are notified whenever a new message is received.

Subclasses of Listener that do not override on_message_received will cause NotImplementedError to be thrown when a message is received on the CAN bus.

class can.Listener

Bases: object

stop()

Override to cleanup any open resources.

BufferedReader

class can.BufferedReader

Bases: can.listener.Listener

A BufferedReader is a subclass of Listener which implements a message buffer: that is, when the can.BufferedReader instance is notified of a new message it pushes it into a queue of messages waiting to be serviced.

get_message(timeout=0.5)

Attempts to retrieve the latest message received by the instance. If no message is available it blocks for given timeout or until a message is received (whichever is shorter),

Parameters:timeout (float) – The number of seconds to wait for a new message. Returns:the Message if there is one, or None if there is not.

Logger

The can.Logger uses the following can.Listener types to create .asc, .csv and .db files with the messages received.

class can.Logger

Bases: object

Logs CAN messages to a file.

The format is determined from the file format which can be one of:

• .asc: can.ASCWriter
• .blf can.BLFWriter
• .csv: can.CSVWriter
• .db: can.SqliteWriter
• other: can.Printer

Note this class itself is just a dispatcher, an object that inherits from Listener will be created when instantiating this class.

Printer

class can.Printer(output_file=None)

Bases: can.listener.Listener

The Printer class is a subclass of Listener which simply prints any messages it receives to the terminal.

Parameters:output_file – An optional file to “print” to.

CSVWriter

class can.CSVWriter(filename)

Bases: can.listener.Listener

Writes a comma separated text file of timestamp, arbitration id, flags, dlc, data for each messages received.

SqliteWriter

class can.SqliteWriter(filename)

Bases: can.listener.BufferedReader

Logs received CAN data to a simple SQL database.

The sqlite database may already exist, otherwise it will be created when the first message arrives.

Messages are internally buffered and written to the SQL file in a background thread.

Note

When the listener’s stop() method is called the thread writing to the sql file will continue to receive and internally buffer messages if they continue to arrive before the GET_MESSAGE_TIMEOUT.

If the GET_MESSAGE_TIMEOUT expires before a message is received, the internal buffer is written out to the sql file.

However if the bus is still saturated with messages, the Listener will continue receiving until the MAX_TIME_BETWEEN_WRITES timeout is reached.

GET_MESSAGE_TIMEOUT = 0.25

Number of seconds to wait for messages from internal queue

MAX_TIME_BETWEEN_WRITES = 5

Maximum number of seconds to wait between writes to the database

Database table format

The messages are written to the table messages in the sqlite database. The table is created if it does not already exist.

The entries are as follows:

Name	Data type	Note
ts	REAL	The timestamp of the message
arbitration_id	INTEGER	The arbitration id, might use the extended format
extended	INTEGER	1 if the arbitration id uses the extended format, else 0
remote	INTEGER	1 if the message is a remote frame, else 0
error	INTEGER	1 if the message is an error frame, else 0
dlc	INTEGER	The data length code (DLC)
data	BLOB	The content of the message

ASC (.asc Logging format)

ASCWriter logs CAN data to an ASCII log file compatible with other CAN tools such as Vector CANalyzer/CANoe and other. Since no official specification exists for the format, it has been reverse- engineered from existing log files. One description of the format can be found here.

class can.ASCWriter(filename, channel=1)

Bases: can.listener.Listener

Logs CAN data to an ASCII log file (.asc)

log_event(message, timestamp=None)

Add an arbitrary message to the log file.

stop()

Stops logging and closes the file.

ASCReader reads CAN data from ASCII log files .asc as further references can-utils can be used: asc2log, log2asc.

class can.ASCReader(filename)

Bases: object

Iterator of CAN messages from a ASC Logging File.

Log (.log can-utils Logging format)

CanutilsLogWriter logs CAN data to an ASCII log file compatible with can-utils <https://github.com/linux-can/can-utils> As specification following references can-utils can be used: asc2log, log2asc.

class can.io.CanutilsLogWriter(filename, channel='vcan0')

Bases: can.listener.Listener

Logs CAN data to an ASCII log file (.log) compatible to candump -L

stop()

Stops logging and closes the file.

CanutilsLogReader reads CAN data from ASCII log files .log

class can.io.CanutilsLogReader(filename)

Bases: object

Iterator of CAN messages from a .log Logging File (candump -L).

.log-format looks like this: (0.0) vcan0 001#8d00100100820100

BLF (Binary Logging Format)

Implements support for BLF (Binary Logging Format) which is a proprietary CAN log format from Vector Informatik GmbH.

The data is stored in a compressed format which makes it very compact.

class can.BLFWriter(filename, channel=1)

Bases: can.listener.Listener

Logs CAN data to a Binary Logging File compatible with Vector’s tools.

COMPRESSION_LEVEL = 9

ZLIB compression level

MAX_CACHE_SIZE = 131072

Max log container size of uncompressed data

log_event(text, timestamp=None)

Add an arbitrary message to the log file as a global marker.

Parameters:

• text (str) – The group name of the marker.
• timestamp (float) – Absolute timestamp in Unix timestamp format. If not given, the marker will be placed along the last message.

stop()

Stops logging and closes the file.

class can.BLFReader(filename)

Bases: object

Iterator of CAN messages from a Binary Logging File.

Only CAN messages and error frames are supported. Other object types are silently ignored.