94 lines
3.3 KiB
ReStructuredText
94 lines
3.3 KiB
ReStructuredText
=============================================
|
||
Nanopb: Protocol Buffers with small code size
|
||
=============================================
|
||
|
||
Nanopb is an ANSI-C library for encoding and decoding messages in Google's `Protocol Buffers`__ format with minimal requirements for RAM and code space.
|
||
It is primarily suitable for 32-bit microcontrollers.
|
||
|
||
__ http://code.google.com/apis/protocolbuffers/
|
||
|
||
Overall structure
|
||
=================
|
||
|
||
For the runtime program, you always need *pb.h* for type declarations.
|
||
Depending on whether you want to encode, decode or both, you also need *pb_encode.h/c* or *pb_decode.h/c*.
|
||
|
||
The high-level encoding and decoding functions take an array of *pb_field_t* structures, which describes the fields of a message structure. Usually you want these autogenerated from a *.proto* file. The tool string *nanopb_generator.py* accomplishes this.
|
||
|
||
So a typical project might include these files:
|
||
|
||
1) Nanopb runtime library:
|
||
- pb.h
|
||
- pb_decode.h and pb_decode.c
|
||
- pb_encode.h and pb_encode.c
|
||
2) Protocol description (you can have many):
|
||
- person.proto
|
||
- person.c (autogenerated, contains initializers for const arrays)
|
||
- person.h (autogenerated, contains type declarations)
|
||
|
||
Features and limitations
|
||
========================
|
||
|
||
**Features**
|
||
|
||
#) Pure C runtime
|
||
#) Small code size (2–10 kB depending on processor)
|
||
#) Small ram usage (typically 200 bytes)
|
||
#) Allows specifying maximum size for strings and arrays, so that they can be allocated statically.
|
||
#) No malloc needed: everything is stored on the stack.
|
||
#) You can use either encoder or decoder alone to cut the code size in half.
|
||
|
||
**Limitations**
|
||
|
||
#) User must provide callbacks when decoding arrays or strings without maximum size.
|
||
#) Some speed has been sacrificed for code size. For example varint calculations are always done in 64 bits.
|
||
#) Encoding is focused on writing to streams. For memory buffers only it could be made more efficient.
|
||
#) The deprecated Protocol Buffers feature called "groups" is not supported.
|
||
#) Fields in the generated structs are ordered by the tag number, instead of the natural ordering in .proto file.
|
||
|
||
Getting started
|
||
===============
|
||
|
||
For starters, consider this simple message::
|
||
|
||
message Example {
|
||
required int32 value = 1;
|
||
}
|
||
|
||
Save this in *example.proto* and run it through *nanopb_generate.py*. You
|
||
should now have in *example.h*::
|
||
|
||
typedef struct {
|
||
int32_t value;
|
||
} Example;
|
||
|
||
extern const pb_field_t Example_fields[2];
|
||
|
||
Now in your main program do this to encode a message::
|
||
|
||
Example mymessage = {42};
|
||
uint8_t buffer[10];
|
||
pb_ostream_t stream = pb_ostream_from_buffer(buffer, sizeof(buffer));
|
||
pb_encode(&stream, Example_fields, &mymessage);
|
||
|
||
After that, buffer will contain the encoded message.
|
||
The number of bytes in the message is stored in *stream.bytes_written*.
|
||
You can feed the message to *protoc --decode=Example example.proto* to verify its validity.
|
||
|
||
Library reference
|
||
=================
|
||
|
||
**Encoding**
|
||
|
||
**Decoding**
|
||
|
||
**Specifying field options**
|
||
|
||
**Generated code**
|
||
|
||
Wishlist
|
||
========
|
||
#) A specialized encoder for encoding to a memory buffer. Should serialize in reverse order to avoid having to determine submessage size beforehand.
|
||
#) A cleaner rewrite of the source generator.
|
||
#) Better performance for 16- and 8-bit platforms: use smaller datatypes where possible.
|