1 =============================================
2 Nanopb: Protocol Buffers with small code size
3 =============================================
7 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.
8 It is primarily suitable for 32-bit microcontrollers.
10 __ http://code.google.com/apis/protocolbuffers/
15 For the runtime program, you always need *pb.h* for type declarations.
16 Depending on whether you want to encode, decode or both, you also need *pb_encode.h/c* or *pb_decode.h/c*.
18 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.
20 So a typical project might include these files:
22 1) Nanopb runtime library:
24 - pb_decode.h and pb_decode.c
25 - pb_encode.h and pb_encode.c
26 2) Protocol description (you can have many):
28 - person.c (autogenerated, contains initializers for const arrays)
29 - person.h (autogenerated, contains type declarations)
31 Features and limitations
32 ========================
37 #) Small code size (2–10 kB depending on processor)
38 #) Small ram usage (typically 200 bytes)
39 #) Allows specifying maximum size for strings and arrays, so that they can be allocated statically.
40 #) No malloc needed: everything is stored on the stack.
41 #) You can use either encoder or decoder alone to cut the code size in half.
45 #) User must provide callbacks when decoding arrays or strings without maximum size. Malloc support could be added as a separate module.
46 #) Some speed has been sacrificed for code size. For example varint calculations are always done in 64 bits.
47 #) Encoding is focused on writing to streams. For memory buffers only it could be made more efficient.
48 #) The deprecated Protocol Buffers feature called "groups" is not supported.
49 #) Fields in the generated structs are ordered by the tag number, instead of the natural ordering in .proto file.
50 #) Unknown fields are not preserved when decoding and re-encoding a message.
55 For starters, consider this simple message::
58 required int32 value = 1;
61 Save this in *example.proto* and compile it::
63 user@host:~$ protoc -omessage.pb message.proto
64 user@host:~$ python ../generator/nanopb_generator.py message.pb
66 You should now have in *example.h*::
72 extern const pb_field_t Example_fields[2];
74 Now in your main program do this to encode a message::
76 Example mymessage = {42};
78 pb_ostream_t stream = pb_ostream_from_buffer(buffer, sizeof(buffer));
79 pb_encode(&stream, Example_fields, &mymessage);
81 After that, buffer will contain the encoded message.
82 The number of bytes in the message is stored in *stream.bytes_written*.
83 You can feed the message to *protoc --decode=Example example.proto* to verify its validity.
87 #) A specialized encoder for encoding to a memory buffer. Should serialize in reverse order to avoid having to determine submessage size beforehand.
88 #) A cleaner rewrite of the Python-based source generator.
89 #) Better performance for 16- and 8-bit platforms: use smaller datatypes where possible.