How Meshtastic Protobuf Data structure works

Published on: December 03, 2024

A little delve into how Meshtastic internal and telemetry data structure works using Protocol Buffers (protobufs)

Meshtastic uses Protobufs to define and serialize structured data exchanged between devices in the mesh network. These messages are organized into different modules, each handling specific types of data.

Why use Protobufs?

Advantages of using Protobufs in Meshtastic Efficiency: Protobufs are more compact and faster than XML or JSON, making them suitable for resource-constrained environments.
Cross-Platform Support: Protobuf supports multiple programming languages, facilitating integration into different parts of the Meshtastic system.
Schema Evolution: Protobuf allows for forward and backward compatibility, ensuring that updates to the message structure do not break existing systems.
Compact Binary Format: Protobuf uses a binary format, reducing the size of the data and improving performance.
Conclusion Protocol Buffers play a crucial role in the Meshtastic project by providing a robust and efficient way to define and serialize messages. This ensures reliable communication between nodes in the mesh network, even in challenging environments.

Below shows example data and how its grouped, to hopefully give you a little more understanding of whats going on under the hood.

NodeInfo:

Contains information on the actual node its unique ID and given username plus unique use settings.

id: A unique identifier for each node, typically a string representing the node's unique address or ID.
user: A human-readable name for the node, which can be set by the user.
battery_level: The current battery level of the node, usually represented as a percentage.
location: The geographical location of the node, using a nested message Location.
is_primary: A boolean flag indicating if this node is the primary node in the network.

Simplified Code Summery example

proto
                        message NodeInfo {

                        string id = 1; 	// Unique identifier for the node

                        string user = 2; 	// User-defined name for the node 

                        int32 battery_level = 3; 	// Battery level of the node

                        Location location = 4; 	// Location of the node (if available)

                        bool is_primary = 5; 	// Flag indicating if this node is the primary node

                        }

EnvironmentalMeasurement:

Contains environmental Telemetry data from the node and accessory modules, useful for weather monitoring, data logging.

temperature: Measures the ambient temperature in degrees Celsius.
humidity: Indicates the relative humidity percentage.
pressure: Represents the atmospheric pressure in hectopascals (hPa).
altitude: Measures the altitude above sea level in meters.
speed: Indicates the speed of the node in meters per second.
heading: Shows the direction or heading in degrees (0 to 360).
dop: Dilution of Precision value, indicating the quality of the GPS signal.

Simplified Code Summery example


                    message EnvironmentalMeasurement {

                    double temperature = 1;     	// Temperature in Celsius

                    double humidity = 2;        	// Humidity percentage

                    double pressure = 3;        	// Atmospheric pressure in hPa

                    double altitude = 4;        	// Altitude in meters

                    double speed = 5;           	// Speed in meters per second

                    double heading = 6;        	 // Heading in degrees

                    double dop = 7;             	// Dilution of Precision (DOP) value

                    }

channel:

Contains Frequency, Bandwidth Modulation and Spreading Factor, power level etc.

channel: The specific channel number used for communication within the mesh network.
frequency: The operating frequency of the channel, measured in MHz.
power_level: The power level at which the channel operates, usually represented in dBm.
modulation: The type of modulation used for communication, such as "LoRa" or "FSK".
bandwidth: The bandwidth used for communication, measured in kilohertz (kHz).
spreading_factor: The spreading factor used for LoRa modulation, which affects data rate and range.
coding_rate: The coding rate for error correction, which improves the reliability of data transmission.
preamble_length: The length of the preamble, which helps in synchronization of the signal.
enable_crc: A boolean flag indicating whether Cyclic Redundancy Check (CRC) is enabled for error detection.

Simplified Code Summery example


                        message ChannelConfig {
                            int32 channel = 1;	      // Channel number

                            int32 frequency = 2;	        // Operating frequency

                            int32 power_level = 3;	      // Power level

                            string modulation = 4;	      // Modulation type (e.g., "LoRa", "FSK")

                            int32 bandwidth = 5;	        // Bandwidth in kHz

                            int32 spreading_factor = 6;	 // Spreading factor for LoRa modulation

                            int32 coding_rate = 7;	      // Coding rate for error correction

                            int32 preamble_length = 8;	  // Length of the preamble

                            bool enable_crc = 9;	        // Flag to enable/disable CRC

                          }

Message:

All the data associated with sending messages its routing to, via and from other nodes.

sender_id: The unique identifier of the node that sent the message.
recipient_id: The unique identifier of the node that is intended to receive the message.
content: The actual content of the message, which can be text, data, or any other format.
timestamp: The time at which the message was sent, usually represented as a Unix timestamp.
hop_count: The number of hops the message has taken from the sender to the recipient.
priority: The priority level of the message, which can determine its importance in the network.
is_encrypted: A boolean flag indicating if the message content is encrypted.

Simplified Code Summery example


                        Proto Message {
                            string sender_id = 1;       	// ID of the sender node

                            string recipient_id = 2;    	// ID of the recipient node

                            string content = 3;         	// Content of the message

                            int64 timestamp = 4;        	// Timestamp when the message was sent

                            int32 hop_count = 5;        	// Number of hops the message has taken

                            int32 priority = 6;         	// Priority level of the message

                            bool is_encrypted = 7;      	// Flag indicating if the message is encrypted

                          }

PositionConfig:

A big part of meshtastic is its ability to report its position either from on-board satellite navigation module or connected mobile phone.

longitude: The longitude of the node, measured in degrees.
latitude: The latitude of the node, measured in degrees.
altitude: The altitude of the node, measured in meters.
speed: The speed of the node, measured in meters per second.
heading: The heading or direction of the node, measured in degrees.
dop: The Dilution of Precision (DOP) value, indicating the quality of the GPS signal.
fix_quality: A string describing the quality of the GPS fix, such as "2D Fix", "3D Fix", etc.

Simplified Code Summery example


                        message PositionConfig {
                            double longitude = 1;	       // Longitude in degrees

                            double latitude = 2;	        // Latitude in degrees

                            double altitude = 3;	        // Altitude in meters

                            double speed = 4;	           // Speed in meters per second

                            double heading = 5;	         // Heading in degrees

                            double dop = 6;	             // Dilution of Precision (DOP) value

                            string fix_quality = 7;	    // Quality of the GPS fix

                        }

RadioConfig:

Configuration settings for the LoRa radio module, frequency, power, channel max hops etc.

frequency: The frequency at which the radio module operates, typically measured in MHz.
power_level: The power level at which the radio module transmits signals, usually represented as a percentage.
channel: The specific channel used for communication within the mesh network.
hop_limit: The maximum number of hops a message can take in the network.
is_enabled: A boolean flag indicating if the radio is enabled or disabled.

Simplified Code Summery example


                        message RadioConfig {
                            int32 frequency = 1;        	// Operating frequency of the radio

                            int32 power_level = 2;      	// Power level of the radio

                            int32 channel = 3;          	// Channel used for communication

                            int32 hop_limit = 4;        	// Maximum number of hops for a message

                            bool is_enabled = 5;        	// Flag indicating if the radio is enabled

                          }

The blog is intended just to give Meshtastic users an overview on the structure its not aimed at programers I sugeest they look at the official documentation on the Meshtastic github.

More info for serious programmers

Meshtastic Protobuf official github