applications: asset_tracker_v2: Add modem module documentation

jtguggedal · rlubos · commit 7a39db1774e8 · 2022-01-14T10:59:44.000+01:00
Add documentation of the modem module.

Signed-off-by: Jan Tore Guggedal &lt;jantore.guggedal@nordicsemi.no&gt;
diff --git a/applications/asset_tracker_v2/README.rst b/applications/asset_tracker_v2/README.rst
@@ -22,6 +22,7 @@ See the subpages for detailed documentation on the application and its internal
    doc/cloud_module
    doc/cloud_wrapper
    doc/debug_module
+   doc/gnss_module
+   doc/modem_module
    doc/sensor_module
    doc/ui_module
-   doc/gnss_module
diff --git a/applications/asset_tracker_v2/doc/modem_module.rst b/applications/asset_tracker_v2/doc/modem_module.rst
@@ -0,0 +1,163 @@
+.. _asset_tracker_v2_modem_module:
+
+Modem module
+############
+
+.. contents::
+   :local:
+   :depth: 2
+
+The modem module communicates with the modem to control the LTE connection and retrieve information from the modem about the device and LTE network.
+
+Features
+********
+
+This section documents the features implemented by the module.
+
+LTE connection handling
+=======================
+
+The module uses the :ref:`lte_lc_readme` library to control and monitor the LTE connection.
+The module registers an event handler with :ref:`lte_lc_readme` to receive updates from the modem about the state of the LTE connection and network information.
+If you use the :ref:`liblwm2m_carrier_readme` library, refer to :ref:`modem_module_carrier_lib` for additional information on LTE connection handling.
+
+In its default configuration, the modem module makes an attempt to establish an LTE connection immediately when it is initialized.
+There is no timeout on the connection attempt, so the modem searches for a suitable LTE network until it finds one.
+
+When the device is registered to an LTE network, the LTE connection is considered to be established, and a :c:enum:`MODEM_EVT_LTE_CONNECTED` event is sent.
+If the network registration is lost at some point, a :c:enum:`MODEM_EVT_LTE_DISCONNECTED` event is sent.
+
+If the device connects to a new LTE cell, an :c:enum:`LTE_LC_EVT_CELL_UPDATE` is sent.
+The event contains cell ID and tracking area code as payload, which can be used to determine the device's coarse position.
+
+If the modem module receives an ``APP_EVT_LTE_DISCONNECT`` event, it instructs the modem to detach from the network, and a subsequent :c:enum:`MODEM_EVT_LTE_DISCONNECTED` event can be expected after the disconnect.
+
+To configure the LTE connection parameters, refer to the :ref:`lte_lc_readme` Kconfig options.
+These options can be used to select the access technology to use (LTE-M or NB-IoT), default values for :term:`Power Saving Mode (PSM)` timers and more.
+
+Note that some network parameters, such as PSM timer values, are requests to the network and might not be granted as requested, and the network might grant a different value than the requested values or deny the request altogether.
+The actual values that are received from the network are distributed in :c:enum:`MODEM_EVT_LTE_PSM_UPDATE` events.
+
+.. _modem_module_carrier_lib:
+
+Carrier library support
+=======================
+
+The modem module has support for the :ref:`liblwm2m_carrier_readme` library.
+When the library is enabled, the modem module leaves the LTE connection handling to the library in order to adhere to the specific carrier's requirements.
+
+If the :ref:`liblwm2m_carrier_readme` library starts a modem firmware update, the modem module sends a :c:enum:`MODEM_EVT_CARRIER_FOTA_PENDING` event.
+This event signals that a modem firmware FOTA download is about to start, and all the other TLS connections in the system must be closed, including any cloud connection.
+After a successful FOTA, :c:enum:`MODEM_EVT_CARRIER_REBOOT_REQUEST` is sent, indicating that the application must perform a graceful shutdown and reboot the device to apply the new modem firmware.
+If a FOTA download fails, a :c:enum:`MODEM_EVT_CARRIER_FOTA_STOPPED` event is sent, and the application might again establish TLS connections and continue normal operation.
+
+For more details and configuration options, you can refer to :ref:`liblwm2m_carrier_readme`.
+
+Modem information
+=================
+
+When the application module sends out an ``APP_EVT_DATA_GET`` event, the modem module checks the requested data list for relevant requests:
+
+* ``APP_DATA_MODEM_STATIC`` - Static modem data, such as configured system mode (any combination of LTE-M, NB-IoT and GNSS), ICCID, modem firmware version, application version and board version.
+* ``APP_DATA_MODEM_DYNAMIC`` - Dynamic modem data, such as Cell ID, tracking area code, RSRP, IP address and PLMN (MCCMNC).
+* ``APP_DATA_BATTERY`` - Voltage of the modem's power supply.
+
+The module uses :ref:`modem_info_readme` to acquire information about the modem, LTE network and the modem's power supply.
+The response for the three different data types is sent as separate events:
+
+* Static data as :c:enum:`MODEM_EVT_MODEM_STATIC_DATA_READY`
+* Dynamic data as :c:enum:`MODEM_EVT_MODEM_DYNAMIC_DATA_READY`
+* Battery voltage as :c:enum:`MODEM_EVT_BATTERY_DATA_READY`
+
+If the sampling of data fails, a corresponding error message is sent through one of the following events:
+
+* :c:enum:`MODEM_EVT_MODEM_STATIC_DATA_NOT_READY`
+* :c:enum:`MODEM_EVT_MODEM_DYNAMIC_DATA_NOT_READY`
+* :c:enum:`MODEM_EVT_BATTERY_DATA_NOT_READY`
+
+Neighbor cell measurements
+==========================
+
+Neighbor cell measurements can be requested by the application by sending an ``APP_EVT_DATA_GET`` event where ``APP_DATA_NEIGHBOR_CELLS`` is part of the requested data list.
+Upon reception of that event, the modem module uses the LTE link controller to start a neighbor cell  search of type :c:enum:`LTE_LC_NEIGHBOR_SEARCH_TYPE_DEFAULT`.
+See :ref:`lte_lc_readme` for more details on the available search types.
+When the search completes, the module sends a :c:enum:`MODEM_EVT_NEIGHBOR_CELLS_DATA_READY` event containing the cell information received from the modem.
+If the search fails, a :c:enum:`MODEM_EVT_NEIGHBOR_CELLS_DATA_NOT_READY` event is sent.
+
+Module internals
+****************
+
+The modem module has an internal thread with a message queue for processing.
+When an event is received in the :ref:`event_manager` handler, the event is converted to a message and put into the module's queue for processing in thread context.
+This gives the module the flexibility to call functions that might take some time to complete.
+
+Module states
+=============
+
+The modem module has an internal state machine with the following states:
+
+  * ``STATE_INIT`` - The initial state of the module in which it awaits the modem to be initialized.
+    The module enters this state only if the :ref:`liblwm2m_carrier_readme` library is enabled because the modem is automatically initialized otherwise.
+  * ``STATE_DISCONNECTED`` - The module has performed all required initializations and is ready to establish an LTE connection.
+    This is the initial state for applications that do not use the :ref:`liblwm2m_carrier_readme` library.
+  * ``STATE_CONNECTING`` - The modem is currently searching for a suitable LTE network and attempting to establish a connection.
+  * ``STATE_CONNECTED`` - The device is connected to an LTE network.
+  * ``STATE_SHUTDOWN`` - The module has been shut down after receiving a request from the utility module.
+
+State transitions take place based on input from other modules through the event manager handler and the LTE link controller handler.
+
+Configuration options
+*********************
+
+You can set the following options to configure the modem module:
+
+.. _CONFIG_MODEM_MODULE:
+
+CONFIG_MODEM_MODULE - Configuration for modem module
+   This option enables the modem module.
+
+.. _CONFIG_MODEM_THREAD_STACK_SIZE:
+
+CONFIG_MODEM_THREAD_STACK_SIZE -  Configuration for thread stack size
+   This option configures the modem module thread stack size.
+
+.. _CONFIG_MODEM_SEND_ALL_SAMPLED_DATA:
+
+CONFIG_MODEM_SEND_ALL_SAMPLED_DATA - Configuration for sending all sampled data
+   By default, the modem module sends only events with sampled data that has changed since the last sampling.
+   To send unchanged data also, enable this option.
+
+.. _CONFIG_MODEM_AUTO_REQUEST_POWER_SAVING_FEATURES:
+
+CONFIG_MODEM_AUTO_REQUEST_POWER_SAVING_FEATURES - Configuration for automatic requests of PSM
+   The module automatically requests PSM from the LTE network.
+   If PSM is granted by the network, it results in reduction of the modem's power consumption.
+   Note that the device is not reachable from the cloud when it is in PSM.
+   The device exits PSM whenever the application sends data, or the configured PSM TAU (Tracking Area Update) interval has passed.
+   To not request PSM from the network, disable this option.
+
+For more information on LTE configuration options, see :ref:`lte_lc_readme`.
+
+Module events
+*************
+
+The :file:`asset_tracker_v2/src/events/modem_module_event.h` header file contains a list of the events sent by the modem module.
+
+Dependencies
+************
+
+The module uses the following |NCS| libraries:
+
+* :ref:`event_manager`
+* :ref:`lte_lc_readme`
+* :ref:`modem_info_readme`
+
+API documentation
+*****************
+
+| Header file: :file:`asset_tracker_v2/src/events/modem_module_event.h`
+| Source files: :file:`asset_tracker_v2/src/events/modem_module_event.c`, :file:`asset_tracker_v2/src/modules/modem_module.c`
+
+.. doxygengroup:: modem_module_event
+   :project: nrf
+   :members:
diff --git a/applications/asset_tracker_v2/src/events/modem_module_event.h b/applications/asset_tracker_v2/src/events/modem_module_event.h
@@ -26,41 +26,122 @@ extern "C" {
 enum modem_module_event_type {
 	/** Event signalling that the modem library and AT command library
 	 *  have been initialized and are ready for use by other modules.
+	 *  The event has no associated payload.
 	 */
 	MODEM_EVT_INITIALIZED,
+
+	/** The device has been registered with an LTE network.
+	 *  The event has no associated payload.
+	 */
 	MODEM_EVT_LTE_CONNECTED,
+
+	/** The device has been de-registered with an LTE network.
+	 *  The event has no associated payload.
+	 */
 	MODEM_EVT_LTE_DISCONNECTED,
+
+	/** The device is searching for an LTE network.
+	 *  The event has no associated payload.
+	 */
 	MODEM_EVT_LTE_CONNECTING,
+
+	/** The device is connected to a new LTE cell.
+	 *  The event has associated payload of type @ref modem_module_cell in
+	 *  the `data.cell` member.
+	 */
 	MODEM_EVT_LTE_CELL_UPDATE,
+
+	/** PSM configuration has been received.
+	 *  The event has associated payload of type @ref modem_module_psm in
+	 *  the `data.psm` member.
+	 */
 	MODEM_EVT_LTE_PSM_UPDATE,
+
+	/** eDRX configuration has been received.
+	 *  The event has associated payload of type @ref modem_module_edrx in
+	 *  the `data.edrx` member.
+	 */
 	MODEM_EVT_LTE_EDRX_UPDATE,
+
+	/** Static modem data has been sampled and is ready.
+	 *  The event has associated payload of type @ref modem_module_static_modem_data in
+	 *  the `data.modem_static` member.
+	 */
 	MODEM_EVT_MODEM_STATIC_DATA_READY,
+
+	/** Dynamic modem data has been sampled and is ready.
+	 *  The event has associated payload of type @ref modem_module_dynamic_modem_data in
+	 *  the `data.modem_dynamic` member.
+	 */
 	MODEM_EVT_MODEM_DYNAMIC_DATA_READY,
+
+	/** Static modem data could not be sampled will not be ready for this
+	 *  sampling interval.
+	 *  The event has no associated payload.
+	 */
 	MODEM_EVT_MODEM_STATIC_DATA_NOT_READY,
+
+	/** Dynamic modem data could not be sampled will not be ready for this
+	 *  sampling interval.
+	 *  The event has no associated payload.
+	 */
 	MODEM_EVT_MODEM_DYNAMIC_DATA_NOT_READY,
+
+	/** Neighbor cell measurements have been gathered and the data is ready.
+	 *  The event has associated payload of type @ref modem_module_neighbor_cells in
+	 *  the `data.neighbor_cells` member.
+	 */
 	MODEM_EVT_NEIGHBOR_CELLS_DATA_READY,
+
+	/** Neighbor cell data measurements could not be gathered will not be ready for this
+	 *  sampling interval.
+	 *  The event has no associated payload.
+	 */
 	MODEM_EVT_NEIGHBOR_CELLS_DATA_NOT_READY,
-	MODEM_EVT_BATTERY_DATA_NOT_READY,
+
+	/** Battery voltage has been sampled and is ready.
+	 *  The event has associated payload of type @ref modem_module_battery_data in
+	 *  the `data.bat` member.
+	 */
 	MODEM_EVT_BATTERY_DATA_READY,
+
+	/** Battery data could not be sampled will not be ready for this sampling interval.
+	 *  The event has no associated payload.
+	 */
+	MODEM_EVT_BATTERY_DATA_NOT_READY,
+
+	/** The modem module has successfully shut down.
+	 *  The event has associated payload of type `uint32_t` in the `data.id` member.
+	 */
 	MODEM_EVT_SHUTDOWN_READY,
+
+	/** A crtical error has occurred, and the application should reboot to recover as
+	 *  the module may enter an undefined state.
+	 *  The event has associated payload of the type `int` in the `data.err` member.
+	 */
 	MODEM_EVT_ERROR,
+
 	/** The carrier library has initialized the modem library and it is
 	 *  now ready to be used. When the carrier library is enabled, this
 	 *  event must be received before the modem module can proceed to initialize
 	 *  other dependencies and subsequently send MODEM_EVT_INITIALIZED.
+	 *  The event has no associated payload.
 	 */
 	MODEM_EVT_CARRIER_INITIALIZED,
 	/** Due to modem limitations for active TLS connections, the carrier
 	 *  library requires all other TLS connections in the system to
 	 *  be terminated while FOTA update is ongoing.
+	 *  The event has no associated payload.
 	 */
 	MODEM_EVT_CARRIER_FOTA_PENDING,
 	/** FOTA update has been stopped and the application can set up TLS
 	 *  connections again.
+	 *  The event has no associated payload.
 	 */
 	MODEM_EVT_CARRIER_FOTA_STOPPED,
 	/** The carrier library requests that the device reboots to apply
 	 *  downloaded firmware image(s) or for other reasons.
+	 *  The event has no associated payload.
 	 */
 	MODEM_EVT_CARRIER_REBOOT_REQUEST,
 };
diff --git a/doc/nrf/releases/release-notes-changelog.rst b/doc/nrf/releases/release-notes-changelog.rst
@@ -65,6 +65,7 @@ nRF9160: Asset Tracker v2
 * Updated the code and documentation to use the acronym GNSS instead of GPS when not referring explicitly to the GPS system.
 * Added support for atmospheric pressure readings retrieved from the BME680 sensor on Thingy:91.
 * Fixed an issue where PSM could be requested from the network even though it was disabled in Kconfig.
+* Added new documentation for Asset Tracker v2 :ref:`asset_tracker_v2_modem_module`.
 
 * Added:
 
@@ -336,4 +337,5 @@ In addition to documentation related to the changes listed above, the following
 
   * Reduced the ToC levels of the subpages.
 
+
 .. |no_changes_yet_note| replace:: No changes since the latest |NCS| release.
