This crate provides a thin "library layer" used by the code generated by micropb-gen. Its main purpose is to provide traits and APIs for encoding and decoding Protobuf messages.

For info on the generated code, see micropb-gen.

Decoder and Encoder

micropb does not force a specific implementation for Protobuf data streams. Instead, streams are represented as the PbRead and PbWrite traits, similar to Read and Write from the standard library.

In addition, micropb provides PbDecoder and PbEncoder, which wrap input and output streams respectively. Their job is to read and write the generated Rust types into Protobuf data streams.

Message traits

Rust message structs generated by micropb-gen all implement MessageDecode and MessageEncode, which provide logic to read or write the message onto the data stream.

use micropb::{PbRead, PbDecoder, PbWrite, PbEncoder, MessageEncode, MessageDecode};
use micropb::heapless::Vec;

#
#

// ProtoMessage was generated by micropb
let mut message = ProtoMessage::default();
                                                                                                                                      
// Create decoder out of a byte slice, which is our input data stream
let data = [0x08, 0x96, 0x01, /* additional bytes */];
let mut decoder = PbDecoder::new(data.as_slice());
// Decode an instance of `ProtoMessage` from the decoder
message.decode(&mut decoder, data.len()).unwrap();
// Or, decode directly from the bytes
message.decode_from_bytes(data.as_slice()).unwrap();

// Use heapless::Vec as the output stream and build an encoder around it
let mut output = Vec::<u8, 16>::new();
let mut encoder = PbEncoder::new(&mut output);
// Encode a `ProtoMessage` to the encoder
message.encode(&mut encoder).unwrap();

Container Traits

micropb provides several options out of the box for handling "collection fields" that have multiple elements, such as strings and repeated fields. These include containers from heapless and arrayvec, as well as the ol' reliable [Vec], String, and Cow for environments with allocators.

However, if you need to use your own container types, you'll have to implement the traits in the container module yourself. For more info on configuring container types, refer to the micropb-gen docs.

Feature Flags

• encode: Enable support for encoding and computing the size of messages. If disabled, the generator should be configured to not generate encoding logic via Generator::encode_decode. Enabled by default.

• decode: Enable support for decoding messages. If disabled, the generator should be configured to not generate decoding logic via Generator::encode_decode. Enabled by default.

• enable-64bit: Enable 64-bit integer operations. If disabled, then 64-bit fields such as int64 or sint64 should have Config::int_size set to 32 bits or less. Has no effect on double fields. Enabled by default.

• alloc: Implements container traits on Vec, String, and BTreeMap from alloc, allowing them to be used as container fields. Corresponds with Generator::use_container_alloc from micropb-gen.

• std: Enables standard library and implements PbMap on HashMap. Corresponds with Generator::use_container_std from micropb-gen.

• container-heapless: Implements container traits on Vec, String, and IndexMap from heapless, allowing them to be used as container fields. Corresponds with Generator::use_container_heapless from micropb-gen.

• container-arrayvec: Implements container traits on ArrayVec and ArrayString from arrayvec, allowing them to be used as container fields. Corresponds with Generator::use_container_arrayvec from micropb-gen.