CAF: sensor_manager: Add sensor event aggregator doc

Add CAF module sensor_data_aggregator documentation.

Jira: NCSDK-13982

Signed-off-by: Jan Zyczkowski <[email protected]>

doc/nrf/libraries/caf/caf_overview.rst

@@ -219,3 +219,13 @@ CAF sensor events
 .. doxygengroup:: caf_sensor_event
    :project: nrf
    :members:
+
+CAF sensor data aggregator events
+=================================
+
+| Header file: :file:`include/caf/events/sensor_data_aggregator_event.h`
+| Source file: :file:`subsys/caf/events/sensor_data_aggregator_event.c`
+
+.. doxygengroup:: caf_sensor_data_aggregator_event
+   :project: nrf
+   :members:

doc/nrf/libraries/caf/sensor_data_aggregator.rst

@@ -0,0 +1,81 @@
+.. _caf_sensor_data_aggregator:
+
+CAF: Sensor data aggregator module
+##################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+The |sensor_data_aggregator| of the :ref:`lib_caf` (CAF) is a simple module responsible for aggregating sensor data in form of ``sensor_event`` and passing them further in packages.
+It can be used in both single-core and multi-core SoCs.
+
+When used with multi-core SoCs, the |sensor_data_aggregator| can reduce power consumption.
+One core gathers data from sensors and when there is sufficient data to analyze, the first core wakes up the other core and sends the aggregated data to that core.
+
+Configuration
+*************
+
+The |sensor_data_aggregator| module can be enabled by selecting the :kconfig:option:`CONFIG_CAF_SENSOR_DATA_AGGREGATOR` option.
+
+To use the module, you must complete the following steps:
+
+1. Enable the :kconfig:option:`CONFIG_CAF_SENSOR_DATA_AGGREGATOR` option.
+#. If you are using multi-core SoC and want to receive aggregated data on another core, on the second core enable the :kconfig:option:`CONFIG_CAF_SENSOR_DATA_AGGREGATOR_EVENTS` option.
+#. Enable aggregator in devicetree file that describes the aggregator parameters you can use for example app.overlay file.
+   Each aggregator should be placed as a separate node.
+   For example, the file content could look like follows:
+
+   .. code-block:: devicetree
+
+      agg0: agg0 {
+              compatible = "caf,aggregator";
+              sensor_descr = "accel_sim_xyz";
+              buf_data_length = <120>;
+              sensor_data_size = <12>;
+              status = "okay";
+      };
+
+      agg1: agg1 {
+             compatible = "caf,aggregator";
+             sensor_descr = "void_test_sensor";
+             buf_data_length = <80>;
+             sensor_data_size = <8>;
+             status = "okay";
+      };
+
+Two aggregators are defined here and each one is responsible to handle data of the different sensors.
+The aggregator is defined as a separate node in the devicetree and consists of the following parameters:
+
+* ``compatible`` - This is DTS binding and should be set to ``caf,aggregator``.
+* ``sensor_descr`` - This parameter represents the description of the sensor and should be the same as the description in the :ref:`caf_sensor_sampler` module.
+* ``buf_data_length`` - This parameter represents the length of the buffer in bytes.
+  Its default value is ``120``.
+  The value should be set as a multiple of sensor sample size.
+* ``sensor_data_size`` - This parameter represents the sensor sample size and is set in bytes.
+  Its default value is ``4``.
+* ``buf_coun`` - This parameter represents the number of buffers in the aggregator.
+  Its default value is ``2``.
+* ``status`` - This parameter represents the node status and should be set to ``okay``.
+
+Implementation details
+**********************
+
+|sensor_data_aggregator| subscribes to following sensor manager events:
+
+* :c:struct:`sensor_state_event`
+* :c:struct:`sensor_event`
+* :c:struct:`sensor_data_aggregator_release_buffer_event`.
+
+The |sensor_data_aggregator| gathers data from :c:struct:`sensor_event` and stores the data in an active :c:struct:`aggregator_buffer`.
+When buffer is full, the |sensor_data_aggregator| sends the buffer to :c:struct:`sensor_data_aggregator_event` struct.
+Then module searches for the next free :c:struct:`aggregator_buffer` and sets it as an active buffer.
+
+After changing the sensor state and receiving :c:struct:`sensor_state_event`, the |sensor_data_aggregator| sends the data that is gathered in the active buffer.
+
+After receiving :c:struct:`sensor_data_aggregator_release_buffer_event`, the |sensor_data_aggregator| sets :c:struct:`aggregator_buffer` to free state.
+
+Several buffers can be reduced to one, in case of a situation where the sampling period is greater than the time needed to send and process :c:struct:`sensor_data_aggregator_event`.
+In the situation when sampling is much faster than the time needed to send and process :c:struct:`sensor_data_aggregator_event`, the number of buffers should be increased.
+
+.. |sensor_data_aggregator| replace:: sensor data aggregator module

doc/nrf/releases/release-notes-changelog.rst

@@ -391,6 +391,13 @@ Other libraries
     The library is no longer directly referenced from the Event Manager.
     Instead, it uses the Event Manager hooks to connect with the manager.
 
+Common Application Framework (CAF)
+----------------------------------
+
+* Added:
+
+  * :ref:`caf_sensor_data_aggregator`, which buffers sensor events and sends them as packages to the listener.
+
 Other libraries
 ---------------
 

dts/bindings/vendor-prefixes.txt

@@ -1 +1,2 @@
 pixart	PixArt Imaging Inc.
+caf	Common Application Framework

subsys/caf/modules/sensor_data_aggregator.c

@@ -21,7 +21,7 @@ LOG_MODULE_REGISTER(MODULE, CONFIG_CAF_SENSOR_MANAGER_LOG_LEVEL);
 #define DT_DRV_COMPAT caf_aggregator
 
 #define __DEFINE_DATA(i, agg_id, size)							\
-	__ALIGNED(4) static uint8_t agg_ ## agg_id ## _buff_ ## i ## _data[size];
+	static uint8_t agg_ ## agg_id ## _buff_ ## i ## _data[size] __aligned(4);
 
 #define __INITIALIZE_BUF(i, agg_id)							\
 	{(uint8_t *) &agg_ ## agg_id ## _buff_ ## i ## _data},