Skip to content

Commit 04e3058

Browse files
DematteisGiacomoDematteisGiacomo
committed
docs: more docs
configurability and location services docs. Signed-off-by: Giacomo Dematteis <giacomo.dematteis@nordicsemi.no>
1 parent 8346fd5 commit 04e3058

File tree

4 files changed

+189
-23
lines changed

4 files changed

+189
-23
lines changed

‎docs/common/configurability.md

+142-8
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,151 @@
11
# Configurability
22

33
## Set sampling interval and logic from cloud
4-
- Instructions on setting sampling interval and logic from the cloud.
4+
5+
The Asset Tracker can be configured remotely through nRF Cloud's device shadow mechanism. This allows dynamic adjustment of device behavior without requiring firmware updates.
6+
7+
### Configuration through nRF Cloud UI
8+
9+
1. Log in to [nRF Cloud](https://nrfcloud.com/)
10+
2. Navigate to "Devices" and select your device
11+
3. Click on "View Config" in the top bar
12+
4. Select "Edit Configuration"
13+
5. Enter the desired configuration:
14+
```json
15+
{
16+
"update_interval": 60
17+
}
18+
```
19+
6. Click "Commit" to apply the changes
20+
21+
The device will receive the new configuration through its shadow and adjust its update interval accordingly.
22+
23+
24+
### Configuration Flow
25+
1. **Initial Setup**
26+
- Device starts with default interval from `CONFIG_APP_MODULE_TRIGGER_TIMEOUT_SECONDS`
27+
- Upon cloud connection, device automatically requests shadow configuration
28+
29+
2. **Runtime Configuration**
30+
- Cloud module receives and processes shadow updates
31+
- Device maintains last known configuration during offline periods
32+
33+
3. **Impact on Device Behavior**
34+
The update_interval configuration controls the frequency of:
35+
- Location updates
36+
- Sensor sampling (environmental, battery, network quality)
37+
- FOTA update checks
38+
- Shadow update polling
539

640
## Set location method priorities
7-
- Instructions on setting location method priorities.
41+
42+
The Asset Tracker supports multiple location methods that can be prioritized based on your needs. Configuration is done through board-specific configuration files.
43+
44+
### Available Location Methods
45+
- GNSS (GPS)
46+
- Wi-Fi positioning
47+
- Cellular positioning
48+
49+
### Configuration Examples
50+
51+
1. **Thingy91x Configuration** (wifi available):
52+
```
53+
CONFIG_LOCATION_REQUEST_DEFAULT_METHOD_FIRST_WIFI=y
54+
CONFIG_LOCATION_REQUEST_DEFAULT_METHOD_SECOND_GNSS=y
55+
CONFIG_LOCATION_REQUEST_DEFAULT_METHOD_THIRD_CELLULAR=y
56+
CONFIG_LOCATION_REQUEST_DEFAULT_WIFI_TIMEOUT=10000
57+
```
58+
59+
2. **nRF9151 DK Configuration** (wifi unavailable):
60+
```
61+
CONFIG_LOCATION_REQUEST_DEFAULT_METHOD_FIRST_GNSS=y
62+
CONFIG_LOCATION_REQUEST_DEFAULT_METHOD_SECOND_CELLULAR=y
63+
```
864

965
## Network configuration
10-
### NB-IoT vs M1
11-
- Explanation of NB-IoT vs M1.
1266

13-
### PSM
14-
- Explanation of PSM.
67+
### NB-IoT vs LTE-M
68+
The Asset Tracker supports both LTE Cat NB1 (NB-IoT) and LTE Cat M1 (LTE-M) cellular connectivity:
69+
70+
- **NB-IoT**: Optimized for:
71+
- Low data rate applications
72+
- Better coverage
73+
- Stationary or low-mobility devices
74+
75+
- **LTE-M**: Better suited for:
76+
- Higher data rates
77+
- Mobile applications
78+
- Lower latency requirements
79+
80+
#### Network Mode Selection
81+
The following network modes are available (`LTE_NETWORK_MODE`):
82+
83+
- **Default**: Use the system mode currently set in the modem
84+
- **LTE-M**: LTE Cat M1 only
85+
- **LTE-M and GPS**: LTE Cat M1 with GPS enabled
86+
- **NB-IoT**: NB-IoT only
87+
- **NB-IoT and GPS**: NB-IoT with GPS enabled
88+
- **LTE-M and NB-IoT**: Both LTE-M and NB-IoT enabled
89+
- **LTE-M, NB-IoT and GPS**: Both LTE modes with GPS enabled
90+
91+
#### Network Mode Preference
92+
When multiple network modes are enabled (LTE-M and NB-IoT), you can set preferences (`LTE_MODE_PREFERENCE`):
93+
94+
- **No preference**: Automatically selected by the modem
95+
- **LTE-M**: Prioritize LTE-M over PLMN selection
96+
- **NB-IoT**: Prioritize NB-IoT over PLMN selection
97+
- **LTE-M, PLMN prioritized**: Prefer LTE-M but prioritize staying on home network
98+
- **NB-IoT, PLMN prioritized**: Prefer NB-IoT but prioritize staying on home network
99+
100+
Example configuration in `prj.conf`:
101+
```
102+
# Enable both LTE-M and NB-IoT with GPS
103+
CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT_GPS=y
104+
105+
# Prefer LTE-M while prioritizing home network
106+
CONFIG_LTE_MODE_PREFERENCE_LTE_M_PLMN_PRIO=y
107+
```
108+
109+
### PSM (Power Saving Mode)
110+
PSM allows the device to enter deep sleep while maintaining network registration. Configuration is done through Kconfig options:
111+
112+
#### PSM Parameters
113+
1. **Periodic TAU (Tracking Area Update)**
114+
- Controls how often the device updates its location with the network
115+
- Configuration options:
116+
```
117+
# Configure TAU in seconds
118+
CONFIG_LTE_PSM_REQ_RPTAU_SECONDS=1800 # 30 minutes
119+
```
120+
121+
2. **Active Time (RAT)**
122+
- Defines how long the device stays active after a wake-up
123+
- Configuration options:
124+
```
125+
# Configure RAT in seconds
126+
CONFIG_LTE_PSM_REQ_RAT_SECONDS=60 # 1 minute
127+
```
128+
129+
Key aspects:
130+
- Device negotiates PSM parameters with the network
131+
- Helps achieve longer battery life
132+
- Device remains registered but unreachable during sleep
133+
- Wakes up periodically based on TAU setting
134+
- Stays active for the duration specified by RAT
135+
136+
137+
### APN (Access Point Name)
138+
The Access Point Name (APN) is a network identifier used by the device to connect to the cellular network's packet data network. Configuration options:
139+
140+
- **Default APN**: Most carriers automatically configure the correct APN
141+
- **Manual Configuration**: If needed, APN can be configured through Kconfig:
142+
```
143+
CONFIG_PDN_DEFAULT_APN="Access point name"
144+
```
145+
146+
Common scenarios for APN configuration:
147+
- Using a custom/private APN
148+
- Connecting to specific network services
149+
- Working with MVNOs (Mobile Virtual Network Operators)
15150
16-
### APN
17-
- Explanation of APN.
151+
Note: In most cases, the default APN provided by the carrier should work without additional configuration.

‎docs/common/location_services.md

+37-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,39 @@
11
# Location Services
22

3-
- Description of location services.
3+
The Asset Tracker uses nRF Cloud's location services to provide accurate device positioning through multiple methods. This document explains the available location services and their capabilities.
4+
5+
## Location Methods
6+
7+
The following location methods are supported:
8+
9+
1. **GNSS (Global Navigation Satellite System)**
10+
- Highest accuracy positioning
11+
- Best suited for outdoor use
12+
- Higher power consumption compared to other methods
13+
14+
2. **Cellular**
15+
- Uses cellular tower information for positioning
16+
- Works indoors
17+
- Lower power consumption than GNSS
18+
19+
3. **Wi-Fi**
20+
- Uses nearby Wi-Fi access points for positioning
21+
- Excellent for indoor positioning
22+
- Lower power consumption than GNSS
23+
24+
## Integration with nRF Cloud
25+
26+
The location data is automatically sent to nRF Cloud, allowing you to:
27+
- Track device location in the nRF Cloud portal
28+
- Analyze location history
29+
- Monitor location accuracy and methods used
30+
31+
## Power Considerations
32+
33+
Different location methods have different power consumption profiles:
34+
35+
1. GNSS: Highest power consumption, best accuracy
36+
2. Wi-Fi: Medium power consumption, good accuracy indoors
37+
3. Cellular: Lowest additional power consumption (modem already active), moderate accuracy
38+
39+
Each method offers a different balance between power consumption and accuracy, allowing you to choose the most appropriate method for your use case.

‎docs/common/test_and_ci_setup.md

+7-9
Original file line numberDiff line numberDiff line change
@@ -27,19 +27,19 @@ Only "fast" targets tests are run. Avoiding excessively time-consuming tests.
2727
- Nightly schedule: build-target-test.yml
2828
Full set of target tests. Includes "slow" tests such as full-modem-fw fota test and power consumption test.
2929

30-
### Testing
31-
32-
#### Hardware Testing
30+
### Hardware Testing
3331
The project includes tests that run on real hardware devices, implemented in the `.github/workflows/target-test.yml` workflow. Key features include:
3432

3533
Tests on target are performed on self-hosted runners.
36-
Read more here and how to set up your own instance for your project: https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners
34+
Read more here and how to set up your own instance for your project: [About Self Hosted](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners)
3735

3836

3937
- Tests run on multiple target devices:
4038
- nRF9151 DK
4139
- Thingy:91 X
4240
- Uses self-hosted runners labeled according to the connected device
41+
- Parallel orizontal execution across different device types
42+
- Parallel vertical execution on multiple same device jobs
4343
- Runs in a containerized environment with hardware access
4444
- pytest as test runner
4545
- Supports Memfault integration for symbol file uploads
@@ -48,17 +48,15 @@ Read more here and how to set up your own instance for your project: https://doc
4848

4949
Try out tests locally: tests/on_target/README.md
5050

51-
#### Emulation Testing
51+
### Emulation Testing
5252
Emulation tests are implemented as part of the SonarCloud workflow (`.github/workflows/sonarcloud.yml`). These tests:
5353

5454
- Run on the native_sim platform using Twister
5555
- Execute integration tests in an emulated environment
5656
- Generate code coverage reports
5757
- Use build wrapper for accurate code analysis
5858

59-
### Code Analysis
60-
61-
#### SonarCloud Analysis
59+
### SonarCloud Analysis
6260
The SonarCloud integration (`.github/workflows/sonarcloud.yml`) provides:
6361

6462
- Static code analysis for C/C++ files
@@ -67,7 +65,7 @@ The SonarCloud integration (`.github/workflows/sonarcloud.yml`) provides:
6765
- Continuous monitoring of code quality metrics
6866
- Separate analysis configurations for main branch and pull requests
6967

70-
#### Compliance Testing
68+
### Compliance Testing
7169
Compliance checks are implemented in `.github/workflows/compliance.yml` and include:
7270

7371
- Codeowners validation

‎docs/modules/button.md

+3-5
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,9 @@
11
# Button module
22

3-
What does this module do
3+
The button module provides button press event handling functionality for the application. It uses the `dk_buttons_and_leds` library to detect button presses and publishes these events through a zbus channel for other modules to consume.
44

55
## Messages
66

7-
## Configurations
7+
### Output Messages
88

9-
Kconfig and device tree
10-
11-
## State diagram
9+
- **BUTTON_CHAN**: The module publishes button events through the `BUTTON_CHAN`.

0 commit comments

Comments
 (0)