Message#

class can.Message(timestamp=0.0, arbitration_id=0, is_extended_id=True, is_remote_frame=False, is_error_frame=False, channel=None, dlc=None, data=None, is_fd=False, is_rx=True, bitrate_switch=False, error_state_indicator=False, check=False)[source]#

The Message object is used to represent CAN messages for sending, receiving and other purposes like converting between different logging formats.

Messages can use extended identifiers, be remote or error frames, contain data and may be associated to a channel.

Messages are always compared by identity and never by value, because that may introduce unexpected behaviour. See also equals().

copy()/deepcopy() is supported as well.

Messages do not support “dynamic” attributes, meaning any others than the documented ones, since it uses __slots__.

To create a message object, simply provide any of the below attributes together with additional parameters as keyword arguments to the constructor.

Parameters

check (bool) – By default, the constructor of this class does not strictly check the input. Thus, the caller must prevent the creation of invalid messages or set this parameter to True, to raise an Error on invalid inputs. Possible problems include the dlc field not matching the length of data or creating a message with both is_remote_frame and is_error_frame set to True.
timestamp (float) –
arbitration_id (int) –
is_extended_id (bool) –
is_remote_frame (bool) –
is_error_frame (bool) –
channel (Optional[Union[int, str]]) –
dlc (Optional[int]) –
data (Optional[Union[bytes, bytearray, int, Iterable[int]]]) –
is_fd (bool) –
is_rx (bool) –
bitrate_switch (bool) –
error_state_indicator (bool) –

Raises

ValueError – If and only if check is set to True and one or more arguments were invalid

One can instantiate a Message defining data, and optional arguments for all attributes such as arbitration ID, flags, and timestamp.

>>> from can import Message
>>> test = Message(data=[1, 2, 3, 4, 5])
>>> test.data
bytearray(b'\x01\x02\x03\x04\x05')
>>> test.dlc
5
>>> print(test)
Timestamp:        0.000000    ID: 00000000    010    DLC: 5    01 02 03 04 05

The arbitration_id field in a CAN message may be either 11 bits (standard addressing, CAN 2.0A) or 29 bits (extended addressing, CAN 2.0B) in length, and python-can exposes this difference with the is_extended_id attribute.

timestamp#

Type: float

The timestamp field in a CAN message is a floating point number representing when the message was received since the epoch in seconds. Where possible this will be timestamped in hardware.

arbitration_id#

Type: int

The frame identifier used for arbitration on the bus.

The arbitration ID can take an int between 0 and the maximum value allowed depending on the is_extended_id flag (either 2¹¹ - 1 for 11-bit IDs, or 2²⁹ - 1 for 29-bit identifiers).

>>> print(Message(is_extended_id=False, arbitration_id=100))
Timestamp:        0.000000        ID: 0064    S        DLC: 0

data#

Type: bytearray

The data parameter of a CAN message is exposed as a bytearray with length between 0 and 8.

>>> example_data = bytearray([1, 2, 3])
>>> print(Message(data=example_data))
Timestamp:        0.000000    ID: 00000000    X        DLC: 3    01 02 03

A Message can also be created with bytes, or lists of ints:

>>> m1 = Message(data=[0x64, 0x65, 0x61, 0x64, 0x62, 0x65, 0x65, 0x66])
>>> print(m1.data)
bytearray(b'deadbeef')
>>> m2 = Message(data=b'deadbeef')
>>> m2.data
bytearray(b'deadbeef')

dlc#

Type: int

The DLC parameter of a CAN message is an integer between 0 and 8 representing the frame payload length.

In the case of a CAN FD message, this indicates the data length in number of bytes.

>>> m = Message(data=[1, 2, 3])
>>> m.dlc
3

Note

The DLC value does not necessarily define the number of bytes of data in a message.

Its purpose varies depending on the frame type - for data frames it represents the amount of data contained in the message, in remote frames it represents the amount of data being requested.

channel#

Type: str or int or None

This might store the channel from which the message came.

is_extended_id#

Type: bool

This flag controls the size of the arbitration_id field. Previously this was exposed as id_type.

>>> print(Message(is_extended_id=False))
Timestamp:        0.000000        ID: 0000    S        DLC: 0
>>> print(Message(is_extended_id=True))
Timestamp:        0.000000    ID: 00000000    X        DLC: 0

Note

The initializer argument and attribute extended_id has been deprecated in favor of is_extended_id, but will continue to work for the 3.x release series.

is_error_frame#

Type: bool

This boolean parameter indicates if the message is an error frame or not.

>>> print(Message(is_error_frame=True))
Timestamp:        0.000000    ID: 00000000    X E      DLC: 0

is_remote_frame#

Type: bool

This boolean attribute indicates if the message is a remote frame or a data frame, and modifies the bit in the CAN message’s flags field indicating this.

>>> print(Message(is_remote_frame=True))
Timestamp:        0.000000    ID: 00000000    X   R    DLC: 0

is_fd#

Type: bool

Indicates that this message is a CAN FD message.

is_rx#

Type: bool

Indicates whether this message is a transmitted (Tx) or received (Rx) frame

bitrate_switch#

Type: bool

If this is a CAN FD message, this indicates that a higher bitrate was used for the data transmission.

error_state_indicator#

Type: bool

If this is a CAN FD message, this indicates an error active state.

__str__()[source]#

A string representation of a CAN message:

>>> from can import Message
>>> test = Message()
>>> print(test)
Timestamp:        0.000000    ID: 00000000    X        DLC: 0
>>> test2 = Message(data=[1, 2, 3, 4, 5])
>>> print(test2)
Timestamp:        0.000000    ID: 00000000    X        DLC: 5    01 02 03 04 05

The fields in the printed message are (in order):

timestamp,
arbitration ID,
flags,
dlc,
and data.

The flags field is represented as one, two or three letters:

X if the is_extended_id attribute is set, otherwise S,
E if the is_error_frame attribute is set,
R if the is_remote_frame attribute is set.

The arbitration ID field is represented as either a four or eight digit hexadecimal number depending on the length of the arbitration ID (11-bit or 29-bit).

Each of the bytes in the data field (when present) are represented as two-digit hexadecimal numbers.

equals(other, timestamp_delta=1e-06, check_direction=True)[source]#

Compares a given message with this one.

Parameters

other (can.message.Message) – the message to compare with
timestamp_delta (Optional[float]) – the maximum difference in seconds at which two timestamps are still considered equal or None to not compare timestamps
check_direction (bool) – whether to compare the messages’ directions (Tx/Rx)

Returns

True if and only if the given message equals this one

Return type

bool