# 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`
  `stop`()

    Override to cleanup any open resources.

## BufferedReader

class `can.``BufferedReader`

  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`

  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)

  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)

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

## SqliteWriter

class `can.``SqliteWriter`(filename)

  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

## 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)

  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)

  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')

  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)

  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)

  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)

  Iterator of CAN messages from a Binary Logging File.

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