Transport Plugin

The Transport Plugin is responsible for transport of messages to and from an implementation of pntOS. This plugin receives messages from various sources outside of pntOS and sends messages back out as needed. Most incoming messages will come from sensors or Smartcables, the primary output message will be a fused solution obtained by processing the input messages.

In addition to handling the transport of messages themselves, this plugin is responsible for converting messages to/from ASPN as needed. Internally, pntOS processes ASPN messages, so all incoming messages need to be converted to ASPN before they can be processed. If incoming messages are already in an ASPN format, then the data only needs to be marshalled into the proper ASPN Python class.

For more information about ASPN, see ASPN.

Transport Plugin API

In addition to the methods required of all plugins, a transport plugin must implement the following methods:

  1. start_listening() - This will be called by the ControllerPlugin when it is ready to start processing messages.

  2. stop_listening() - Similarly, this can be called when the controller plugin is done processing messages, or wants to temporarily stop ingesting data.

  3. broadcast_message() - This will be called by the Mediator to output a message. Note that any plugin can publish a message by calling mediator.broadcast_aspn_message, and it is the mediator’s job to route this message out through the desired transport(s).

When a transport plugin receives an incoming message, after converting it into the desired ASPN message type, it should pass that message to the mediator to be processed by calling mediator.process_pntos_message.

Note

There is no process_message method in the transport plugin API, as the way each plugin handles incoming messages is up to the implementer. In most cases, this involves spinning up a thread that listens for incoming messages, forwarding them on to the mediator as they arrive.

Transport Plugin Implementations

Cobra offers a few off-the-shelf transport plugin implementations, each specific to a particular transport method.

Note

If your desired transport protocol is not supported by these plugins, they may still be helpful as a reference for implementing your own.

The LcmLogTransportPlugin utilizes the Lightweight Communications and Marshalling (LCM) protocol, reading ASPN messages from one LCM log and writing messages to another.

This plugin is primarily useful for obtaining fast, postprocessed solutions, as it will run through all the messages in the input log as quick as possible. It is capable of ingesting ASPN23 messages from an LCM log.

To use this plugin in your app, you just have to ensure that this plugin is included in your list of plugins to run, and that it’s been configured by setting the LcmLogTransportConfig.

See POS INS App for a walkthrough of an app that uses this plugin.

Like the LCM log-based transport plugin, the LcmTransportPlugin uses LCM to decode ASPN input messages and to encode output messages. However, instead of reading from and writing to a log, this plugin listens and publishes messages over the network, via either TCP or UDP.

This plugin is primarily useful for real-time scenarios, where pntOS is listening to and processing data from various sensors to produce a live solution.

To use this plugin in your app, you need to do the following:

  1. Ensure that this plugin is included in your list of plugins to run

  2. Ensure that the plugin configuration is set by filling out the LcmTransportConfig.

  3. Before starting the app, spin up a network relay.

  4. If desired, before starting the app, spin up an LCM logger so that input and output messages can be recorded.

  5. After starting the app, start streaming data over the network by playing messages from a log file or broadcasting from one or more sensor drivers or smartcables.

See Running Your First App for specific instructions on how to run an example app that uses this plugin.

Note

Currently, this transport only works with ROS2 Humble or Jazzy.

The Aspn23RosTransportPlugin sends and receives ASPN23 messages over the network using the Robot Operating System (ROS) protocol.

See ROS Transport App for a walkthrough of an app that uses this plugin.