From 73142ba082e56b8c5ba75c055a20c200b623da83 Mon Sep 17 00:00:00 2001
From: Petteri Aimonen <jpa@git.mail.kapsi.fi>
Date: Fri, 13 Sep 2013 13:35:25 +0300
Subject: [PATCH] Add a new very simple example
---
docs/index.rst | 29 ++++++++++++++-----
examples/simple/Makefile | 22 ++++++++++++++
examples/simple/README | 30 +++++++++++++++++++
examples/simple/simple.c | 68 ++++++++++++++++++++++++++++++++++++++++++++
examples/simple/simple.proto | 7 +++++
5 files changed, 149 insertions(+), 7 deletions(-)
create mode 100644 examples/simple/Makefile
create mode 100644 examples/simple/README
create mode 100644 examples/simple/simple.c
create mode 100644 examples/simple/simple.proto
diff --git a/docs/index.rst b/docs/index.rst
index e56ff4c..27840f7 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 0000000..2be3a04
--- /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 0000000..d18c418
--- /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 0000000..3127230
--- /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 0000000..26e72f4
--- /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;
+}
+
--
2.16.6