Started writing documentation
git-svn-id: https://svn.kapsi.fi/jpa/nanopb@953 e3a754e5-d11d-0410-8d38-ebb782a927b9
This commit is contained in:
Petteri Aimonen
4
docs/Makefile
Normal file
4
docs/Makefile
Normal file
@@ -0,0 +1,4 @@
|
||||
all: index.html
|
||||
|
||||
%.html: %.rst
|
||||
rst2html --stylesheet=lsr.css --link-stylesheet $< $@
|
||||
92
docs/index.rst
Normal file
92
docs/index.rst
Normal file
@@ -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.
|
||||
231
docs/lsr.css
Normal file
231
docs/lsr.css
Normal file
@@ -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;
|
||||
}
|
||||
Reference in New Issue
Block a user