Protobuf Plugin

Source code on GitHub.

This plugin enables communication via protobuf through protobuf_comm, a C++ library to handle communication via Protocol Buffers (protobuf) using a simple framing protocol.

NOTE

This Plugin relies on protobuf_comm and thus is subject to the GPLv2+ license.

Configuration

• pkg_share_dirs: | Type | Default | |—————|———–| | string vector | [] |

  Description

  When specifying relative paths, look at the share directories of the listed packages to resolve them (in the specified order).

• proto_paths: | Type | Default | |—————|———–| | string vector | [] |

  Description

  Location to directories containing .proto files. The messages found in the given directories are registered automatically for usage. Supports absolute paths or relative paths using the share directories specified above.

Features

The utilized protobuf_comm library (de)-serializes proto using a framing protocol that other communication endpoints therefore need to adhere to, as well. Refer to it’s documentation to get details on the layout of the frame headers.

It requires messages using proto2 syntax that additionally define a CompType enum acting as a unique identifier (using a tmple COMP_ID and MESSAGE_TYPE. An example message is depicted below:

message SearchRequest {
  enum CompType {
    COMP_ID = 100;
    MSG_TYPE = 1;
  }
  required string query = 1;
}

Messages can be exchanged either via establishing TCP Client-Server connections or via UDP broadcast peers.

Registering Messages

Messages need to be registered before they can be used. The easiest way is to utilize the configuration options to specify directories that host proto definitions (.proto files). This automatically registers all found messages when the plugin is loaded in a CLIPS environment.

It is also possible to instead register types explicitly by looking them up from a linked library. However, this requires to build a shared library from proto files and then link it together with the cx_protobuf_plugin plugin, creating a new linked plugin.

In order to accomplish this, this plugin offers two cmake macros:

# Generates a new plugin called NEW_PLUGIN_NAME (should be a name in CamelCase, e.g., CustomProtobufPlugin) given a list of protobuf message definitions PROTO_FILES.
cx_generate_linked_protobuf_plugin_from_proto(NEW_PLUGIN_NAME PROTO_FILES)
# Generates a new plugin called NEW_PLUGIN_NAME (should be a name in CamelCase, e.g., CustomProtobufPlugin) given a shared library that is linked against via target_link_libraries().
cx_generate_linked_protobuf_plugin_from_lib(NEW_PLUGIN_NAME SHARED_LIBRARY_TARGET)

Facts

```clips ; Asserted whenever a message is received (deftemplate protobuf-msg (slot type (type STRING)) ; (package + “.” +) message-name (slot comp-id (type INTEGER)) (slot msg-type (type INTEGER)) (slot rcvd-via (type SYMBOL) (allowed-values STREAM BROADCAST) ) (multislot rcvd-from ; address and port (cardinality 2 2) ) (slot rcvd-at (type FLOAT)) ; ros timestamp in seconds (slot client-type (type SYMBOL) (allowed-values SERVER CLIENT PEER) ) (slot client-id (type INTEGER)) (slot ptr (type EXTERNAL-ADDRESS)) )

; Asserted whenever a message handled by a client could not be processed (deftemplate protobuf-receive-failed (slot comp-id (type INTEGER)) (slot msg-type (type INTEGER)) (slot rcvd-via (type SYMBOL) (allowed-values STREAM BROADCAST) ) (multislot rcvd-from (cardinality 2 2)) (slot client-id (type INTEGER))

File truncated at 100 lines see the full file

Changelog for package cx_protobuf_plugin

0.1.3 (2025-08-06)

• 0.1.3
• project: remove occurrences of pkgconfig (it is not used)
• Contributors: Tarik Viehmann

0.1.2 (2025-07-16)

0.1.1 (2025-07-11)

• project: prepare for first ros2 release
• Contributors: Tarik Viehmann