1.. _nanopb_reference:
2
3Nanopb
4######
5
6`Nanopb <https://jpa.kapsi.fi/nanopb/>`_ is a C implementation of Google's
7`Protocol Buffers <https://protobuf.dev/>`_.
8
9Requirements
10************
11
12Nanopb uses the protocol buffer compiler to generate source and header files,
13make sure the ``protoc`` executable is installed and available.
14
15.. tabs::
16
17   .. group-tab:: Ubuntu
18
19      Use ``apt`` to install dependency:
20
21         .. code-block:: shell
22
23            sudo apt install protobuf-compiler
24
25   .. group-tab:: macOS
26
27      Use ``brew`` to install dependency:
28
29         .. code-block:: shell
30
31            brew install protobuf
32
33   .. group-tab:: Windows
34
35      Use ``choco`` to install dependency:
36
37         .. code-block:: shell
38
39            choco install protoc
40
41
42Additionally, Nanopb is an optional module and needs to be added explicitly to the workspace:
43
44.. code-block:: shell
45
46   west config manifest.project-filter -- +nanopb
47   west update
48   west packages pip --install
49
50Configuration
51*************
52
53Make sure to include ``nanopb`` within your ``CMakeLists.txt`` file as follows:
54
55.. code-block:: cmake
56
57   list(APPEND CMAKE_MODULE_PATH ${ZEPHYR_BASE}/modules/nanopb)
58   include(nanopb)
59
60Adding ``proto`` files can be done with the ``zephyr_nanopb_sources()`` CMake function which
61ensures the generated header and source files are created before building the specified target.
62
63Nanopb has `generator options <https://jpa.kapsi.fi/nanopb/docs/reference.html#generator-options>`_
64that can be used to configure messages or fields. This allows to set fixed sizes or skip fields
65entirely.
66
67The internal CMake generator has an extension to configure ``*.options.in`` files automatically
68with CMake variables.
69
70See :zephyr_file:`samples/modules/nanopb/src/simple.options.in` and
71:zephyr_file:`samples/modules/nanopb/CMakeLists.txt` for usage example.
72