Message(timestamp=0.0, arbitration_id=0, is_extended_id=None, is_remote_frame=False, is_error_frame=False, channel=None, dlc=None, data=None, is_fd=False, bitrate_switch=False, error_state_indicator=False, extended_id=None, check=False)¶
Messageobject 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
Messages do not support “dynamic” attributes, meaning any others than the documented ones, since it uses
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. Raises: ValueError – iff check is set to True and one or more arguments were invalid
One can instantiate a
Messagedefining 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
arbitration_idfield 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-canexposes this difference with the
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.
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_idflag (either 211 - 1 for 11-bit IDs, or 229 - 1 for 29-bit identifiers).
>>> print(Message(is_extended_id=False, arbitration_id=100)) Timestamp: 0.000000 ID: 0064 S DLC: 0
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
Messagecan 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')
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
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.
This flag controls the size of the
arbitration_idfield. 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
The initializer argument and attribute
extended_idhas been deprecated in favor of
is_extended_id, but will continue to work for the
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
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
If this is a CAN FD message, this indicates that a higher bitrate was used for the data transmission.
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):
- arbitration ID,
- and data.
The flags field is represented as one, two or three letters:
- X if the
is_extended_idattribute is set, otherwise S,
- E if the
is_error_frameattribute is set,
- R if the
is_remote_frameattribute 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.
Compares a given message with this one.
Parameters: Return type: Returns:
True iff the given message equals this one