libs/nanopb/docs/index.rst

   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 (2–10 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