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.
It is primarily suitable for 32-bit microcontrollers.
-__ http://code.google.com/apis/protocolbuffers/
+__ https://developers.google.com/protocol-buffers/docs/reference/overview
Overall structure
=================
1) Nanopb runtime library:
- pb.h
+ - pb_common.h and pb_common.c (always needed)
- pb_decode.h and pb_decode.c (needed for decoding messages)
- pb_encode.h and pb_encode.c (needed for encoding messages)
2) Protocol description (you can have many):
#) Small code size (2–10 kB depending on processor, plus any message definitions)
#) Small ram usage (typically ~300 bytes, plus any message structs)
#) Allows specifying maximum size for strings and arrays, so that they can be allocated statically.
-#) No malloc needed: everything can be allocated statically or on the stack.
+#) No malloc needed: everything can be allocated statically or on the stack. Optional malloc support available.
#) You can use either encoder or decoder alone to cut the code size in half.
-#) Support for most protobuf features, including: all data types, nested submessages, default values, repeated and optional fields, packed arrays, extension fields.
+#) Support for most protobuf features, including: all data types, nested submessages, default values, repeated and optional fields, oneofs, packed arrays, extension fields.
#) Callback mechanism for handling messages larger than can fit in available RAM.
#) Extensive set of tests.
**Limitations**
-#) User must provide callbacks when decoding arrays or strings without maximum size. Malloc support could be added as a separate module.
#) Some speed has been sacrificed for code size.
#) Encoding is focused on writing to streams. For memory buffers only it could be made more efficient.
#) The deprecated Protocol Buffers feature called "groups" is not supported.
#) Fields in the generated structs are ordered by the tag number, instead of the natural ordering in .proto file.
#) Unknown fields are not preserved when decoding and re-encoding a message.
#) Reflection (runtime introspection) is not supported. E.g. you can't request a field by giving its name in a string.
-#) 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.
-#) Cyclic references between messages are supported only in callback mode.
+#) Numeric arrays are always encoded as packed, even if not marked as packed in .proto.
+#) Cyclic references between messages are supported only in callback and malloc mode.
Getting started
===============
#) *stdbool.h*, for definition of *bool*
If these header files do not come with your compiler, you can use the
-file *compat/pb_syshdr.h* instead. It contains an example of how to provide
+file *extra/pb_syshdr.h* instead. It contains an example of how to provide
the dependencies. You may have to edit it a bit to suit your custom platform.
-To use the pb_syshdr.h, define *PB_SYSTEM_HEADER* to be the name of your custom
-header file. It should provide all the dependencies listed above.
+To use the pb_syshdr.h, define *PB_SYSTEM_HEADER* as *"pb_syshdr.h"* (including the quotes).
+Similarly, you can provide a custom include file, which should provide all the dependencies
+listed above.
Running the test cases
======================
Code Review / apps / agl-service-can-low-level.git / blobdiff