OpenLCB over CAN

OpenLCB over CAN

Classes for creating, manipulating, and parsing CAN frames as OpenLCB messages.

author:Dustin C. Hatch
author:Timothy C. Hatch
class openlcb.can.AddressedMessage(**keywords)

Represents a message sent to a single node

Parameters:
  • src_alias (int) – The alias of the node from which messages originate
  • dst_alias (int) – The alias of the node to which the message is sent
src_alias

The node alias of the node sending the message

dst_alias

The alias of the node for which the message is intended

exception openlcb.can.AlreadyRegistered(mti, body_data=None)

Raised when more than one class attempt to use the same MTI

class openlcb.can.CANMessage(header='', body='')

Base class for Controller Area Network messages

Calling str() on CANMessage instances returns a string containing the CAN frame.

header

The value of the header that would be sent in the frame

body

The value of the body that would be sent with the frame

classmethod from_sequence(seq)

Convert a sequence (list, etc.) of strings to Message objects

Parameters:seq (sequence) – A sequence of OpenLCB frame strings
Yields:Instances of the CANMessage subclass
classmethod from_string(frame)

Create a CANMessage instance from a frame string

Parameters:frame (str) – The complete CAN frame, including control characters
Returns:A new instance of the CANMessage subclass

Subclasses of CANMessage should not override this method, but rather parse_frame() instead.

classmethod parse_frame(frame)

Parse a string containing a CAN frame into its parts

Returns dict:A dictionary containing the valuable message parts

Subclasses of CANMessage should override this method and provide their own unique logic for parsing the header and body into usable properties.

class openlcb.can.DatagramData(**keywords)

Represents a message that contains a full node ID

node_id

The full of the ID of the node identified in the message

class openlcb.can.EventMessage(**keywords)

Represents a message containing an event ID

event_id

The ID of the event identified in the message

According to the Event Identifiers Technical Note, a node ID is part of the event ID, however it does not have to have any relationship to the event (i.e. it does not have to refer to the node sending the message).

class openlcb.can.GlobalMessage(**keywords)

Represents a message sent to the entire bus

exception openlcb.can.IncorrectMTI(mti, cls)

Raised when creating a message from a string with the wrong MTI

exception openlcb.can.InvalidMessage(frame)

Raised when attempting to parse an improperly-formatted frame

class openlcb.can.NodeAlias(alias)

Utility class for handling node alias

  • Calling int on an instance of NodeAlias will return the integer value.
  • Calling str on an instance of NodeAlias will return a hexidecimal number.
class openlcb.can.NodeIDMessage(**keywords)

Represents a message that contains a full node ID

node_id

The full of the ID of the node identified in the message

class openlcb.can.OpenLCBMessage(**keywords)

Base class for all OpenLCB CAN messages

Parameters:src_alias (int) – The alias of the node from which messages originate
src_alias

The node alias of the node sending the message

MTI

The message type indicator, as an integer. This value should be set by subclasses of CANMessage. See http://www.openlcb.org/trunk/specs/MtiAllocations.pdf for a list of MTI allocations.

class openlcb.can.RegisteredMessage

Metaclass for OpenLCB message classes

Classes using RegisteredMessage as their metaclass will automatically have their MTIs registered, which creates a reverse mapping from MTI to class. This registration is required for parse_frame() to discover a message class based on the MTI and return an instance of it.

openlcb.can.parse_frame(frame)

Parse an OpenLCB Message from a CAN frame

Parameters:frame (str) – CAN frame as a string, including control characters
Returns:An instance of the class registered for the MTI specified in the frame

The message type lookup proceeds as follows:

  1. The MTI of the message is determined by shifting the header to the left by 12 bits
  2. If the message contains a body, the first byte (2 characters) is taken as the body MTI
  3. The list of registered message classes is searched for a class with the same MTI and no body MTI
  4. If no class is found, the list of registered message classes is searched again for the same MTI, this time including the body MTI
  5. If no class is found, a new MTI is calculated by bit shifting the MTI 12 places to the right
  6. The list of registered message classes is searched for a class with the recalculated MTI and the body MTI
  7. If a class is still not found, a new one is created. The new class is called UnknownMessage and inherits directly from OpenLCBMessage. Its MTI is set to the original MTI (i.e. before the second bit shift), and its body MTI is set, if it exists.

Once a suitable message class has been found (or created), it will be instantiated by calling its from_string classmethod, passing in the original message frame string.

Previous topic

API Reference

Next topic

OpenLCB Message Representations

This Page