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 __ http://code.google.com/apis/protocolbuffers/
  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_decode.h and pb_decode.c (needed for decoding messages)
  27     - pb_encode.h and pb_encode.c (needed for encoding messages)
  28 2) Protocol description (you can have many):
  29     - person.proto (just an example)
  30     - person.pb.c (autogenerated, contains initializers for const arrays)
  31     - person.pb.h (autogenerated, contains type declarations)
  32
  33 Features and limitations
  34 ========================
  35
  36 **Features**
  37
  38 #) Pure C runtime
  39 #) Small code size (2–10 kB depending on processor)
  40 #) Small ram usage (typically 200 bytes)
  41 #) Allows specifying maximum size for strings and arrays, so that they can be allocated statically.
  42 #) No malloc needed: everything can be allocated statically or on the stack.
  43 #) You can use either encoder or decoder alone to cut the code size in half.
  44
  45 **Limitations**
  46
  47 #) User must provide callbacks when decoding arrays or strings without maximum size. Malloc support could be added as a separate module.
  48 #) Some speed has been sacrificed for code size. For example varint calculations are always done in 64 bits.
  49 #) Encoding is focused on writing to streams. For memory buffers only it could be made more efficient.
  50 #) The deprecated Protocol Buffers feature called "groups" is not supported.
  51 #) Fields in the generated structs are ordered by the tag number, instead of the natural ordering in .proto file.
  52 #) Unknown fields are not preserved when decoding and re-encoding a message.
  53 #) Reflection (runtime introspection) is not supported. E.g. you can't request a field by giving its name in a string.
  54 #) Numeric arrays are always encoded as packed, even if not marked as packed in .proto. This causes incompatibility with decoders that do not support packed format.
  55 #) Cyclic references between messages are not supported. They could be supported in callback-mode if there was an option in the generator to set the mode.
  56
  57 Getting started
  58 ===============
  59
  60 For starters, consider this simple message::
  61
  62  message Example {
  63     required int32 value = 1;
  64  }
  65
  66 Save this in *message.proto* and compile it::
  67
  68     user@host:~$ protoc -omessage.pb message.proto
  69     user@host:~$ python nanopb/generator/nanopb_generator.py message.pb
  70
  71 You should now have in *message.pb.h*::
  72
  73  typedef struct {
  74     int32_t value;
  75  } Example;
  76
  77  extern const pb_field_t Example_fields[2];
  78
  79 Now in your main program do this to encode a message::
  80
  81  Example mymessage = {42};
  82  uint8_t buffer[10];
  83  pb_ostream_t stream = pb_ostream_from_buffer(buffer, sizeof(buffer));
  84  pb_encode(&stream, Example_fields, &mymessage);
  85
  86 After that, buffer will contain the encoded message.
  87 The number of bytes in the message is stored in *stream.bytes_written*.
  88 You can feed the message to *protoc --decode=Example message.proto* to verify its validity.
  89
  90 For complete examples of the simple cases, see *tests/test_decode1.c* and *tests/test_encode1.c*. For an example with network interface, see the *example* subdirectory.
  91
  92 Compiler requirements
  93 =====================
  94 Nanopb should compile with most ansi-C compatible compilers. It however requires a few header files to be available:
  95
  96 #) *string.h*, with these functions: *strlen*, *memcpy*, *memset*
  97 #) *stdint.h*, for definitions of *int32_t* etc.
  98 #) *stddef.h*, for definition of *size_t*
  99 #) *stdbool.h*, for definition of *bool*
 100
 101 If these header files do not come with your compiler, you should be able to find suitable replacements online. Mostly the requirements are very simple, just a few basic functions and typedefs.
 102
 103 Debugging and testing
 104 =====================
 105 Extensive unittests are included under the *tests* folder. Just type *make* there to run the tests.
 106
 107 This also generates a file called *breakpoints* which includes all lines returning *false* in nanopb. You can use this in gdb by typing *source breakpoints*, after which gdb will break on first nanopb error.
 108
 109 Wishlist
 110 ========
 111 #) A specialized encoder for encoding to a memory buffer. Should serialize in reverse order to avoid having to determine submessage size beforehand.
 112 #) A cleaner rewrite of the Python-based source generator.
 113 #) Better performance for 16- and 8-bit platforms: use smaller datatypes where possible.