bproto/README.md

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

Currently the easiest way to run the bproto-compiler is via run_docker_compiler.py. For that you need docker (Install Docker) and python (Install Python).

Running the compiler:

./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:

• 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.

Protocol Description

A protocol is described in a .bproto file.

Example Protocol for an imaginary aircraft:

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.

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