diff options
| -rw-r--r-- | docs/index.rst | 29 | ||||
| -rw-r--r-- | examples/simple/Makefile | 22 | ||||
| -rw-r--r-- | examples/simple/README | 30 | ||||
| -rw-r--r-- | examples/simple/simple.c | 68 | ||||
| -rw-r--r-- | examples/simple/simple.proto | 7 |
5 files changed, 149 insertions, 7 deletions
diff --git a/docs/index.rst b/docs/index.rst index e56ff4cc..27840f7d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -90,22 +90,37 @@ 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 message.proto* to verify its validity. -For complete examples of the simple cases, see *tests/test_decode1.c* and *tests/test_encode1.c*. For an example with network interface, see the *example* subdirectory. +For a complete example of the simple case, see *example/simple.c*. +For a more complex example with network interface, see the *example/network_server* subdirectory. Compiler requirements ===================== -Nanopb should compile with most ansi-C compatible compilers. It however requires a few header files to be available: +Nanopb should compile with most ansi-C compatible compilers. It however +requires a few header files to be available: #) *string.h*, with these functions: *strlen*, *memcpy*, *memset* #) *stdint.h*, for definitions of *int32_t* etc. #) *stddef.h*, for definition of *size_t* #) *stdbool.h*, for definition of *bool* -If these header files do not come with your compiler, you should be able to find suitable replacements online. Mostly the requirements are very simple, just a few basic functions and typedefs. +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 +the dependencies. You may have to edit it a bit to suit your custom platform. -Alternatively, you can define *PB_SYSTEM_HEADER*, which should be the name of a single header file including all the necessary definitions. +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. -Debugging and testing -===================== -Extensive unittests are included under the *tests* folder. Just type *make* there to run the tests. +Running the test cases +====================== +Extensive unittests and test cases are included under the *tests* folder. + +To build the tests, you will need the `scons`__ build system. The tests should +be runnable on most platforms. Windows and Linux builds are regularly tested. + +__ http://www.scons.org/ + +In addition to the build system, you will also need a working Google Protocol +Buffers *protoc* compiler, and the Python bindings for Protocol Buffers. On +Debian-based systems, install the following packages: *protobuf-compiler*, +*python-protobuf* and *libprotobuf-dev*. diff --git a/examples/simple/Makefile b/examples/simple/Makefile new file mode 100644 index 00000000..2be3a047 --- /dev/null +++ b/examples/simple/Makefile @@ -0,0 +1,22 @@ +# Compiler flags to enable all warnings & debug info +CFLAGS = -Wall -Werror -g -O0 + +# Path to the nanopb root folder +NANOPB_DIR = ../.. +CFLAGS += -I$(NANOPB_DIR) + +# C source code files that are required +CSRC = simple.c # The main program +CSRC += simple.pb.c # The compiled protocol definition +CSRC += $(NANOPB_DIR)/pb_encode.c # The nanopb encoder +CSRC += $(NANOPB_DIR)/pb_decode.c # The nanopb decoder + +# Build rule for the main program +simple: $(CSRC) + $(CC) $(CFLAGS) -osimple $(CSRC) + +# Build rule for the protocol +simple.pb.c: simple.proto + protoc -osimple.pb simple.proto + python $(NANOPB_DIR)/generator/nanopb_generator.py simple.pb + diff --git a/examples/simple/README b/examples/simple/README new file mode 100644 index 00000000..d18c4183 --- /dev/null +++ b/examples/simple/README @@ -0,0 +1,30 @@ +Nanopb example "simple" +======================= + +This example demonstrates the very basic use of nanopb. It encodes and +decodes a simple message. + +The code uses four different API functions: + + * pb_ostream_from_buffer() to declare the output buffer that is to be used + * pb_encode() to encode a message + * pb_istream_from_buffer() to declare the input buffer that is to be used + * pb_decode() to decode a message + +Example usage +------------- + +On Linux, simply type "make" to build the example. After that, you can +run it with the command: ./simple + +On other platforms, you first have to compile the protocol definition using +the following two commands:: + + protoc -osimple.pb simple.proto + python nanopb_generator.py simple.pb + +After that, add the following four files to your project and compile: + + simple.c simple.pb.c pb_encode.c pb_decode.c + + diff --git a/examples/simple/simple.c b/examples/simple/simple.c new file mode 100644 index 00000000..31272301 --- /dev/null +++ b/examples/simple/simple.c @@ -0,0 +1,68 @@ +#include <stdio.h> +#include <pb_encode.h> +#include <pb_decode.h> +#include "simple.pb.h" + +int main() +{ + /* This is the buffer where we will store our message. */ + uint8_t buffer[128]; + size_t message_length; + bool status; + + /* Encode our message */ + { + /* Allocate space on the stack to store the message data. + * + * Nanopb generates simple struct definitions for all the messages. + * - check out the contents of simple.pb.h! */ + SimpleMessage message; + + /* Create a stream that will write to our buffer. */ + pb_ostream_t stream = pb_ostream_from_buffer(buffer, sizeof(buffer)); + + /* Fill in the lucky number */ + message.lucky_number = 13; + + /* Now we are ready to encode the message! */ + status = pb_encode(&stream, SimpleMessage_fields, &message); + message_length = stream.bytes_written; + + /* Then just check for any errors.. */ + if (!status) + { + printf("Encoding failed: %s\n", PB_GET_ERROR(&stream)); + return 1; + } + } + + /* Now we could transmit the message over network, store it in a file or + * wrap it to a pigeon's leg. + */ + + /* But because we are lazy, we will just decode it immediately. */ + + { + /* Allocate space for the decoded message. */ + SimpleMessage message; + + /* Create a stream that reads from the buffer. */ + pb_istream_t stream = pb_istream_from_buffer(buffer, message_length); + + /* Now we are ready to decode the message. */ + status = pb_decode(&stream, SimpleMessage_fields, &message); + + /* Check for errors... */ + if (!status) + { + printf("Decoding failed: %s\n", PB_GET_ERROR(&stream)); + return 1; + } + + /* Print the data contained in the message. */ + printf("Your lucky number was %d!\n", message.lucky_number); + } + + return 0; +} + diff --git a/examples/simple/simple.proto b/examples/simple/simple.proto new file mode 100644 index 00000000..26e72f46 --- /dev/null +++ b/examples/simple/simple.proto @@ -0,0 +1,7 @@ +// A very simple protocol definition, consisting of only +// one message. + +message SimpleMessage { + required int32 lucky_number = 1; +} + |