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 string *nanopb_generator.py* accomplishes this.
  19
  20 So a typical project might include these files:
  21
  22 1) Nanopb runtime library:
  23     - pb.h
  24     - pb_decode.h and pb_decode.c
  25     - pb_encode.h and pb_encode.c
  26 2) Protocol description (you can have many):
  27     - person.proto
  28     - person.c (autogenerated, contains initializers for const arrays)
  29     - person.h (autogenerated, contains type declarations)
  30
  31 Features and limitations
  32 ========================
  33
  34 **Features**
  35
  36 #) Pure C runtime
  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.
  42
  43 **Limitations**
  44
  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.
  51 #) 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.
  52
  53 Getting started
  54 ===============
  55
  56 For starters, consider this simple message::
  57
  58  message Example {
  59     required int32 value = 1;
  60  }
  61
  62 Save this in *example.proto* and compile it::
  63
  64     user@host:~$ protoc -omessage.pb message.proto
  65     user@host:~$ python ../generator/nanopb_generator.py message.pb
  66
  67 You should now have in *example.h*::
  68
  69  typedef struct {
  70     int32_t value;
  71  } Example;
  72
  73  extern const pb_field_t Example_fields[2];
  74
  75 Now in your main program do this to encode a message::
  76
  77  Example mymessage = {42};
  78  uint8_t buffer[10];
  79  pb_ostream_t stream = pb_ostream_from_buffer(buffer, sizeof(buffer));
  80  pb_encode(&stream, Example_fields, &mymessage);
  81
  82 After that, buffer will contain the encoded message.
  83 The number of bytes in the message is stored in *stream.bytes_written*.
  84 You can feed the message to *protoc --decode=Example example.proto* to verify its validity.
  85
  86 Debugging and testing
  87 =====================
  88 Extensive unittests are included under the *tests* folder. Just type *make* there to run the tests.
  89
  90 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.
  91
  92 Wishlist
  93 ========
  94 #) A specialized encoder for encoding to a memory buffer. Should serialize in reverse order to avoid having to determine submessage size beforehand.
  95 #) A cleaner rewrite of the Python-based source generator.
  96 #) Better performance for 16- and 8-bit platforms: use smaller datatypes where possible.