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.
BufferedReader¶
-
class
can.
BufferedReader
[source]¶ Bases:
can.listener.Listener
A BufferedReader is a subclass of
Listener
which implements a message buffer: that is, when thecan.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)[source]¶ 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
[source]¶ 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
- .log
can.CanutilsLogWriter
- other:
can.Printer
- .asc:
Note this class itself is just a dispatcher, an object that inherits from Listener will be created when instantiating this class.
Printer¶
CSVWriter¶
-
class
can.
CSVWriter
(filename)[source]¶ Bases:
can.listener.Listener
Writes a comma separated text file with a line for each message.
The columns are as follows:
name of column format description example timestamp decimal float 1483389946.197 arbitration_id hex 0x00dadada extended 1 == True, 0 == False 1 remote 1 == True, 0 == False 0 error 1 == True, 0 == False 0 dlc int 6 data base64 encoded WzQyLCA5XQ== Each line is terminated with a platform specific line seperator.
SqliteWriter¶
-
class
can.
SqliteWriter
(filename)[source]¶ 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 theGET_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.
Note
Channels will be converted to integers.
-
class
can.
ASCWriter
(filename, channel=1)[source]¶ Bases:
can.listener.Listener
Logs CAN data to an ASCII log file (.asc).
The measurement starts with the timestamp of the first registered message. If a message has a timestamp smaller than the previous one (or 0 or None), it gets assigned the timestamp that was written for the last message. It the first message does not have a timestamp, it is set to zero.
ASCReader reads CAN data from ASCII log files .asc as further references can-utils can be used: asc2log, log2asc.
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')[source]¶ Bases:
can.listener.Listener
Logs CAN data to an ASCII log file (.log). This class is is compatible with “candump -L”.
If a message has a timestamp smaller than the previous one (or 0 or None), it gets assigned the timestamp that was written for the last message. It the first message does not have a timestamp, it is set to zero.
CanutilsLogReader reads CAN data from ASCII log files .log
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.
Note
Channels will be converted to integers.
-
class
can.
BLFWriter
(filename, channel=1)[source]¶ 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
-