Protobuffers

What are Protobuffers?

Keep this short — one paragraph explaining that Protocol Buffers (Protobuffers or protobufs) are Google's binary serialization format,format whyfor structured data. Compared to alternatives like JSON or XML, they are significantly more compact and faster to serialize/deserialize, making them well-suited for real-time communication between the teamrover's chosesubsystems. themThey (compact,are fast, language-agnostic,also strongly typed),typed and linklanguage-agnostic — the same .proto definition can generate code for C++, Python, Rust, and others. For a general introduction, refer to the official documentation: https://protobuf.dev/overview/

The ERC-Protobufs Repository

Explain that allAll protobuf definitions used by the rover live in a shared repository called ERC-Protobufs,Protobufs, which is used as a submoduledependency across the rover's software stack. LinkYou tocan find it linked from the repo.Starting Explainwith theProtobufs folderpage.

structure

The —repository is organized under a components/board_name/ —folder, andwhere whyeach subfolder groups messages are organized by the hardware board or subsystem they belong toto:

(e.g.

components/
  arm_board/
  driving_board/
  sensor_board/
  container_board/
  basestation/
  common/

components/arm_board/,For example, components/basestation/detected_object.proto). contains the message definition for a single YOLO-detected object sent from Jonny Boi to the Basestation. Placing it under basestation/ makes its intended direction and purpose immediately clear.

Naming Conventions

This is important enough to call out explicitly. Every message name in the repository must be globally unique across the entire repo, regardless of folder,which folder it lives in. This is because proto3 imports usereference filenamefiles pathsby andpath, but message names exist in a flat global namespace — two messages with the same name collisionswill cause build failures.

The convention used across the rover is to prefix withevery the componentmessage name —with its component:

• ArmBoardControlSignals,
• BasestationControlMode,
• SensorBoardIMUInfo
• DrivingBoardMotorMessage

etc.

Follow this convention strictly when adding new messages.

How Protobufs are Compiled

Briefly explain that theThe comms package does not manually clone ERC-Protobufs. Instead, CMake fetches ERC-Protobufsit automatically at build time via CMake'susing FetchContent, pinned to a specific commit hash.hash in CMakeLists.txt:

FetchContent_Declare(
  erc_protobufs
  GIT_REPOSITORY https://github.com/RoboTeamTwente/ERC-Protobufs.git
  GIT_TAG <commit_hash>
)

Once fetched, protoc then generates .pb.h and .pb.cc files into the build directory.directory, Mentionwhich are then compiled into the comms node. This means that whenwhenever new protosproto files are added to ERC-Protobufs,Protobufs and committed, the GIT_TAG in CMakeLists.txt needs tomust be updated to the new commit —hash link tobefore the "changes will be picked up by the build. The full procedure is covered in the Adding a New Message"Message page for the full procedure.page.

The PBEnvelope

One short paragraph: allAll protobuf messages on this rover are wrapped inside a PBEnvelope before being senttransmitted over UDP. LinkThe PBEnvelope acts as a typed container that allows the receiver to identify which type of message is inside before deserializing the payload. See the dedicated PBEnvelope page for thea full explanation.