Docs for main module

README.md

@@ -7,11 +7,25 @@
 [![Target_tests](https://github.com/nrfconnect/Asset-Tracker-Template/actions/workflows/build-and-target-test.yml/badge.svg?event=schedule)](https://github.com/nrfconnect/Asset-Tracker-Template/actions/workflows/build-and-target-test.yml?query=branch%3Amain+event%3Aschedule)
 [![Power Consumption Badge](https://img.shields.io/endpoint?url=https://nrfconnect.github.io/Asset-Tracker-Template/power_badge.json)](https://nrfconnect.github.io/Asset-Tracker-Template/power_measurements_plot.html)
 
-The Asset Tracker Template is under development.
-
 ## Overview
 
-Template for Cellular IoT development on Nordic Semiconductor nRF91 Series LTE devices
+The Asset Tracker Template implements a modular application framework for nRF91-based IoT devices.
+The application is built on nRF Connect SDK and uses a combination of state machines and message-based inter-module communication.
+It is intended to be a framework for developing asset tracking applications, but can be customized for other use cases as well.
+We have not targeted a specific use-case with this template, but rather a set of features that are common in asset tracking applications, and left it up to the user to decide how to use, modify, or extend the template to fit their needs.
+The ``main.c`` file contains the main module of the application, where the business logic and control over the other modules is implemented, and is a good starting point for understanding how the application works.
+This is also the naural place to start when customizing the application for a specific use-case.
+
+The template is open-source for a reason, and we encourage users to contribute back to the project with improvements, bug fixes, or new features.
+
+## Key concepts
+
+* **Modular design**: The application is divided into modules, each responsible for a specific feature or functionality.
+* **State machines**: Each module, where applicable, has its own state machine, which defines the behavior of the module. The state machines are implemented using Zephyr's [State Machine Framework](https://docs.nordicsemi.com/bundle/ncs-3.0.0-preview1/page/zephyr/services/smf/index.html).
+* **Message-based communication**: Modules communicate with each other by sending messages using [zbus](https://docs.nordicsemi.com/bundle/ncs-latest/page/zephyr/services/zbus/index.html), a message bus library for Zephyr.
+* **Configuration options**: The application can be configured using Kconfig options to enable or disable features, set parameters, and more.
+* **Designed for low-power operation**: The application is designed to be power-efficient, with features like LTE Power Saving Mode (PSM) enabled by default.
+
 
 ## Table of Contents
 

app/src/Kconfig.main

@@ -12,10 +12,6 @@ config APP_MODULE_TRIGGER_TIMEOUT_SECONDS
 	  Timeout for the trigger timer. On timeout, the module will send triggers for
 	  sensor sampling, location search and polling of shadow and FOTA status from cloud.
 
-config APP_MODULE_THREAD_STACK_SIZE
-	int "Thread stack size"
-	default 3200
-
 config APP_REQUEST_NETWORK_QUALITY
 	bool "Request network quality"
 	help

docs/modules/main.md

@@ -1,11 +1,105 @@
-# Main module
+# Main Module
 
-What does this module do
+The Main module serves as the central control unit of the Asset Tracker Template application. It implements a hierarchical state machine that coordinates the activities of all other modules through [zbus](https://docs.nordicsemi.com/bundle/ncs-latest/page/zephyr/services/zbus/index.html) messages.
+This module handles the application's business logic, including cloud connectivity, data sampling, firmware updates, configuration updates, and user interactions.
 
 ## Messages
 
+The main module does not implement messages available to other modules. Instead, it processes messages from other modules to control the application's behavior.
+It subscribes to messages on the following zbus channels:
+
+The Main module uses the following zbus channels, both for subscribing to incoming data and publishing outbound requests or status updates:
+
+* **BUTTON_CHAN**
+  - Processes user button presses for manually triggering data samples.
+
+* **CLOUD_CHAN**
+  - Receive connectivity status (connected, disconnected) and cloud response data.
+  - Trigger device shadow polling to retrieve configuration updates.
+
+* **ENVIRONMENTAL_CHAN**
+  - Request sensor data from the environmental module.
+
+* **FOTA_CHAN**
+  - Poll for FOTA updates and manage the FOTA process.
+  - Apply FOTA updates to install the new firmware image.
+
+* **LED_CHAN**
+  - Update LED pattern to indicate system state.
+
+* **LOCATION_CHAN**
+  - Requests new location data when a sample is due.
+
+* **NETWORK_CHAN**
+  - Control LTE network connection.
+  - Track cellular connectivity events.
+  - Request network quality samples.
+
+* **POWER_CHAN**
+  - Request battery status.
+  - Initiate low-power mode.
+
+* **TIMER_CHAN**
+  - Handle timer events for sampling.
+
+
 ## Configurations
 
-Kconfig and device tree
+The Main module can be configured using the following Kconfig options:
+
+* **CONFIG_APP_LOG_LEVEL**
+  Controls logging level for the main module.
+
+* **CONFIG_APP_MODULE_TRIGGER_TIMEOUT_SECONDS**
+  Default data sampling interval.
+
+* **CONFIG_APP_REQUEST_NETWORK_QUALITY**
+  When enabled, requests network quality metrics during regular sampling.
+
+* **CONFIG_APP_MSG_PROCESSING_TIMEOUT_SECONDS**
+  Maximum time allowed for processing a single message.
+
+* **CONFIG_APP_WATCHDOG_TIMEOUT_SECONDS**
+  Defines the watchdog timeout for the main module.
+
+
+## State Diagram
+
+The Main module implements a hierarchical state machine with the following states:
+
+```mermaid
+stateDiagram-v2
+    [*] --> STATE_RUNNING
+
+    state STATE_RUNNING {
+        [*] --> STATE_IDLE
+
+        STATE_IDLE --> STATE_TRIGGERING : CLOUD_CONNECTED_READY_TO_SEND
+        STATE_TRIGGERING --> STATE_IDLE : CLOUD_DISCONNECTED/CLOUD_CONNECTED_PAUSED
+
+        state STATE_TRIGGERING {
+            [*] --> STATE_SAMPLE_DATA
+            STATE_WAIT_FOR_TRIGGER --> STATE_SAMPLE_DATA : timer_trigger/button_press
+
+            STATE_SAMPLE_DATA --> STATE_WAIT_FOR_TRIGGER : LOCATION_SEARCH_DONE
+        }
+    }
+
+    STATE_RUNNING --> STATE_FOTA : FOTA_DOWNLOADING_UPDATE
+
+    state STATE_FOTA {
+        [*] --> STATE_FOTA_DOWNLOADING
+
+        STATE_FOTA_DOWNLOADING --> STATE_FOTA_WAITING_FOR_NETWORK_DISCONNECT : FOTA_SUCCESS_REBOOT_NEEDED
+        STATE_FOTA_DOWNLOADING --> STATE_FOTA_WAITING_FOR_NETWORK_DISCONNECT_TO_APPLY_IMAGE : FOTA_IMAGE_APPLY_NEEDED
+
+        STATE_FOTA_WAITING_FOR_NETWORK_DISCONNECT --> STATE_FOTA_REBOOTING : NETWORK_DISCONNECTED
+
+        STATE_FOTA_WAITING_FOR_NETWORK_DISCONNECT_TO_APPLY_IMAGE --> STATE_FOTA_APPLYING_IMAGE : NETWORK_DISCONNECTED
+        STATE_FOTA_APPLYING_IMAGE --> STATE_FOTA_REBOOTING : FOTA_SUCCESS_REBOOT_NEEDED
+
+        STATE_FOTA_REBOOTING --> [*] : sys_reboot()
+    }
 
-## State diagram
+    STATE_FOTA --> STATE_RUNNING : FOTA_DOWNLOAD_CANCELED/TIMED_OUT/FAILED
+```