# Starting with Protobufs

## What are protobufs?

[Protocol Buffers](https://protobuf.dev/programming-guides/proto3/)<span style="white-space: pre-wrap;"> (protobufs) are a way to define structured messages in </span>`<span class="editor-theme-code">.proto</span>`<span style="white-space: pre-wrap;"> files.</span>

The point is simple: define the message format once, generate code for your language, and now everyone agrees what the bytes mean (without inventing a new packet format every semester).

## Where they live

<span style="white-space: pre-wrap;">The source of truth for RoboTeam message definitions is: </span>[RoboTeamTwente/ERC-Protobufs](https://github.com/RoboTeamTwente/ERC-Protobufs).

<span style="white-space: pre-wrap;">Other repositories (embedded, software, tooling) should </span>**consume**<span style="white-space: pre-wrap;"> these definitions (often via a git submodule) instead of copy-pasting </span>`<span class="editor-theme-code">.proto</span>`<span style="white-space: pre-wrap;"> files around.</span>

## Editing rules (the important part)

### Field numbers are the real API

<span style="white-space: pre-wrap;">In protobuf, the </span>**field number**<span style="white-space: pre-wrap;"> is what goes on the wire. Renaming a field is usually harmless; changing its number is usually the problem.</span>

**Never renumber an existing field**<span style="white-space: pre-wrap;"> unless you are intentionally breaking compatibility and coordinating the update across all consumers.</span>

### Safe changes (usually)

- <span style="white-space: pre-wrap;">Add a new field with a </span>**new**<span style="white-space: pre-wrap;"> unused number.</span>
- Add new enum values (don’t reuse old numeric values for new meanings).
- Stop using a field before deleting it, and reserve its number if your style guide does that.

### Changes that need extra care

- <span style="white-space: pre-wrap;">Changing a field type (e.g. </span>`<span class="editor-theme-code">int32</span>`<span style="white-space: pre-wrap;"> → </span>`<span class="editor-theme-code">string</span>`).
- Changing semantics/units (mm vs m, degrees vs radians).

## Typical workflow

1. <span style="white-space: pre-wrap;">Edit / add </span>`<span class="editor-theme-code">.proto</span>`<span style="white-space: pre-wrap;"> files in </span>`<span class="editor-theme-code">ERC-Protobufs</span>`.
2. Generate / update code as required by your project (this step is repo-specific).
3. Update consumers to use the new fields (and handle missing fields safely).
4. Test at least one real send/receive path.
5. Open a PR that lists: what changed, field numbers, and compatibility expectations.

## Troubleshooting

### “My message doesn’t parse”

- <span style="white-space: pre-wrap;">Confirm both sides use the same (or compatible) </span>`<span class="editor-theme-code">.proto</span>`<span style="white-space: pre-wrap;"> definitions.</span>
- Check field numbers: no reuse, no renumbering.
- Check transport framing (length prefix / delimiter / CRC). Protobuf gives bytes; transport still matters.

### “It parses, but values are nonsense”

- Check units and semantics (the most common “it’s wrong but not broken” bug).
- Make sure generated code is up to date (stale generated files cause creative failures).

<p class="callout info">Protobufs are boring on purpose. Boring schemas prevent exciting debugging sessions. Keep changes small, reviewable, and compatible.</p>