pamoja.can

  1"""Idiomatic CAN facade.
  2
  3CAN is how the moving parts of a machine talk to each other: motor controllers,
  4servos, battery management, and the engines and farm equipment that speak J1939 on
  5top of it. :class:`CanBus` is one node on a bus, simulated or a kernel interface
  6through SocketCAN, and the rest is the identifier and payload layer; the controller
  7hardware handles the wire itself.
  8"""
  9
 10from __future__ import annotations
 11
 12import enum
 13from enum import IntEnum
 14from typing import Iterable
 15
 16from pamoja._native import CanBus as _NativeBus
 17from pamoja._native import CanFilter, CanFrame, J1939Message, Signals
 18from pamoja._native import can_dlc_to_len as _dlc_to_len
 19from pamoja._native import can_fd_frame as _fd_frame
 20from pamoja._native import can_frame as _frame
 21from pamoja._native import can_len_to_dlc as _len_to_dlc
 22from pamoja._native import can_remote_frame as _remote_frame
 23from pamoja._native import j1939_compose as _j1939_compose
 24from pamoja._native import j1939_broadcast as _j1939_broadcast
 25from pamoja._native import j1939_decode as _j1939_decode
 26from pamoja._native import j1939_limits as _limits
 27
 28__all__ = [
 29    "BROADCAST_ADDRESS",
 30    "NOT_AVAILABLE",
 31    "CanBus",
 32    "CanBusKind",
 33    "CanFilter",
 34    "CanFrame",
 35    "J1939Message",
 36    "Priority",
 37    "Signals",
 38    "broadcast_j1939",
 39    "compose_j1939",
 40    "decode_j1939",
 41    "dlc_to_len",
 42    "fd_frame",
 43    "frame",
 44    "len_to_dlc",
 45    "remote_frame",
 46    "signals",
 47    "signals_from",
 48]
 49
 50_NOT_AVAILABLE, _BROADCAST_ADDRESS, _CONTROL, _DEFAULT, _LOWEST = _limits()
 51
 52#: The byte a J1939 sender writes for a signal it is not reporting.
 53NOT_AVAILABLE = _NOT_AVAILABLE
 54
 55#: The destination address every node on the bus reads.
 56BROADCAST_ADDRESS = _BROADCAST_ADDRESS
 57
 58
 59class Priority(IntEnum):
 60    """The priorities J1939 publishes, so a caller does not write the number out."""
 61
 62    CONTROL = _CONTROL
 63    """Ahead of ordinary traffic, for a message that controls something."""
 64
 65    DEFAULT = _DEFAULT
 66    """What ordinary traffic uses."""
 67
 68    LOWEST = _LOWEST
 69    """Yields to everything else on the bus."""
 70
 71
 72def signals() -> Signals:
 73    """Build a J1939 payload with every signal marked not available.
 74
 75    :returns: Eight bytes a controller writes only its own signals into.
 76    """
 77    return Signals()
 78
 79
 80def signals_from(data: bytes) -> Signals:
 81    """Read the eight data bytes of a frame that arrived off the bus.
 82
 83    :param data: The frame's payload.
 84    :returns: The payload, ready for its signals to be read out.
 85    :raises PamojaError: The payload is not exactly eight bytes.
 86    """
 87    return Signals.from_bytes(data)
 88
 89
 90def frame(identifier: int, data: bytes, extended: bool = False) -> CanFrame:
 91    """Build a classic CAN 2.0 frame.
 92
 93    :param identifier: The arbitration identifier, masked to the width ``extended``
 94        selects.
 95    :param data: The payload, at most eight bytes.
 96    :param extended: Whether the identifier is a 29-bit extended one.
 97    :returns: The frame.
 98    :raises PamojaError: If the payload is longer than a classic frame carries.
 99    """
100    return _frame(identifier, extended, bytes(data))
101
102
103def fd_frame(identifier: int, data: bytes, extended: bool = False) -> CanFrame:
104    """Build a CAN-FD frame, which carries up to 64 bytes.
105
106    :param identifier: The arbitration identifier.
107    :param data: The payload, at one of the discrete CAN-FD lengths: 0 to 8, then
108        12, 16, 20, 24, 32, 48, or 64 bytes.
109    :param extended: Whether the identifier is a 29-bit extended one.
110    :returns: The frame.
111    :raises PamojaError: If the payload length is not one CAN-FD can carry.
112    """
113    return _fd_frame(identifier, extended, bytes(data))
114
115
116def remote_frame(identifier: int, length: int, extended: bool = False) -> CanFrame:
117    """Build a remote transmission request, which asks another node to send.
118
119    :param identifier: The arbitration identifier.
120    :param length: The data length being requested, clamped to eight bytes.
121    :param extended: Whether the identifier is a 29-bit extended one.
122    :returns: The frame, which carries no payload of its own.
123    """
124    return _remote_frame(identifier, extended, length)
125
126
127def len_to_dlc(length: int) -> int:
128    """Return the data length code that encodes a payload length.
129
130    :param length: The payload length in bytes.
131    :returns: The code, rounding up to the next length CAN-FD can carry.
132    """
133    return _len_to_dlc(length)
134
135
136def dlc_to_len(dlc: int) -> int:
137    """Return the payload length a data length code encodes.
138
139    :param dlc: The data length code.
140    :returns: The length in bytes.
141    """
142    return _dlc_to_len(dlc)
143
144
145def decode_j1939(identifier: int, extended: bool = True) -> J1939Message | None:
146    """Decode the J1939 fields out of an extended CAN identifier.
147
148    :param identifier: The identifier as it arrived.
149    :param extended: Whether it is a 29-bit extended identifier.
150    :returns: The decoded message, or ``None`` for a standard identifier, which
151        J1939 does not use.
152    """
153    return _j1939_decode(identifier, extended)
154
155
156def compose_j1939(priority: int, pgn: int, source: int, destination: int = 0) -> int:
157    """Compose the extended CAN identifier a set of J1939 fields describes.
158
159    :param priority: The message priority, 0 (highest) to 7.
160    :param pgn: The parameter group number.
161    :param source: The address of the sending node.
162    :param destination: The destination address, used only for an addressed (PDU1)
163        parameter group and ignored for a broadcast (PDU2) one.
164    :returns: The 29-bit identifier.
165    """
166    return _j1939_compose(priority, pgn, source, destination)
167
168
169def broadcast_j1939(priority: int, pgn: int, source: int) -> int:
170    """Compose the identifier of a J1939 broadcast, which every node reads.
171
172    Most parameter groups are broadcast, so this is the common case; it saves a
173    caller knowing that a broadcast is addressed to ``0xFF``.
174
175    :param priority: The message priority, 0 (highest) to 7.
176    :param pgn: The parameter group number.
177    :param source: The address of the sending node.
178    :returns: The 29-bit identifier.
179    """
180    return _j1939_broadcast(priority, pgn, source)
181
182
183class CanBusKind(str, enum.Enum):
184    """What a node's bus is."""
185
186    #: A kernel CAN interface reached through SocketCAN.
187    DEVICE = "Device"
188    #: A bus inside the program.
189    SIMULATED = "Simulated"
190
191
192class CanBus:
193    """One node's place on a CAN bus.
194
195    :meth:`open` opens a kernel interface such as ``can0`` through SocketCAN on a Linux board,
196    once it is up with ``ip link set can0 up type can bitrate 250000``. :meth:`simulated` makes
197    a bus inside the program, and :meth:`join` puts another node on the same bus. A node hears
198    every frame the others send and none of its own, and keeps only the frames its filters
199    pass. A send and a receive release the interpreter while the bus is busy; a receive on a
200    simulated bus with nothing waiting returns ``None`` at once and counts its timeout in
201    :attr:`waited_micros`.
202
203    >>> engine = CanBus.simulated()
204    >>> gateway = engine.join()
205    >>> speed = (500).to_bytes(2, "big")
206    >>> engine.send(frame(0x20A, speed))
207    >>> bytes(gateway.receive(timeout=0.01).data) == speed
208    True
209    """
210
211    __slots__ = ("_native",)
212
213    def __init__(self, native: _NativeBus) -> None:
214        """Wrap a native node; use :meth:`open` or :meth:`simulated` instead."""
215        self._native = native
216
217    @classmethod
218    def open(cls, interface: str) -> CanBus:
219        """Open a kernel CAN interface through SocketCAN, as one node on its bus.
220
221        :param interface: ``can0`` for the first controller, ``vcan0`` for a virtual one.
222        :returns: The node.
223        :raises PamojaError: Anywhere but Linux, or when the interface does not exist.
224        """
225        return cls(_NativeBus.open(interface))
226
227    @classmethod
228    def simulated(cls) -> CanBus:
229        """A new bus inside the program, with this node the first on it.
230
231        :returns: The node.
232        """
233        return cls(_NativeBus.simulated())
234
235    def join(self) -> CanBus:
236        """Put another node on the same bus.
237
238        :returns: The new node.
239        """
240        return CanBus(self._native.join())
241
242    @property
243    def kind(self) -> CanBusKind:
244        """What the bus is."""
245        return CanBusKind(self._native.kind)
246
247    @property
248    def interface(self) -> str | None:
249        """The kernel interface the node is on, or ``None`` on a simulated bus."""
250        return self._native.interface
251
252    def send(self, frame: CanFrame) -> None:
253        """Send a frame to every other node on the bus.
254
255        :param frame: The frame.
256        :raises PamojaError: When the kernel refuses the frame.
257        """
258        self._native.send(frame)
259
260    def receive(self, timeout: float) -> CanFrame | None:
261        """Take the next frame the node keeps, waiting up to ``timeout`` for one.
262
263        :param timeout: How long to wait, in seconds.
264        :returns: The frame, or ``None`` when the timeout passed with nothing.
265        :raises PamojaError: When the interface fails.
266        """
267        if not timeout >= 0:
268            raise ValueError("a time must be zero or more seconds")
269        return self._native.receive(round(timeout * 1_000_000))
270
271    def set_filters(self, filters: Iterable[CanFilter]) -> None:
272        """Keep only the frames that pass at least one of the filters, from now on.
273
274        An empty list keeps nothing; :meth:`clear_filters` keeps everything again.
275
276        :param filters: ``CanFilter.pgn(61444)``, ``CanFilter.exact(0x20A)``, and the like.
277        """
278        self._native.set_filters(list(filters))
279
280    def clear_filters(self) -> None:
281        """Keep every frame again, as a node does when it joins."""
282        self._native.clear_filters()
283
284    @property
285    def sent(self) -> int:
286        """How many frames the node has sent."""
287        return self._native.sent
288
289    @property
290    def received(self) -> int:
291        """How many frames the node has received."""
292        return self._native.received
293
294    @property
295    def waited_micros(self) -> int:
296        """How long receives have waited without a frame, whether or not the process slept."""
297        return self._native.waited_micros