1Nanopb - Protocol Buffers for Embedded Systems 2============================================== 3 4[](https://travis-ci.com/nanopb/nanopb) 5 6Nanopb is a small code-size Protocol Buffers implementation in ansi C. It is 7especially suitable for use in microcontrollers, but fits any memory 8restricted system. 9 10* **Homepage:** https://jpa.kapsi.fi/nanopb/ 11* **Documentation:** https://jpa.kapsi.fi/nanopb/docs/ 12* **Downloads:** https://jpa.kapsi.fi/nanopb/download/ 13* **Forum:** https://groups.google.com/forum/#!forum/nanopb 14* **Nightly builds:** https://jpa.kapsi.fi/jenkins/job/nanopb/ 15 16 17Using the nanopb library 18------------------------ 19To use the nanopb library, you need to do two things: 20 211. Compile your .proto files for nanopb, using `protoc`. 222. Include *pb_encode.c*, *pb_decode.c* and *pb_common.c* in your project. 23 24The easiest way to get started is to study the project in "examples/simple". 25It contains a Makefile, which should work directly under most Linux systems. 26However, for any other kind of build system, see the manual steps in 27README.txt in that folder. 28 29 30Generating the headers 31---------------------- 32Protocol Buffers messages are defined in a `.proto` file, which follows a standard 33format that is compatible with all Protocol Buffers libraries. To use it with nanopb, 34you need to generate `.pb.c` and `.pb.h` files from it: 35 36 python generator/nanopb_generator.py myprotocol.proto # For source checkout 37 generator-bin/nanopb_generator myprotocol.proto # For binary package 38 39(Note: For instructions for nanopb-0.3.9.x and older, see the documentation 40of that particular version [here](https://github.com/nanopb/nanopb/blob/maintenance_0.3/README.md)) 41 42The binary packages for Windows, Linux and Mac OS X should contain all necessary 43dependencies, including Python, python-protobuf library and protoc. If you are 44using a git checkout or a plain source distribution, you will need to install 45Python separately. Once you have Python, you can install the other dependencies 46with `pip install protobuf grpcio-tools`. 47 48You can further customize the header generation by creating an `.options` file. 49See [documentation](https://jpa.kapsi.fi/nanopb/docs/concepts.html#modifying-generator-behaviour) for details. 50 51 52Running the tests 53----------------- 54If you want to perform further development of the nanopb core, or to verify 55its functionality using your compiler and platform, you'll want to run the 56test suite. The build rules for the test suite are implemented using Scons, 57so you need to have that installed (ex: `sudo apt install scons` or `pip install scons`). 58To run the tests: 59 60 cd tests 61 scons 62 63This will show the progress of various test cases. If the output does not 64end in an error, the test cases were successful. 65 66Note: Mac OS X by default aliases 'clang' as 'gcc', while not actually 67supporting the same command line options as gcc does. To run tests on 68Mac OS X, use: `scons CC=clang CXX=clang`. Same way can be used to run 69tests with different compilers on any platform. 70 71For embedded platforms, there is currently support for running the tests 72on STM32 discovery board and [simavr](https://github.com/buserror/simavr) 73AVR simulator. Use `scons PLATFORM=STM32` and `scons PLATFORM=AVR` to run 74these tests. 75 76 77Build systems and integration 78----------------------------- 79Nanopb C code itself is designed to be portable and easy to build 80on any platform. Often the bigger hurdle is running the generator which 81takes in the `.proto` files and outputs `.pb.c` definitions. 82 83There exist build rules for several systems: 84 85* **Makefiles**: `extra/nanopb.mk`, see `examples/simple` 86* **CMake**: `extra/FindNanopb.cmake`, see `examples/cmake` 87* **SCons**: `tests/site_scons` (generator only) 88* **Bazel**: `BUILD` in source root 89* **Conan**: `conanfile.py` in source root 90* **PlatformIO**: https://platformio.org/lib/show/431/Nanopb 91* **PyPI/pip**: https://pypi.org/project/nanopb/ 92 93And also integration to platform interfaces: 94 95* **Arduino**: http://platformio.org/lib/show/1385/nanopb-arduino 96 97Building nanopb - Using vcpkg 98----------------------------- 99 100You can download and install nanopb using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager: 101 102 git clone https://github.com/Microsoft/vcpkg.git 103 cd vcpkg 104 ./bootstrap-vcpkg.sh 105 ./vcpkg integrate install 106 ./vcpkg install nanopb 107 108The nanopb port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository. 109
){kind=link}