doc: Cerate doc pages for Hello nRFcloud firmware

Created doc pages for Hello nRFcloud firmware. Signed-off-by: divya pillai <[email protected]>
hello-nrfcloud · Nov 28, 2024 · 2f25fbd · 2f25fbd
1 parent 5941ece
commit 2f25fbd
Show file tree

Hide file tree

Showing 14 changed files with 462 additions and 207 deletions.
diff --git a/README.md b/README.md
@@ -15,141 +15,4 @@ This project is based on the
 
 ## Getting started
 
-Before getting started, make sure you have a proper nRF Connect SDK development
-environment. Follow the official
-[Getting started guide](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/getting_started.html).
-
-### Initialization
-
-Before initializing start the toolchain environment:
-
-```shell
-nrfutil toolchain-manager launch --shell
-```
-
-The first step is to initialize the workspace folder (`hello-nrfcloud`) where the
-`firmware` project and all nRF Connect SDK modules will be cloned. Run the
-following command:
-
-```shell
-# initialize hello-nrfcloud workspace
-west init -m https://github.com/hello-nrfcloud/firmware --mr main hello-nrfcloud
-
-cd hello-nrfcloud
-
-# enable Bosch environmental sensor driver
-west config manifest.group-filter +bsec
-
-# update nRF Connect SDK modules
-west update
-
-# use sysbuild by default
-west config build.sysbuild True
-```
-
-### Building and running
-
-First change folder:
-
-```shell
-cd project
-```
-
-To build the application, run the following command:
-
-```shell
-west build -b thingy91x/nrf9151/ns app
-```
-
-When using the serial bootloader, you can update using this command:
-
-```
-west thingy91x-dfu
-```
-
-When using an external debugger, you can flash using this command:
-
-```shell
-west flash --erase
-```
-
-Experimental: You can also use [pyOCD](https://github.com/pyocd/pyOCD) to flash the nRF9151 using the CMSIS-DAP interface provided by the Connectivity Bridge firmware.
-
-Note: **Don't use pyOCD with JLink probes**, use [nrfutil-device](https://docs.nordicsemi.com/bundle/nrfutil/page/README.html) or the west runner in that case. pyOCD seems to be unmaintained at the moment, so this might not be fixed.
-
-Another note: Sometimes, the nRF9151 is detected as protected and is mass-erased automatically. In that case, simply flash the bootloader as well.
-
-To flash just the app:
-
-```
-pyocd flash build/app/zephyr/zephyr.signed.hex
-```
-
-To flash the bootloader (included in releases):
-
-```
-pyocd flash nrf91-bl-v2.hex
-```
-
-To erase the chip including UICR:
-
-```
-pyocd erase --mass
-```
-
-Experimental: You can update the modem firmware using pyOCD. A simple way to do this is to use the included `nrf91_flasher` script:
-
-```
-python3 scripts/nrf91_flasher.py -m mfw_nrf91x1_2.0.1.zip
-```
-
-## LED pattern
-
-| LED effect     | Color      | Meaning                                      | Duration (seconds)                                  |
-|----------------|------------|----------------------------------------------|-----------------------------------------------------|
-| Blinking       | Yellow     | Device is (re-)connecting to the LTE network | NA                                                  |
-| Blinking       | Green      | Location searching                           | NA                                                  |
-| Blinking slow  | Blue       | Device is actively polling cloud             | 10 minutes after last config update or button press |
-| Solid          | Configured | Device has received a LED configuration      | NA                                                  |
-| Blinking rapid | Red        | Fatal error, the device will reboot          | NA                                                  |
-| Blinking slow  | Red        | Irrecoverable Fatal error                    | NA                                                  |
-
-## Architecture
-
-Documentation on the overall architecture of the firmware can be found in the document [Architecture](docs/ARCHITECTURE.md).
-
-## Troubleshooting
-
-The following section contains guidelines on how to troubleshoot issues with the device.
-
-### Modem Traces
-
-Modem traces are enabled by default on the Thingy:91 X and continously stored to external flash. These traces can be output to UART for analysis using the **nRF Connect for Desktop Cellular Monitor** application.
-
-#### Steps to Capture and Dump Modem Traces:
-
-1. **Connect to a Serial Terminal**
-   - Connect your Thingy:91 X to a serial terminal on **UART 0**. This will allow you to interact with the device's shell commands. You might need to push **Button 1** to wake the UART up.
-
-2. **Set Up Cellular Monitor Application**
-   - Open the [Cellular Monitor Application](https://docs.nordicsemi.com/bundle/nrf-connect-cellularmonitor/page/index.html).
-   - Connect the Thingy:91 X to the application, select **UART 1** as the trace output, and click **Start Traces** to begin capturing modem activity.
-
-3. **Dump Traces via UART**
-   - Ensure that the error scenario has been captured. Note that older traces will be overwritten by new ones when the flash buffer is full, so ensure that the issue you want to troubleshoot has occured relatively recent to dumping of the traces over UART.
-   - Use the following shell commands in the connected serial terminal to manage and dump the modem traces on **UART 1**:
-
-   ```shell
-   modem_trace stop         # Stop modem tracing if running
-   modem_trace size         # Check the size of stored traces
-   modem_trace dump_uart    # Dump traces to UART 1 for analysis
-
-## Known issues
-
-* Serial DFU for nRF91 stops working after using GNU screen
-  * Will be fixed with the next release (https://github.com/nrfconnect/sdk-nrf/pull/19024)
-  * Workaround: use a different serial terminal application like Nordic's Serial Terminal or `tio`, power cycle device if needed.
-
-## Interactive BOM
-
-Explore the board online at this page: [Interactive BOM PCA20065 1.0.0](https://htmlpreview.github.io/?https://github.com/hello-nrfcloud/firmware/blob/main/docs/pca20065_1_0_0.html).
+To get started with hello-nrfcloud firmware for the Thingy:91 X, follow [documentation](https://github.com/hello-nrfcloud/firmware).
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
diff --git a/docs/Makefile.txt b/docs/Makefile.txt
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build_sphinx
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/about.rst b/docs/about.rst
@@ -0,0 +1,39 @@
+.. _thingy91_x_helloworld_firmware_about:
+
+About Thingy:91 X: Hello nRF Cloud firmware
+###########################################
+
+.. contents::
+   :local:
+   :depth: 1
+
+This project is based on the `NCS Example Application`_.
+
+.. to do intro
+
+LED indication
+**************
+
+The firmware supports multiple LED patterns to visualize the operating state of the application.
+The following table describes the supported LED states:
+
++----------------+------------+----------------------------------------------+-----------------------------------------------------+
+| LED effect     | Color      | Meaning                                      | Duration (seconds)                                  |
++================+============+==============================================+=====================================================+
+| Blinking       | Yellow     | Device is (re-)connecting to the LTE network | NA                                                  |
++----------------+------------+----------------------------------------------+-----------------------------------------------------+
+| Blinking       | Green      | Location searching                           | NA                                                  |
++----------------+------------+----------------------------------------------+-----------------------------------------------------+
+| Blinking slow  | Blue       | Device is actively polling cloud             | 10 minutes after last config update or button press |
++----------------+------------+----------------------------------------------+-----------------------------------------------------+
+| Solid          | Configured | Device has received a LED configuration      | NA                                                  |
++----------------+------------+----------------------------------------------+-----------------------------------------------------+
+| Blinking rapid | Red        | Fatal error, the device will reboot          | NA                                                  |
++----------------+------------+----------------------------------------------+-----------------------------------------------------+
+| Blinking slow  | Red        | Irrecoverable Fatal error                    | NA                                                  |
++----------------+------------+----------------------------------------------+-----------------------------------------------------+
+
+Interactive bill of materials (BOM)
+***********************************
+
+You can explore the interactive BOM for the Thingy:91 X board online on `Interactive BOM PCA20065 1.0.0.`_
diff --git a/docs/architecture.rst b/docs/architecture.rst
@@ -0,0 +1,100 @@
+.. _thingy91_x_helloworld_firmware_architecture:
+
+Firmware Architecture
+#####################
+
+.. contents::
+   :local:
+   :depth: 2
+
+This is the firmware that is programmed on the nRF9151 of the Thingy:91 X in the factory.
+It showcases the device's functionality if you like to try out the device.
+`nRF Cloud CoAP`_ is used as the cloud solution.
+
+Overview
+********
+
+The architecture is based on state machines and `ZBUS`_.
+The 12 modules communicate through the ZBUS channels instead of using the classic pattern of a :file:`main.c` file to tie the application together.
+This enables you to keep the modules relatively small, maintainable and reusable.
+
+The cloud-to-device communication is done with runtime settings.
+Device-to-cloud communication uses CBOR encoded-LwM2M objects.
+Each module encodes its own data using `zcbor`_.
+The format is specified in CDDL files, and encoding functions are automatically generated.
+The encoded data is sent to the payload channel, which takes care of forwarding it to the cloud.
+
+Following are the 12 modules that communicate through the ZBUS channels:
+
+Trigger module
+   This is the heart of the application, which sends triggers to control other modules.
+   The module handles the different states of the application.
+
+Transport module
+   This module manages the connection to `nRF Cloud CoAP`_ and notifies about the cloud connection status.
+   It also forwards payloads to the cloud.
+
+Network module
+   This module wraps the `connection manager`_ subsystem and notifies about network events.
+
+FOTA module
+  This module handles FOTA using the nRF Cloud CoAP and notifies about the FOTA status.
+
+App module
+  This module manages runtime settings, wraps the `Date-Time`_ library, and notifies when time is available.
+
+Memfault module
+  This module uploads runtime stats and coredumps to `Memfault`_ for easier debugging.
+
+Battery module
+  This module wraps the `Fuel Gauge`_ subsystem and publishes battery status as payload.
+
+Button module
+  This module notifies other modules about button presses and publishes button messages as payload.
+
+Environment module
+  This module wraps the `BME68X IAQ driver`_ driver and publishes air quality, temperature, and humidity data as payload.
+
+LED module
+  This module monitors various events and displays sophisticated LED patterns.
+
+Location module
+  This module wraps the `Location`_ library, gathers and sends location data.
+
+  .. note::
+     The data is sent directly using the library rather than being repackaged in the module.
+
+Shell module
+  This module tests related shell functions and turns off UART for power saving when leaving the polling mode.
+
+Accessing of modules with ZBUS channels
+***************************************
+
+.. note::
+   The ERROR channel and channels only used internally in modules are omitted.
+
+The following table showcases the access of modules with different ZBUS channels:
+
++--------------+---------+-------------+----------+---------+---------+-----+--------+------+-----+----------+-------+-----------+
+| CHANNEL      | Battery | Environment | Location | Network | Trigger | App | Button | FOTA | Led | Memfault | Shell | Transport |
++==============+=========+=============+==========+=========+=========+=====+========+======+=====+==========+=======+===========+
+| CLOUD        |         |             | R        |         | R       | R   |        | R    |     | R        |       | W         |
++--------------+---------+-------------+----------+---------+---------+-----+--------+------+-----+----------+-------+-----------+
+| CONFIG       |         |             | R        |         | R       | W   |        |      |     |          |       |           |
++--------------+---------+-------------+----------+---------+---------+-----+--------+------+-----+----------+-------+-----------+
+| LOCATION     |         |             | W        |         | R       |     |        |      | R   |          |       |           |
++--------------+---------+-------------+----------+---------+---------+-----+--------+------+-----+----------+-------+-----------+
+| BUTTON       |         |             |          |         | R       |     | W      |      |     |          | W     |           |
++--------------+---------+-------------+----------+---------+---------+-----+--------+------+-----+----------+-------+-----------+
+| FOTA         |         |             |          |         | R       |     |        | W    |     |          |       |           |
++--------------+---------+-------------+----------+---------+---------+-----+--------+------+-----+----------+-------+-----------+
+| TRIGGER      | R       | R           | R        | R       | W       |     |        |      |     |          |       |           |
++--------------+---------+-------------+----------+---------+---------+-----+--------+------+-----+----------+-------+-----------+
+| TRIGGER_MODE |         |             |          |         | W       |     |        |      | R   |          |       |           |
++--------------+---------+-------------+----------+---------+---------+-----+--------+------+-----+----------+-------+-----------+
+| NETWORK      | R       |             | R        | W       |         |     |        |      | R   |          |       | R         |
++--------------+---------+-------------+----------+---------+---------+-----+--------+------+-----+----------+-------+-----------+
+| PAYLOAD      | W       | W           |          | W       |         |     | W      |      |     |          |       | R         |
++--------------+---------+-------------+----------+---------+---------+-----+--------+------+-----+----------+-------+-----------+
+| TIME         | R       | R           |          | R       |         | W   |        |      | R   |          |       |           |
++--------------+---------+-------------+----------+---------+---------+-----+--------+------+-----+----------+-------+-----------+