Skip to content
This repository was archived by the owner on Jul 9, 2024. It is now read-only.

Commit c57c343

Browse files
author
GitHub Actions
committed
fix: update from upstream
See https://github.com/nrfconnect/sdk-nrf/tree/472f023073ae22a29878c207bc0ea44921d98a11/applications/asset_tracker_v2
1 parent bbb5f34 commit c57c343

11 files changed

Lines changed: 701 additions & 234 deletions

‎README.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,6 @@ See the subpages for detailed documentation on the application and its internal
1919
:caption: Subpages:
2020

2121
doc/asset_tracker_v2_description
22+
doc/cloud_module
23+
doc/cloud_wrapper
2224
doc/debug_module

‎doc/asset_tracker_v2_description.rst‎

Lines changed: 99 additions & 192 deletions
Large diffs are not rendered by default.

‎doc/cloud_module.rst‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
.. _asset_tracker_v2_cloud_module:
2+
3+
Cloud module
4+
############
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
The cloud module establishes and maintains the connection to a supported cloud service.
11+
Use the :ref:`Cloud wrapper API <api_cloud_wrapper>` to integrate and handle the client libraries present in the |NCS|.
12+
13+
Features
14+
********
15+
16+
This section documents the various features implemented by the module.
17+
18+
Cloud services
19+
==============
20+
21+
The cloud module supports communication with multiple cloud services, one service at the time.
22+
The :ref:`Supported cloud services <supported_cloud_services>` table lists the cloud services supported by the module together with protocols and technologies used with them.
23+
See :ref:`Cloud wrapper API <api_cloud_wrapper>` for more information on how each client library is integrated in the module.
24+
25+
.. _supported_cloud_services:
26+
27+
+------------------+-------------------------------+
28+
| Cloud service | Protocols and technologies |
29+
+==================+===============================+
30+
| `AWS IoT Core`_ | `MQTT`_ |
31+
| +-------------------------------+
32+
| | `TCP`_ |
33+
| +-------------------------------+
34+
| | `TLS`_ |
35+
| +-------------------------------+
36+
| | :ref:`FOTA <nrf9160_fota>` |
37+
| +-------------------------------+
38+
| | :ref:`lib_nrf_cloud_agps` |
39+
| +-------------------------------+
40+
| | :ref:`lib_nrf_cloud_pgps` |
41+
+------------------+-------------------------------+
42+
| `Azure IoT Hub`_ | `MQTT`_ |
43+
| +-------------------------------+
44+
| | `TCP`_ |
45+
| +-------------------------------+
46+
| | `TLS`_ |
47+
| +-------------------------------+
48+
| | :ref:`FOTA <nrf9160_fota>` |
49+
| +-------------------------------+
50+
| | :ref:`lib_nrf_cloud_agps` |
51+
| +-------------------------------+
52+
| | :ref:`lib_nrf_cloud_pgps` |
53+
+------------------+-------------------------------+
54+
| `nRF Cloud`_ | `MQTT`_ |
55+
| +-------------------------------+
56+
| | `TCP`_ |
57+
| +-------------------------------+
58+
| | `TLS`_ |
59+
| +-------------------------------+
60+
| | :ref:`FOTA <nrf9160_fota>` |
61+
| +-------------------------------+
62+
| | :ref:`lib_nrf_cloud_agps` |
63+
| +-------------------------------+
64+
| | :ref:`lib_nrf_cloud_pgps` |
65+
+------------------+-------------------------------+
66+
67+
.. _nrfcloud_agps_pgps:
68+
69+
nRF Cloud A-GPS and P-GPS
70+
=========================
71+
72+
When the cloud module is configured to communicate with `AWS IoT Core`_ or `Azure IoT Hub`_, it supports processing of received A-GPS and P-GPS data using the :ref:`lib_nrf_cloud_agps` and :ref:`lib_nrf_cloud_pgps` libraries.
73+
This enables the cloud to fetch A-GPS and P-GPS data from `nRF Cloud`_ using REST calls and relay the data to the nRF9160 SiP using the pre-established connection to `AWS IoT Core`_ or `Azure IoT Hub`_.
74+
Maintaining multiple cloud connections at the same time is not feasible because of high data traffic and energy consumption.
75+
Establishing a secure connection typically consists of multiple kB of exchanged data with the cloud service.
76+
When configuring the application to communicate with nRF Cloud, A-GPS and P-GPS data are received directly from the service, in contrast to the AWS IoT and Azure IoT Hub implementations.
77+
78+
FOTA
79+
====
80+
81+
The client libraries supported by the cloud wrapper API all implement their own version of :ref:`FOTA <nrf9160_fota>`.
82+
This enables the cloud to issue FOTA updates and update the application and modem firmware while the device is in field.
83+
For additional documentation on the various FOTA implementations, refer to the respective client library documentation linked to in :ref:`Integration layers <integration_layers>`.
84+
85+
Connection awareness
86+
====================
87+
88+
The cloud module implements connection awareness by maintaing an internal state that is based on
89+
events from the modem module and callbacks from the :ref:`Cloud wrapper API <api_cloud_wrapper>`.
90+
91+
If the module is disconnected, it will try to reconnect while the LTE connection is still valid.
92+
To adjust the number of reconnection attempts, set the :ref:`CONFIG_CLOUD_CONNECT_RETRIES <CONFIG_CLOUD_CONNECT_RETRIES>` option.
93+
Reconnection is implemented with a binary backoff based on the following lookup table:
94+
95+
.. code-block:: c
96+
97+
static struct cloud_backoff_delay_lookup backoff_delay[] = {
98+
{ 32 }, { 64 }, { 128 }, { 256 }, { 512 },
99+
{ 2048 }, { 4096 }, { 8192 }, { 16384 }, { 32768 },
100+
{ 65536 }, { 131072 }, { 262144 }, { 524288 }, { 1048576 }
101+
};
102+
103+
If the module reaches the maximum number of reconnection attempts, the application receives an error event notification of type :c:enum:`CLOUD_EVT_ERROR`, causing the application to perform a reboot.
104+
105+
Configuration options
106+
*********************
107+
108+
.. _CONFIG_CLOUD_THREAD_STACK_SIZE:
109+
110+
CONFIG_CLOUD_THREAD_STACK_SIZE - Cloud module thread stack size
111+
This option increases the cloud module's internal thread stack size.
112+
113+
.. _CONFIG_CLOUD_CLIENT_ID_USE_CUSTOM:
114+
115+
CONFIG_CLOUD_CLIENT_ID_USE_CUSTOM - Configuration for enabling the use of a custom cloud client ID
116+
This option is used to enable the use of a custom client ID for connection to the respective cloud service.
117+
By default, the cloud module uses the IMEI of the nRF9160-based device as the client ID.
118+
119+
.. _CONFIG_CLOUD_CLIENT_ID:
120+
121+
CONFIG_CLOUD_CLIENT_ID - Configuration for providing a custom cloud client ID
122+
This option sets the custom client ID for the respective cloud service.
123+
For setting a custom client ID, you need to set :kconfig:`CONFIG_CLOUD_CLIENT_ID_USE_CUSTOM` to ``y``.
124+
125+
.. _CONFIG_CLOUD_CONNECT_RETRIES:
126+
127+
CONFIG_CLOUD_CONNECT_RETRIES - Configuration that sets the number of cloud reconnection attempts
128+
This option sets the number of times that a connection will be re-attempted upon a disconnect from the cloud service.
129+
130+
.. _mandatory_config:
131+
132+
Mandatory configurations
133+
========================
134+
135+
To be able to use a supported cloud client library, you need to set a few mandatory Kconfig options.
136+
These typically include the cloud service hostname and the security tag associated with the certificates used to establish a connection.
137+
Before running the application, you need to provision the certificates to the modem using the same security tag.
138+
For more information on how to set up a connection and provision certificates to the modem, see the documentation for the respective client library in :ref:`Integration layers <integration_layers>`.
139+
140+
.. note::
141+
There are no mandatory configuration settings for the :ref:`lib_nrf_cloud` library.
142+
The nRF9160 DK and Thingy91 come preprovisioned with certificates required to establish a connection to nRF Cloud.
143+
The default configuration of the :ref:`lib_nrf_cloud` library uses the security tag that the nRF Cloud certificates are stored to.
144+
145+
Configurations for AWS IoT library
146+
----------------------------------
147+
148+
To enable communication with AWS IoT, set the following options in the :file:`overlay-aws.conf` file:
149+
150+
* :kconfig:`CONFIG_AWS_IOT_BROKER_HOST_NAME`
151+
* :kconfig:`CONFIG_AWS_IOT_SEC_TAG`
152+
153+
Configurations for Azure IoT Hub library
154+
----------------------------------------
155+
156+
To enable communication with Azure IoT Hub, set the following options in the :file:`overlay-azure.conf` file:
157+
158+
* :kconfig:`CONFIG_AZURE_IOT_HUB_DPS_HOSTNAME`
159+
* :kconfig:`CONFIG_AZURE_IOT_HUB_DPS_ID_SCOPE`
160+
* :kconfig:`CONFIG_AZURE_IOT_HUB_SEC_TAG`
161+
* :kconfig:`CONFIG_AZURE_FOTA_SEC_TAG`
162+
163+
Module hierarchy
164+
****************
165+
166+
The following diagram illustrates the relationship between the cloud module, integration layers, and client libraries.
167+
168+
.. figure:: /images/asset_tracker_v2_cloud_module_hierarchy.svg
169+
:alt: Cloud module hierarchy
170+
171+
Cloud module hierarchy
172+
173+
Module states
174+
*************
175+
176+
The cloud module has an internal state machine with the following states:
177+
178+
* ``STATE_LTE_INIT`` - The initial state of the module in which it awaits the modem to be initialized.
179+
* ``STATE_LTE_DISCONNECTED`` - The module has performed all required initialization and waits for the modem to connect to LTE.
180+
* ``STATE_LTE_CONNECTED`` - The modem is connected to LTE and the internal cloud connection routine starts. This state has two sub-states:
181+
182+
* ``SUB_STATE_CLOUD_DISCONNECTED`` - The cloud service is disconnected.
183+
* ``SUB_STATE_CLOUD_CONNECTED`` - The cloud service is connected, data can now be sent.
184+
185+
* ``STATE_SHUTDOWN`` - The module has been shut down after receiving a request to do so from the util module.
186+
187+
State transitions take place based on events from other modules, such as the app module, data module, and util module.
188+
189+
Module events
190+
*************
191+
192+
The :file:`asset_tracker_v2/src/events/cloud_module_event.h` header file contains a list of various events sent by the module.
193+
194+
Dependencies
195+
************
196+
197+
This module uses the following |NCS| libraries and drivers:
198+
199+
* :ref:`api_cloud_wrapper`
200+
* :ref:`lib_nrf_cloud_agps`
201+
* :ref:`lib_nrf_cloud_pgps`
202+
203+
API documentation
204+
*****************
205+
206+
| Header file: :file:`asset_tracker_v2/src/events/cloud_module_event.h`
207+
| Source files: :file:`asset_tracker_v2/src/events/cloud_module_event.c`
208+
:file:`asset_tracker_v2/src/modules/cloud_module.c`
209+
210+
.. doxygengroup:: cloud_module_event
211+
:project: nrf
212+
:members:

0 commit comments

Comments
 (0)