doc: services: serialization: Add Nanopb entry

Move part of the Nanopb sample documentation to a serialization entry and add information on how to configure proto files. Signed-off-by: Pieter De Gendt <[email protected]>
go2sh · Mar 1, 2024 · 6c273f5 · 6c273f5
1 parent 44e8123
commit 6c273f5
Show file tree

Hide file tree

Showing 4 changed files with 98 additions and 36 deletions.
diff --git a/doc/services/index.rst b/doc/services/index.rst
@@ -29,6 +29,7 @@ OS Services
    portability/index.rst
    poweroff.rst
    shell/index.rst
+   serialization/index.rst
    settings/index.rst
    smf/index.rst
    storage/index.rst

diff --git a/doc/services/serialization/index.rst b/doc/services/serialization/index.rst
@@ -0,0 +1,12 @@
+.. _seialization_reference:
+
+Serialization
+#############
+
+Zephyr has support for several data serialization subsystems. These can be used to encode/decode
+structured data with a known format on-the-wire.
+
+.. toctree::
+   :maxdepth: 1
+
+   nanopb.rst
diff --git a/doc/services/serialization/nanopb.rst b/doc/services/serialization/nanopb.rst
@@ -0,0 +1,70 @@
+.. _nanopb_reference:
+
+Nanopb
+######
+
+`Nanopb <https://jpa.kapsi.fi/nanopb/>`_ is a C implementation of Google's
+`Protocol Buffers <https://protobuf.dev/>`_.
+
+Requirements
+************
+
+Nanopb uses the protocol buffer compiler to generate source and header files,
+make sure the ``protoc`` executable is installed and available.
+
+.. tabs::
+
+   .. group-tab:: Ubuntu
+
+      Use ``apt`` to install dependency:
+
+         .. code-block:: shell
+
+            sudo apt install protobuf-compiler
+
+   .. group-tab:: macOS
+
+      Use ``brew`` to install dependency:
+
+         .. code-block:: shell
+
+            brew install protobuf
+
+   .. group-tab:: Windows
+
+      Use ``choco`` to install dependency:
+
+         .. code-block:: shell
+
+            choco install protoc
+
+
+Additionally, Nanopb is an optional module and needs to be added explicitly to the workspace:
+
+.. code-block:: shell
+
+   west config manifest.project-filter -- +nanopb
+   west update
+
+Configuration
+*************
+
+Make sure to include ``nanopb`` within your ``CMakeLists.txt`` file as follows:
+
+.. code-block:: cmake
+
+   list(APPEND CMAKE_MODULE_PATH ${ZEPHYR_BASE}/modules/nanopb)
+   include(nanopb)
+
+Adding ``proto`` files can be done with the ``zephyr_nanopb_sources()`` CMake function which
+ensures the generated header and source files are created before building the specified target.
+
+Nanopb has `generator options <https://jpa.kapsi.fi/nanopb/docs/reference.html#generator-options>`_
+that can be used to configure messages or fields. This allows to set fixed sizes or skip fields
+entirely.
+
+The internal CMake generator has an extension to configure ``*.options.in`` files automatically
+with CMake variables.
+
+See :zephyr_file:`samples/modules/nanopb/src/simple.options.in` and
+:zephyr_file:`samples/modules/nanopb/CMakeLists.txt` for usage example.
diff --git a/samples/modules/nanopb/README.rst b/samples/modules/nanopb/README.rst
@@ -6,50 +6,29 @@ Nanopb sample
 Overview
 ********
 
-A simple protocol buffer sample using Nanopb for serializing structured data
+A simple protocol buffer sample using :ref:`nanopb_reference` for serializing structured data
 to platform independent raw buffers or streams.
 
+The structured data to encode/decode is presented as follows:
 
-Requirements
-************
+.. code-block:: proto
 
-Nanopb uses the protocol buffer compiler to generate source and header files,
-make sure the ``protoc`` executable is installed and available.
+   syntax = "proto3";
 
-.. tabs::
+   message SimpleMessage {
+       int32 lucky_number = 1;
+       bytes buffer = 2;
+       int32 unlucky_number = 3;
+   }
 
-   .. group-tab:: Ubuntu
+Configuration
+*************
 
-      Use ``apt`` to install dependency:
-
-         .. code-block:: shell
-
-            sudo apt install protobuf-compiler
-
-   .. group-tab:: macOS
-
-      Use ``brew`` to install dependency:
-
-         .. code-block:: shell
-
-            brew install protobuf
-
-   .. group-tab:: Windows
-
-      Use ``choco`` to install dependency:
-
-         .. code-block:: shell
-
-            choco install protoc
-
-
-Additionally Nanopb is an optional module and needs to be added explicitly to the workspace:
-
-.. code-block:: shell
-
-   west config manifest.project-filter -- +nanopb
-   west update
+This sample uses two configuration options to modify the behavior.
 
+* :kconfig:option:`CONFIG_SAMPLE_BUFFER_SIZE` sets the ``buffer`` field's size
+* :kconfig:option:`CONFIG_SAMPLE_UNLUCKY_NUMBER` either enables or disables the ``unlucky_number``
+  field.
 
 Building and Running
 ********************