docs/index.rst

   1 =============================================
   2 Nanopb: Protocol Buffers with small code size
   3 =============================================
   4
   5 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.
   6 It is primarily suitable for 32-bit microcontrollers.
   7
   8 __ http://code.google.com/apis/protocolbuffers/
   9
  10 Overall structure
  11 =================
  12
  13 For the runtime program, you always need *pb.h* for type declarations.
  14 Depending on whether you want to encode, decode or both, you also need *pb_encode.h/c* or *pb_decode.h/c*.
  15
  16 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.
  17
  18 So a typical project might include these files:
  19
  20 1) Nanopb runtime library:
  21     - pb.h
  22     - pb_decode.h and pb_decode.c
  23     - pb_encode.h and pb_encode.c
  24 2) Protocol description (you can have many):
  25     - person.proto
  26     - person.c (autogenerated, contains initializers for const arrays)
  27     - person.h (autogenerated, contains type declarations)
  28
  29 Features and limitations
  30 ========================
  31
  32 **Features**
  33
  34 #) Pure C runtime
  35 #) Small code size (2–10 kB depending on processor)
  36 #) Small ram usage (typically 200 bytes)
  37 #) Allows specifying maximum size for strings and arrays, so that they can be allocated statically.
  38 #) No malloc needed: everything is stored on the stack.
  39 #) You can use either encoder or decoder alone to cut the code size in half.
  40
  41 **Limitations**
  42
  43 #) User must provide callbacks when decoding arrays or strings without maximum size.
  44 #) Some speed has been sacrificed for code size. For example varint calculations are always done in 64 bits.
  45 #) Encoding is focused on writing to streams. For memory buffers only it could be made more efficient.
  46 #) The deprecated Protocol Buffers feature called "groups" is not supported.
  47 #) Fields in the generated structs are ordered by the tag number, instead of the natural ordering in .proto file.
  48
  49 Getting started
  50 ===============
  51
  52 For starters, consider this simple message::
  53
  54  message Example {
  55     required int32 value = 1;
  56  }
  57
  58 Save this in *example.proto* and run it through *nanopb_generate.py*. You
  59 should now have in *example.h*::
  60
  61  typedef struct {
  62     int32_t value;
  63  } Example;
  64
  65  extern const pb_field_t Example_fields[2];
  66
  67 Now in your main program do this to encode a message::
  68
  69  Example mymessage = {42};
  70  uint8_t buffer[10];
  71  pb_ostream_t stream = pb_ostream_from_buffer(buffer, sizeof(buffer));
  72  pb_encode(&stream, Example_fields, &mymessage);
  73
  74 After that, buffer will contain the encoded message.
  75 The number of bytes in the message is stored in *stream.bytes_written*.
  76 You can feed the message to *protoc --decode=Example example.proto* to verify its validity.
  77
  78 Library reference
  79 =================
  80
  81 **Encoding**
  82
  83 **Decoding**
  84
  85 **Specifying field options**
  86
  87 **Generated code**
  88
  89 Wishlist
  90 ========
  91 #) A specialized encoder for encoding to a memory buffer. Should serialize in reverse order to avoid having to determine submessage size beforehand.
  92 #) A cleaner rewrite of the source generator.
  93 #) Better performance for 16- and 8-bit platforms: use smaller datatypes where possible.