Skip to content

Commit bc98e0a

Browse files
hardbytehardbyte
committed
Update documentation for Message object.
1 parent a5e479a commit bc98e0a

2 files changed

Lines changed: 130 additions & 83 deletions

File tree

‎can/message.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ def __init__(self, timestamp=0.0, is_remote_frame=False, extended_id=True,
1212

1313
self.timestamp = timestamp
1414
self.id_type = extended_id
15+
self.is_extended_id = extended_id
1516

1617
self.is_remote_frame = is_remote_frame
1718
self.is_error_frame = is_error_frame
@@ -76,3 +77,6 @@ def __str__(self):
7677
pass
7778

7879
return " ".join(field_strings).strip()
80+
81+
def __len__(self):
82+
return len(self.data)

‎doc/message.rst‎

Lines changed: 126 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,116 +1,159 @@
11
Message
22
=======
33

4-
The :class:`~can.Message` object is used to represent CAN messages. Instantiating
5-
a CAN message (with default values for timestamp, arbitration ID, flags, and
6-
data) is done as follows:
4+
.. warning::
75

8-
>>> from can import Message
9-
>>> test = Message()
10-
>>> print(test)
11-
0.000000 0000 0002 0
12-
>>> test2 = Message(data=[1,2,3,4,5])
13-
>>> print(test2)
14-
0.000000 0000 0002 5 01 02 03 04 05
6+
Check the backend specific documentation for additional fields or differences.
157

16-
The fields in the printed message are (in order):
17-
- timestamp,
18-
- arbitration ID,
19-
- flags,
20-
- dlc,
21-
- and data.
228

23-
The flags field is represented as a four-digit hexadecimal number. The arbitration
24-
ID field as either a four or eight digit hexadecimal number depending on the length
25-
of the arbitration ID (11-bit or 29-bit). Each of the bytes in the data field (when
26-
present) are represented as two-digit hexadecimal numbers. The following sections
27-
describe each of the parameters to the Message constructor.
9+
.. module:: can
2810

29-
Timestamp
30-
---------
11+
.. autoclass:: Message
3112

32-
The timestamp field in a CAN message is a floating point number representing when
33-
the message was received since the epoch in seconds. Where possible this will be
34-
timestamped in hardware.
13+
One can instantiate a :class:`~can.Message` defining data, and optional
14+
arguments for all attributes such as arbitration ID, flags, and timestamp.
3515

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

37-
Arbitration ID
38-
--------------
3925

40-
The arbitration ID field in a CAN message may be either 11 bits (standard
41-
addressing, CAN 2.0A) or 29 bits (extended addressing, CAN 2.0B) in length, and
42-
``python-can`` supports this by providing an ``extended_id`` parameter to the
43-
Message constructor. The effect of this parameter is shown below.
26+
The :attr:`~can.Message.arbitration_id` field in a CAN message may be either
27+
11 bits (standard addressing, CAN 2.0A) or 29 bits (extended addressing, CAN
28+
2.0B) in length, and ``python-can`` exposes this difference with the
29+
:attr:`~can.Message.is_extended_id` attribute.
4430

45-
The arbitration ID parameter itself can take an integer between 0 and the
46-
maximum value allowed by the extended_id parameter passed to the Message
47-
constructor (either 2\ :sup:`11` - 1 for 11-bit IDs, or 2\ :sup:`29` - 1 for
48-
29-bit identifiers).
31+
.. attribute:: arbitration_id
4932

50-
>>> print(Message(extended_id=False))
51-
0.000000 0000 0002 0
33+
:type: int
5234

53-
>>> print(Message(extended_id=True))
54-
0.000000 00000000 0004 0
55-
56-
>>> print(Message(extended_id=False, arbitration_id=100))
57-
0.000000 0064 0002 0
35+
The frame identifier used for arbitration on the bus.
5836

37+
The arbitration ID can take an int between 0 and the
38+
maximum value allowed depending on the is_extended_id flag
39+
(either 2\ :sup:`11` - 1 for 11-bit IDs, or
40+
2\ :sup:`29` - 1 for 29-bit identifiers).
5941

60-
is_remote_frame
61-
---------------
42+
>>> print(Message(extended_id=False, arbitration_id=100))
43+
Timestamp: 0.000000 ID: 0064 000 DLC: 0
6244

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

66-
id_type
67-
-------
46+
.. attribute:: data
6847

69-
This parameter controls the length of this CAN message's arbitration ID field.
70-
It is covered in the `Arbitration ID`_ section of this document.
48+
:type: bytearray
7149

50+
The data parameter of a CAN message is exposed as a **bytearray**
51+
with length between 0 and 8.
7252

73-
is_error_frame
74-
--------------
53+
>>> example_data = bytearray([1, 2, 3])
54+
>>> print(Message(data=example_data))
55+
0.000000 00000000 0002 3 01 02 03
7556

76-
This boolean parameter indicates if the message is an error frame or not.
57+
A :class:`~can.Message` can also be created with bytes, or lists of ints:
7758

78-
DLC
79-
---
59+
>>> m1 = Message(data=[0x64, 0x65, 0x61, 0x64, 0x62, 0x65, 0x65, 0x66])
60+
>>> print(m1.data)
61+
bytearray(b'deadbeef')
62+
>>> m2 = can.Message(data=b'deadbeef')
63+
>>> m2.data
64+
bytearray(b'deadbeef')
8065

81-
The :abbr:`DLC (Data Link Count)` parameter of a CAN message is an integer
82-
between 0 and 8. Its purpose varies depending on the frame type - for data
83-
frames it represents the amount of data contained in the message, in remote
84-
frames it represents the amount of data being requested from the device the
85-
message is addressed to.
8666

87-
The default behaviour is to use the length of the data passed in.
67+
.. attribute:: dlc
8868

89-
>>> print(Message(dlc=1))
90-
0.000000 0000 0002 1
91-
>>> print(Message(dlc=5))
92-
0.000000 0000 0002 5
69+
:type: int
70+
71+
The :abbr:`DLC (Data Link Count)` parameter of a CAN message is an integer
72+
between 0 and 8 representing the frame payload length.
73+
74+
>>> m = Message(data=[1, 2, 3])
75+
>>> m.dlc
76+
3
77+
78+
.. note::
79+
80+
The DLC value does not necessarily define the number of bytes of data
81+
in a message.
82+
83+
Its purpose varies depending on the frame type - for data frames it
84+
represents the amount of data contained in the message, in remote
85+
frames it represents the amount of data being requested.
86+
87+
88+
.. attribute:: is_extended_id
89+
90+
:type: bool
91+
92+
This flag controls the size of the :meth:`~can.Message.arbitration_id` field.
93+
94+
>>> print(Message(extended_id=False))
95+
Timestamp: 0.000000 ID: 0000 000 DLC: 0
96+
>>> print(Message(extended_id=True))
97+
Timestamp: 0.000000 ID: 00000000 010 DLC: 0
98+
99+
100+
Previously this was exposed as `id_type`.
101+
102+
103+
.. attribute:: is_error_frame
104+
105+
:type: bool
106+
107+
This boolean parameter indicates if the message is an error frame or not.
108+
109+
110+
.. attribute:: is_remote_frame
111+
112+
:type: boolean
113+
114+
This boolean attribute indicates if the message is a remote frame or a data frame, and
115+
modifies the bit in the CAN message's flags field indicating this.
116+
117+
118+
.. attribute:: timestamp
119+
120+
:type: float
121+
122+
The timestamp field in a CAN message is a floating point number representing when
123+
the message was received since the epoch in seconds. Where possible this will be
124+
timestamped in hardware.
125+
126+
127+
.. method:: __str__
128+
129+
A string representation of a CAN message:
130+
131+
>>> from can import Message
132+
>>> test = Message()
133+
>>> print(test)
134+
Timestamp: 0.000000 ID: 00000000 010 DLC: 0
135+
>>> test2 = Message(data=[1, 2, 3, 4, 5])
136+
>>> print(test2)
137+
Timestamp: 0.000000 ID: 00000000 010 DLC: 5 01 02 03 04 05
138+
139+
The fields in the printed message are (in order):
140+
141+
- timestamp,
142+
- arbitration ID,
143+
- flags,
144+
- dlc,
145+
- and data.
146+
147+
148+
The flags field is represented as a four-digit hexadecimal number. The arbitration
149+
ID field as either a four or eight digit hexadecimal number depending on the length
150+
of the arbitration ID (11-bit or 29-bit). Each of the bytes in the data field (when
151+
present) are represented as two-digit hexadecimal numbers. The following sections
152+
describe each of the parameters to the Message constructor.
93153

94-
.. note::
95-
The DLC value does not necessarily define the number of bytes of data
96-
in a packet.
97154

98155

99-
Data
100-
----
101156

102-
The data parameter of a CAN message is a **bytearray** (or list of ints)
103-
with length between 0 and 8.
104157

105-
>>> example_data = bytearray([1,2,3])
106-
>>> print(Message(data=example_data))
107-
0.000000 00000000 0002 3 01 02 03
108-
>>> print(can.Message(data=[2,2]))
109-
0.000000 00000000 010 2 02 02
110-
>>> m = can.Message(data=[3])
111-
>>> m.data
112-
bytearray(b'\x03')
113158

114159

115-
.. autoclass:: can.Message
116-
:members:

0 commit comments

Comments
 (0)