Proton

Proton is a lightweight, efficient, peer-to-peer communication protocol designed for embedded systems and robotics applications. It enables bidirectional communication between nodes. The protocol is built on top of Google Protocol Buffers (protobuf) and provides a lightweight C or C++ implementation optimized for resource-constrained embedded systems, extendable to a runtime-configurable C++ implementation for high-powered devices. Proton also offers a ROS 2 adapter that bridges communication between the Proton protocol and ROS 2, allowing embedded devices to still participate in a ROS 2 network without the complexity and overhead of ROS 2 middleware.

As of the Jazzy 2.9 software release (and clearpath_firmware version 3.0.0), all Clearpath robots use this protocol for MCU to PC communication.

note

This documentation is intended for users wishing to understand the Proton protocol and implement it into their robots or projects. Users with Clearpath robots only need to update their robots to the latest firmware and set Proton as their MCU communication protocol in the Robot Configuration. See the MCU Protocol section for details.

Key Concepts

Signals

The fundamental data unit in proton. A Signal represents a typed value with a known size.

note

There are nuances to how Signals and Bundles are defined between the two different versions of Proton, see the 1.0 documentation vs the 2.0 documentation for comparison.

Proton 1.0	Proton 2.0
Signals must be associated with a single Bundle	Signals can be part of 0 or more Bundles
A Signal represents data that is specific to that Bundle	Signals represent data shared between Nodes, the Bundle is simply the grouping
Signals can be lists of almost any type that is also a scalar	Signals are scalar-only
Signals with default values are immutable	All Signals are mutable, but can have a default value

Bundles

A Bundle is a collection of Signals, associated with a 32-bit "Bundle ID". Bundles are the main data type used for messaging between devices.

Nodes

A node represents a participant in the communication network. Each node can:

• Produce bundles (send data)
• Consume bundles (receive data)
• Communicate with multiple peer nodes

A node is also defined with a list of endpoints at which it can be reached.

Peers

Peers are other nodes in the proton network that a given node can communicate with. A node is paired with a peer with a pair of endpoints called a connection.

Proton Versions

Proton 1

The original version of the Proton library, released as part of Jazzy 2.9 and clearpath_firmware v3.0.0. The core library (protonc) uses a build-time generation script to create individual message Bundles with unique Signals, akin to ROS 2 messages. Signals are accessed via name within bespoke Bundle structs.

Proton 1 also incorporates a liveliness mechanism for participant nodes via "heartbeat Bundles", and the concept of "const" immutable Signals.

This ecosystem has two main libraries:

• protonc: C library using nanopb for protobuf encode/decode. Requires code generation to create the bundles and nodes used in operation.
• protoncpp: C++ library using Google's protobuf library, compatible with Linux and incorporates asynchronous message transport from boost asio

Proton 1 also incorporates a ROS 2 package to convert Proton Bundles into ROS 2 messages and services.

note

Adding custom messages to proton_ros2 requires a fork of the existing codebase as the message bridging classes are built as part of the package.

Proton source code is available on GitHub:

• Core libraries: https://github.com/clearpathrobotics/proton/tree/1.0.1
• ROS 2 adapter: https://github.com/clearpathrobotics/proton_ros2/tree/1.0.0

note

Proton 1 is no longer being actively developed.

Proton 2

A refactored version of Proton written specifically to address the need for removing re-declaring signals between Bundles, and to remove the need to compile autogenerated code within libprotonc. Proton 2.0 uses a "Signal Registry" for a participant Node to access Signal data via 32-bit identifiers, operating on a bring-your-own-memory (BYOM) model to allow a user to declare their Signal Registry either via the included code generation system, or allocating it themselves. The transport framing API is largely unchanged from Proton 1.

This ecosystem also has two libraries:

• proton_core: C library including the Signal Registry API and Node Manager API. Defines types for the Signal Registry and Node Manager, but does not allocate directly.
• proton_cpp: C++ Superset of proton_core, scaling from simple no-alloc type-safe C++ wrapper all the way up to runtime generation of a Signal Registry and Node Manager from YAML and JSON configuration files. Does not include asynchronous message transport to allow for portability.

Proton 2 also has a ROS 2 bridging ecosystem (the 2.0 release of proton_ros2), rewritten to use pluginlib to easily add user-defined ROS 2 messages, and reuse Proton Signals between topics. proton_ros2_node incorporates OTTO Motors' asynchronous transport packages with proton_ros2 to complete the Proton/ROS 2 communication ecosystem.

• Core libraries: https://github.com/clearpathrobotics/proton
• ROS 2 adaptor: https://github.com/clearpathrobotics/proton_ros2

Transport Layers

Proton leverages Protobuf serialization to encode data into packets, enabling it to be sent over any transport layer that can handle dynamically sized packets.

Currently, Serial and UDP transport is supported.

UDP Transport (2.0 and up)

When using the UDP transport, both nodes in a connection will bind to a socket at a specified port and receive bundles they consume at that socket. They will then send bundles they produce to their peer's socket. The following minimal header is applied to each UDP transaction

Version	Node ID	Flags	Reserved
uint8_t	uint8_t	uint8_t	uint8_t

Serial Transport

For serial communication, proton expects the bundles to be framed:

| Magic 0 | Magic 1 | Length | Payload |  CRC16 |
|---|---|---|---|---|
| uint8_t (0x50) | uint8_t (0x52) | uint16_t | `Length` bytes | uint16_t |

• Magic bytes: 0x50 0x52 ("PR") for synchronization
• Length: 16-bit payload length (allows up to 65535 bytes)
• Payload: Serialized proton bundle
• CRC16: 16-bit cyclic redundancy check for error detection

The proton libraries provide useful helper functions for framing, calculating CRC, and validating received data.

Which Version of Proton is Right For Me?

Proton 2 is the currently developed version, but if you are running Clearpath release Jazzy 2.9 specifically to talk to Clearpath MCU's, use Proton 1.