# Protobuffers

## What are Protobuffers?

<span style="white-space: pre-wrap;">Protocol Buffers (Protobuffers or protobufs) are Google's binary serialization format for 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 rover's subsystems. They are also strongly typed and language-agnostic, the same </span>`<span class="editor-theme-code">.proto</span>`<span style="white-space: pre-wrap;"> definition can generate code for C++, Python, Rust, and others. For a general introduction, refer to the official documentation: </span>  
[https://protobuf.dev/overview/](https://protobuf.dev/overview/)

## The ERC-Protobufs Repository

<span style="white-space: pre-wrap;">All protobuf definitions used by the rover live in a shared repository called </span>**ERC-Protobufs**<span style="white-space: pre-wrap;">, which is used as a dependency across the rover's software stack. You can find it linked from the </span>[Starting with Protobufs](https://bookstack.roboteamtwente.nl/books/communication-system/page/starting-with-protobufs "Starting with Protobufs")<span style="white-space: pre-wrap;"> page.</span>

<span style="white-space: pre-wrap;">The repository is organized under a </span>`<span class="editor-theme-code">components/</span>`<span style="white-space: pre-wrap;"> folder, where each subfolder groups messages by the hardware board or subsystem they belong to:</span>

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

<span style="white-space: pre-wrap;">For example, </span>`<span class="editor-theme-code">components/basestation/detected_object.proto</span>`<span style="white-space: pre-wrap;"> contains the message definition for a single YOLO-detected object sent from Jonny Boi to the Basestation. Placing it under </span>`<span class="editor-theme-code">basestation/</span>`<span style="white-space: pre-wrap;"> makes its intended direction and purpose immediately clear.</span>

## Naming Conventions

<span style="white-space: pre-wrap;">Every message name in the repository must be </span>**globally unique**, regardless of which folder it lives in. This is because proto3 imports reference files by path, but message names exist in a flat global namespace, two messages with the same name will cause build failures.

The convention used across the rover is to prefix every message name with its component:

- `<span class="editor-theme-code">ArmBoardControlSignals</span>`
- `<span class="editor-theme-code">BasestationControlMode</span>`
- `<span class="editor-theme-code">SensorBoardIMUInfo</span>`
- `<span class="editor-theme-code">DrivingBoardMotorMessage</span>`

Follow this convention strictly when adding new messages.

## How Protobufs are Compiled

<span style="white-space: pre-wrap;">The </span>`<span class="editor-theme-code">comms</span>`<span style="white-space: pre-wrap;"> package does not manually clone ERC-Protobufs. Instead, CMake fetches it automatically at build time using </span>`<span class="editor-theme-code">FetchContent</span>`<span style="white-space: pre-wrap;">, pinned to a specific commit hash in </span>`<span class="editor-theme-code">CMakeLists.txt</span>`:

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

<span style="white-space: pre-wrap;">Once fetched, </span>`<span class="editor-theme-code">protoc</span>`<span style="white-space: pre-wrap;"> generates </span>`<span class="editor-theme-code">.pb.h</span>`<span style="white-space: pre-wrap;"> and </span>`<span class="editor-theme-code">.pb.cc</span>`<span style="white-space: pre-wrap;"> files into the build directory, which are then compiled into the </span>`<span class="editor-theme-code">comms</span>`<span style="white-space: pre-wrap;"> node. This means that whenever new proto files are added to ERC-Protobufs and committed, the </span>`<span class="editor-theme-code">GIT_TAG</span>`<span style="white-space: pre-wrap;"> in </span>`<span class="editor-theme-code">CMakeLists.txt</span>`<span style="white-space: pre-wrap;"> must be updated to the new commit hash before the changes will be picked up by the build. The full procedure is covered in the </span>**Adding a New Message**<span style="white-space: pre-wrap;"> page.</span>

## The PBEnvelope

<span style="white-space: pre-wrap;">All protobuf messages on this rover are wrapped inside a </span>`<span class="editor-theme-code">PBEnvelope</span>`<span style="white-space: pre-wrap;"> before being transmitted over UDP. The 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 </span>[PBEnvelope](https://bookstack.roboteamtwente.nl/books/jonny-boi/page/pbenvelope "PBEnvelope")<span style="white-space: pre-wrap;"> page for a full explanation.</span>

## <span style="white-space: pre-wrap;"></span>