1 ============================================= 2 Nanopb: Protocol Buffers with small code size 3 ============================================= 4 5 .. include :: menu.rst 6 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. 9 10 __ https://developers.google.com/protocol-buffers/docs/reference/overview 11 12 Overall structure 13 ================= 14 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*. 17 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 script *nanopb_generator.py* accomplishes this. 19 20 .. image:: generator_flow.png 21 22 So a typical project might include these files: 23 24 1) Nanopb runtime library: 25 - pb.h 26 - pb_common.h and pb_common.c (always needed) 27 - pb_decode.h and pb_decode.c (needed for decoding messages) 28 - pb_encode.h and pb_encode.c (needed for encoding messages) 29 2) Protocol description (you can have many): 30 - person.proto (just an example) 31 - person.pb.c (autogenerated, contains initializers for const arrays) 32 - person.pb.h (autogenerated, contains type declarations) 33 34 Features and limitations 35 ======================== 36 37 **Features** 38 39 #) Pure C runtime 40 #) Small code size (210 kB depending on processor, plus any message definitions) 41 #) Small ram usage (typically ~300 bytes, plus any message structs) 42 #) Allows specifying maximum size for strings and arrays, so that they can be allocated statically. 43 #) No malloc needed: everything can be allocated statically or on the stack. Optional malloc support available. 44 #) You can use either encoder or decoder alone to cut the code size in half. 45 #) Support for most protobuf features, including: all data types, nested submessages, default values, repeated and optional fields, oneofs, packed arrays, extension fields. 46 #) Callback mechanism for handling messages larger than can fit in available RAM. 47 #) Extensive set of tests. 48 49 **Limitations** 50 51 #) Some speed has been sacrificed for code size. 52 #) Encoding is focused on writing to streams. For memory buffers only it could be made more efficient. 53 #) The deprecated Protocol Buffers feature called "groups" is not supported. 54 #) Fields in the generated structs are ordered by the tag number, instead of the natural ordering in .proto file. 55 #) Unknown fields are not preserved when decoding and re-encoding a message. 56 #) Reflection (runtime introspection) is not supported. E.g. you can't request a field by giving its name in a string. 57 #) Numeric arrays are always encoded as packed, even if not marked as packed in .proto. 58 #) Cyclic references between messages are supported only in callback and malloc mode. 59 60 Getting started 61 =============== 62 63 For starters, consider this simple message:: 64 65 message Example { 66 required int32 value = 1; 67 } 68 69 Save this in *message.proto* and compile it:: 70 71 user@host:~$ protoc -omessage.pb message.proto 72 user@host:~$ python nanopb/generator/nanopb_generator.py message.pb 73 74 You should now have in *message.pb.h*:: 75 76 typedef struct { 77 int32_t value; 78 } Example; 79 80 extern const pb_field_t Example_fields[2]; 81 82 Now in your main program do this to encode a message:: 83 84 Example mymessage = {42}; 85 uint8_t buffer[10]; 86 pb_ostream_t stream = pb_ostream_from_buffer(buffer, sizeof(buffer)); 87 pb_encode(&stream, Example_fields, &mymessage); 88 89 After that, buffer will contain the encoded message. 90 The number of bytes in the message is stored in *stream.bytes_written*. 91 You can feed the message to *protoc --decode=Example message.proto* to verify its validity. 92 93 For a complete example of the simple case, see *example/simple.c*. 94 For a more complex example with network interface, see the *example/network_server* subdirectory. 95 96 Compiler requirements 97 ===================== 98 Nanopb should compile with most ansi-C compatible compilers. It however 99 requires a few header files to be available: 100 101 #) *string.h*, with these functions: *strlen*, *memcpy*, *memset* 102 #) *stdint.h*, for definitions of *int32_t* etc. 103 #) *stddef.h*, for definition of *size_t* 104 #) *stdbool.h*, for definition of *bool* 105 106 If these header files do not come with your compiler, you can use the 107 file *extra/pb_syshdr.h* instead. It contains an example of how to provide 108 the dependencies. You may have to edit it a bit to suit your custom platform. 109 110 To use the pb_syshdr.h, define *PB_SYSTEM_HEADER* as *"pb_syshdr.h"* (including the quotes). 111 Similarly, you can provide a custom include file, which should provide all the dependencies 112 listed above. 113 114 Running the test cases 115 ====================== 116 Extensive unittests and test cases are included under the *tests* folder. 117 118 To build the tests, you will need the `scons`__ build system. The tests should 119 be runnable on most platforms. Windows and Linux builds are regularly tested. 120 121 __ http://www.scons.org/ 122 123 In addition to the build system, you will also need a working Google Protocol 124 Buffers *protoc* compiler, and the Python bindings for Protocol Buffers. On 125 Debian-based systems, install the following packages: *protobuf-compiler*, 126 *python-protobuf* and *libprotobuf-dev*. 127 128
