From 09f92bafa59460ea4597c557e469e982386c9e3b Mon Sep 17 00:00:00 2001 From: Petteri Aimonen Date: Wed, 10 Aug 2011 20:08:06 +0000 Subject: [PATCH] Started writing documentation git-svn-id: https://svn.kapsi.fi/jpa/nanopb@953 e3a754e5-d11d-0410-8d38-ebb782a927b9 --- docs/Makefile | 4 + docs/index.rst | 92 +++++++++++++++++++++++ docs/lsr.css | 231 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ pb.h | 2 +- 4 files changed, 328 insertions(+), 1 deletion(-) create mode 100644 docs/Makefile create mode 100644 docs/index.rst create mode 100644 docs/lsr.css diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..e4cac27d --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,4 @@ +all: index.html + +%.html: %.rst + rst2html --stylesheet=lsr.css --link-stylesheet $< $@ \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..93b06e86 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,92 @@ +============================================= +Nanopb: Protocol Buffers with small code size +============================================= + +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/ + +Overall structure +================= + +For the runtime program, you always need *pb.h* for type declarations. +Depending on whether you want to encode, decode or both, you also need *pb_encode.h/c* or *pb_decode.h/c*. + +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. + +So a typical project might include these files: + +1) Nanopb runtime library: + - pb.h + - pb_decode.h and pb_decode.c + - pb_encode.h and pb_encode.c +2) Protocol description (you can have many): + - person.proto + - person.c (autogenerated, contains initializers for const arrays) + - person.h (autogenerated, contains type declarations) + +Features and limitations +======================== + +**Features** + +#) Pure C runtime +#) Small code size (2–10 kB depending on processor) +#) Small ram usage (typically 200 bytes) +#) Allows specifying maximum size for strings and arrays, so that they can be allocated statically. +#) No malloc needed: everything is stored on the stack. +#) You can use either encoder or decoder alone to cut the code size in half. + +**Limitations** + +#) User must provide callbacks when decoding arrays or strings without maximum size. +#) Some speed has been sacrificed for code size. For example varint calculations are always done in 64 bits. +#) 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. + +Getting started +=============== + +For starters, consider this simple message:: + + message Example { + required int32 value = 1; + } + +Save this in *example.proto* and run it through *nanopb_generate.py*. You +should now have in *example.h*:: + + typedef struct { + int32_t value; + } Example; + + extern const pb_field_t Example_fields[2]; + +Now in your main program do this to encode a message:: + + Example mymessage = {42}; + uint8_t buffer[10]; + pb_ostream_t stream = pb_ostream_from_buffer(buffer, sizeof(buffer)); + pb_encode(&stream, Example_fields, &mymessage); + +After that, buffer will contain the encoded message. +The number of bytes in the message is stored in *stream.bytes_written*. +You can feed the message to *protoc --decode=Example example.proto* to verify its validity. + +Library reference +================= + +**Encoding** + +**Decoding** + +**Specifying field options** + +**Generated code** + +Wishlist +======== +#) A specialized encoder for encoding to a memory buffer. Should serialize in reverse order to avoid having to determine submessage size beforehand. +#) A cleaner rewrite of the source generator. +#) Better performance for 16- and 8-bit platforms. diff --git a/docs/lsr.css b/docs/lsr.css new file mode 100644 index 00000000..758b231b --- /dev/null +++ b/docs/lsr.css @@ -0,0 +1,231 @@ +/* +Author: Peter Parente +Date: 2008/01/22 +Version: 1.0 (modified) +Copyright: This stylesheet has been placed in the public domain - free to edit and use for all uses. +*/ + +body { + font: 100% sans-serif; + background: #ffffff; + color: black; + margin: 2em; + padding: 0em 2em; +} + +p.topic-title { + font-weight: bold; +} + +table.docinfo { + text-align: left; + margin: 2em 0em; +} + +a[href] { + color: #436976; + background-color: transparent; +} + +a.toc-backref { + text-decoration: none; +} + +h1 a[href] { + color: #003a6b; + text-decoration: none; + background-color: transparent; +} + +a.strong { + font-weight: bold; +} + +img { + margin: 0; + border: 0; +} + +p { + margin: 0.5em 0 1em 0; + line-height: 1.5em; +} + +p a:visited { + color: purple; + background-color: transparent; +} + +p a:active { + color: red; + background-color: transparent; +} + +a:hover { + text-decoration: none; +} + +p img { + border: 0; + margin: 0; +} + +p.rubric { + font-weight: bold; + font-style: italic; +} + +em { + font-style: normal; + font-family: monospace; + font-weight: bold; +} + +pre { + border-left: 3px double #aaa; + padding-left: 10px; +} + +h1.title { + color: #003a6b; + font-size: 250%; + margin-bottom: 0em; +} + +h2.subtitle { + color: #003a6b; + border-bottom: 0px; +} + +h1, h2, h3, h4, h5, h6 { + color: #555; + background-color: transparent; + margin: 0em; + padding-top: 0.5em; +} + +h1 { + font-size: 160%; + margin-bottom: 0.5em; + border-bottom: 2px solid #aaa; +} + +h2 { + font-size: 140%; + margin-bottom: 0.5em; + border-bottom: 1px solid #aaa; +} + +h3 { + font-size: 130%; + margin-bottom: 0.5em; +} + +h4 { + font-size: 110%; + font-weight: bold; + margin-bottom: 0.5em; +} + +h5 { + font-size: 105%; + font-weight: bold; + margin-bottom: 0.5em; +} + +h6 { + font-size: 100%; + font-weight: bold; + margin-bottom: 0.5em; +} + +dt { + font-style: italic; +} + +dd { + margin-bottom: 1.5em; +} + +div.admonition, div.note, div.tip, div.caution, div.important { + margin: 2em 2em; + padding: 0em 1em; + border-top: 1px solid #aaa; + border-left: 1px solid #aaa; + border-bottom: 2px solid #555; + border-right: 2px solid #555; +} + +div.important { + background: transparent url('../images/important.png') 10px 2px no-repeat; +} + +div.caution { + background: transparent url('../images/caution.png') 10px 2px no-repeat; +} + +div.note { + background: transparent url('../images/note.png') 10px 2px no-repeat; +} + +div.tip { + background: transparent url('../images/tip.png') 10px 2px no-repeat; +} + +div.admonition-example { + background: transparent url('../images/tip.png') 10px 2px no-repeat; +} + +div.admonition-critical-example { + background: transparent url('../images/important.png') 10px 2px no-repeat; +} + +p.admonition-title { + font-weight: bold; + border-bottom: 1px solid #aaa; + padding-left: 30px; +} + +table.docutils { + text-align: left; + border: 1px solid gray; + border-collapse: collapse; + width: 100%; + margin: 1.5em 0em; +} + +table.docutils caption { + font-style: italic; +} + +table.docutils td, table.docutils th { + padding: 0.25em 0.5em; +} + +table.docutils th { + background-color: #dddddd; +} + +div.sidebar { + width: 33%; + float: right; + margin: 0em 2em; + padding: 0em 1em; + border-top: 1px solid #aaa; + border-left: 1px solid #aaa; + border-bottom: 2px solid #555; + border-right: 2px solid #555; +} + +p.sidebar-title { + margin-bottom: 0em; + color: #003a6b; + border-bottom: 1px solid #aaa; + font-weight: bold; +} + +p.sidebar-subtitle { + margin-top: 0em; + font-style: italic; + color: #003a6b; +} diff --git a/pb.h b/pb.h index 46d7c2ce..1d32ee9b 100644 --- a/pb.h +++ b/pb.h @@ -12,7 +12,7 @@ #define pb_packed #endif -/* Wire types */ +/* Wire types. Library user needs these only in encoder callbacks. */ typedef enum { PB_WT_VARINT = 0, PB_WT_64BIT = 1, -- 2.16.6