123 lines
4.7 KiB
Markdown
123 lines
4.7 KiB
Markdown
# bproto
|
||
_binarized protocol_
|
||
|
||
A protocol description language for generating lightweight, binary formats optimized for embedded systems and constrained environments.
|
||
|
||
Bproto is a transpiler from the bproto format to a target language. Unlike protobuf and JSON, bproto focuses on creating highly efficient binary formats suitable for constrained environments.
|
||
|
||
bproto is designed to be statically typed and sized. No memory allocation is needed for serialization and deserialization, making it suitable for embedded systems and real-time applications.
|
||
|
||
**bproto supports:**
|
||
- Numerical, Floating-point, and Boolean datatypes
|
||
- Fixed-size arrays and strings
|
||
- Enums and Bitfields
|
||
|
||
**bproto does not support:**
|
||
- Variable-length arrays or strings
|
||
- Nested messages
|
||
- Optional fields
|
||
|
||
**Current supported Targets: C, Python**
|
||
|
||
Planned support: Markdown Documentation, TypeScript/Deno
|
||
|
||
## Getting Start
|
||
|
||
For Beginners have a look at the [Getting Started Guide](/docs/getting_started.md)
|
||
|
||
Currently the easiest way to run the bproto-compiler is via `run_docker_compiler.py`.
|
||
For that you need docker ([Install Docker](https://docs.docker.com/engine/install/)) and python ([Install Python](https://www.python.org/downloads/)).
|
||
|
||
Running the compiler:
|
||
```bash
|
||
./run_docker_compiler.py --input protocol_description_file.bproto --output output_folder/ --target txt --target python --target c
|
||
```
|
||
|
||
This will compile the `protocol_description_file.bproto` to `txt`, `python` and `c`. The output is placed in `output_folder/`
|
||
|
||
This use the `alexanderhd27/bproto-compiler:latest` docker image
|
||
|
||
### Running it nativ
|
||
|
||
You need python3.12.
|
||
1. Install the python requirements with `pip install -r requirements.txt`
|
||
2. Running the compiler with
|
||
```
|
||
--input protocol_description_file.bproto --output output_folder/ --target txt --target python --target c
|
||
```
|
||
|
||
IMPORTANTED: You need to run the compiler from `protocolGenerator` directory, such that the compiler has access to template folder
|
||
|
||
## Core concept
|
||
|
||
How does bproto work? There are three main components:
|
||
|
||
<img src="docs/img/bprotoDocumentationGraphics.drawio.png" alt="Diagram showing the flow from the protocol definition via the bproto-compiler to the protocol implementation (C and Python)" width="600px">
|
||
|
||
<br>
|
||
|
||
- **Protocol Description** – A structured definition of the binary format, specifying message types, field layouts, and encoding rules.
|
||
- **bproto-Compiler** – Translates the protocol description into optimized source code, generating efficient serializers and deserializers.
|
||
- **Protocol Implementation (aka the target)** – The generated code and supporting files that implement the described protocol, ready for integration into (embedded) applications.
|
||
|
||
<br>
|
||
|
||
## Protocol Description
|
||
|
||
A protocol is described in a .bproto file.
|
||
|
||
Example Protocol for an imaginary aircraft:
|
||
```bproto
|
||
protocol myCustomAirplaneProtocol version 2
|
||
|
||
enum engine_status {
|
||
OFF = 0,
|
||
IDLE = 1,
|
||
RUNNING = 2,
|
||
FULL_THRUST = 3
|
||
}
|
||
|
||
bits engine_enables {
|
||
engine_left, engine_right
|
||
}
|
||
|
||
// Message or Package sent from engine to cockpit engine display
|
||
message [1] EngineSensorData {
|
||
[0] engine_thrust_left : float32,
|
||
[1] engine_thrust_right : float32,
|
||
[2] fuel_tanks_fill : uint32[8], // Fill levels of 8 fuel tanks
|
||
[3] engine_fault_left : bool,
|
||
[4] engine_fault_right : bool
|
||
}
|
||
|
||
// Message or Package sent from cockpit to the engine controller
|
||
message [2] EngineCtrlCommand {
|
||
[0] engine_status : enum engine_status,
|
||
[1] engine_enables : bits engine_enables,
|
||
[2] flaps : int8,
|
||
[3] rudder : float64,
|
||
[4] trim : int16
|
||
}
|
||
```
|
||
(this is just an example. bproto should NOT be used in an airplane or any system that can cause harm)
|
||
|
||
More about bproto's syntax can be found in the [syntax documentation](/docs/syntax.md).
|
||
|
||
### Core Description Elements:
|
||
|
||
- **Protocol Tag Line** – First Line of every protocol description. Defines the protocol name and version. It establishes the protocol's identity and ensures compatibility across protocol implementations.
|
||
- **Message** – A data structure designed to be sent over the wire. It contains fields with specific types and orders, representing the data to be transmitted.
|
||
- **Enum** – A set of named integer values that represent discrete states or options. Enums enhance code clarity by using descriptive names instead of raw numeric values.
|
||
- **Bitfields** – A compact representation of multiple boolean flags within a single byte or group of bytes, optimizing space for binary communication.
|
||
|
||
Bitfields and Enums can also be declared inline in messages.
|
||
|
||
Syntax documentation details can be found here!
|
||
|
||
## Tooling/Versions for testing
|
||
gcc: 11.4.0
|
||
gcov: 11.4.0
|
||
gcovr: 5.0
|
||
|
||
|