Smart label v2

docs/02 - Getting-started/06-smart-label-v2.md

@@ -0,0 +1,80 @@
+---
+sidebar_label: smart label v2
+---
+
+# Getting Started Guide for the Smart Label v2
+
+### This document details the step-by-step instructions about how to set up the Truvami smart label.
+
+<br></br>
+:bulb: Installation instructions are available in the [Smart Label Onboarding](https://github.com/user-attachments/files/22113240/Template.Smart.Label.Pilot.Onboarding.pdf) document <br></br>
+<br></br>
+
+
+
+<!-- ![Bild 1](/img/getting-started-imgs/tag_s_side.png) -->
+<img src="/img/smart_label/SL_LED_OFF.png" width="75%" height="auto"/>
+
+
+#### 1. Charge the Truvami® smart label
+The smart label uses the ambient indoor light as an energy source. The optimal exposure is around 1000 lux and a full charge can take up to 2 days. 
+
+:warning: **Warning:** Exposing the label to direct sunlight of high intensity is not advised as the organic photovoltaic cells of the smart label are not designed for these conditions.
+
+
+#### 2. Short press on the power button activates the tracker
+After pressing the power button and releasing it, the LED will blink 5 times in green. After a few seconds, the LED will blink again 3 times in green to indicate a successful join to the network. 
+
+<!-- ![Bild 2](/img/getting-started-imgs/tag_s_front.png) -->
+<img src="/img/smart_label/SL_LED_ON.png" width="75%" height="auto"/>
+
+
+```
+If the tracker cannot join the network, the LED will blink in red. 
+It will try automatically to join the network until being successful. 
+```
+
+
+#### 3. Click on the activation link that you have received by email
+
+It will take you to the https://dashboard.truvami.com page where you can set your
+password.
+
+<img src="/img/getting-started-imgs/NowYourTrackingJourneyBegins.webp" width="75%" height="auto"/>
+
+
+
+## Troubleshooting
+
+In the event that the device fails to join, consider the following list of workarounds:
+
+#### 1. Check your LoRaWAN coverage.
+If applicable, plug in your LoRaWAN Gateway. In case you have your own network server, check on there if data is coming through.
+
+#### 2. Check if battery is fully charged: 
+Leave the smart label exposed to constant indoor lighting for one day and try step 2 again.
+
+#### 3. Reset the Smart Label
+
+To reset your Truvami Smart Label, you will need to switch it off and then switch it on again.
+
+##### Steps
+###### Switch Off
+
+- Press and hold the power button firmly for 10 seconds.
+
+- Release the button – the device will power down.
+
+###### Switch On
+
+- Press the power button firmly for 1 second..
+
+- The device will restart and is now reset.
+
+:::warning Support 
+<br></br>
+For support, please submit a ticket. We will provide support as promptly as possible. <br></br>
+<br></br>
+
+[**Click here to open a new ticket**](https://truvami.com/service-request/)
+:::

docs/04 - Devices/06 - smart label v2/02_sw_spec.md

@@ -0,0 +1,195 @@
+---
+sidebar_label: Functional Description 
+---
+
+# Functional Description 
+
+## Overview
+
+Software for an energy-efficient, LoRaWAN class A, indoor/outdoor asset tracking device capable of performing localization, movement detection and temperature and battery measurement. Based on the FMLR-LR1110 and LBM4 stack. 
+
+Main functionality: 
+- Localization through passive GNSS, WiFi sniffing, LoRa TDoA
+- Indoor recognition with fall-back to WiFi sniffing
+- Movment detection and configurable steady- and moving-intervals for localization triggering
+- Temperature and battery voltage measurement with heartbeat uplink and configurable interval
+- Configuration through LoRaWAN downlink
+- LED for visual feedback of application state
+- EU868/US915 compatibility
+
+
+
+
+
+## State Diagramm
+<img src="/img/smart_label/fsm.svg" width="100%" height="auto"/>
+
+
+
+
+
+## Class Diagram
+<img src="/img/smart_label/class.svg" width="60%" height="auto"/>
+
+
+# Features Overview
+
+# Features
+
+## Functional requirements
+
+### F-001: Interval-triggered localization
+
+In absence of movements, localization will be performed after the interval __steady_interval_s__. After a movmement-triggered localization the interval used to trigger the next interval-triggered localization is __moving_interval_s__ instead.
+
+### F-002: Movement-triggered localization 
+
+After the detection of a movement, localization is performed. Movements are detected with a LIS2DW accelerometer. The logic for a successfull movement detection is as follows:
+
+- Detected acceleration is greater than the configured threshold __acc_threshold__ for at least the configured delay __acc_delay_ms__.
+
+After a movement-triggered localization, the interval __moving_interval_s__ is used to trigger the following interval-triggered localization. An __hold_timer__ will ensure that a localization doesn't happen to shortly after the previous one. The __hold_timer__ is set to the minimum between __steady_interal_s__ and __moving_interval_s__.
+
+### F-003: Localization type selection
+
+The device starts by performing a WiFi sniffing. If the number of sniffed WiFi AP is less than __minAP__, then a pasive GNSS localization is attempted. Otherwise, the device sends the WiFi UL without attempting a GNSS localization. 
+
+### F-004: Passive GNSS localization
+
+Localization can be performed using passive GNSS. The LoRa Basic Modem geolocation service 'GNSS scan & send' is used for this purpose with the following options:
+
+- MOBILE mode
+- GPS & BEIDU
+- SEND MODE, i.e. directly send the scan result if valid, __no buffering__.
+
+The default option is "SEND MODE".
+
+The almanac update is done autonmously, using the GNSS almanac demodulation service available with LR11xx radio chip (i.e. without using LoRa Cloud assistance).
+
+Refer to the LoRa Basic Modem geolocation services documentation for any further detail.
+
+### F-005: WiFi sniffing localization
+
+Localization can be performed using WiFi sniffing. The LoRa Basic Modem geolocation service 'WiFi scan & service' is used for this purpose with the following options:
+
+- SEND MODE, i.e. directly send the scan result, __no buffering__.
+
+Refer to the LoRa Basic Modem geolocation services documentation for any further detail.
+
+### F-006: LoRa TDoA localization
+
+Localization can also be performed using LoRa TDoA. This is handled completely in the cloud and no specific action must be performed by the software since any type of localization execution is followed by an uplink, needed in the cloud to perform LoRa TDoA localization.
+
+### F-007: Temperature  and battery measurement
+
+Temperature and battery voltage are measured every interval __heartbeat_interval_h__ (unit: hours). For the temperature a SHT3X sensor is used. The Battery voltage is inferred by measuring the internal reference voltage of the MCU. Temperature and battery data are sent in the heartbeat uplink.
+
+### F-008: Sleep
+
+If the software is not performing localization, movement detection or measurements, the MCU is put to sleep until the next action needs to be executed.
+
+### F-009: Configuration parameters
+
+| Parameter                  |  Type  |  Range   | Description | Default value |
+|----------------------------|--------|----------|-------------|-------------|
+| __steady_interval_s__      | UINT16 | 0..65535 | Interval for localization trigger while steady, in __seconds__ |21600|
+| __moving_interval_s__      | UINT16 | 0..65535 | Interval for localization trigger while moving, in __seconds__ |3600|
+| __temperature_polling_interval_s__      | UINT16 | 0..65535 | Interval for polling temperature sensor, in __seconds__ |900|
+| __temperature_uplink_hold_interval_s__      | UINT16 | 0..65535 | Interval for temperature measurement uplink if it is outside of threshold, in __seconds__ |3600|
+| __temperature_upper_threshold__                  | INT8  |  -127..128   | Temperature upper threshold to yield uplink from polling in __°C__ | 40 |
+| __temperature_lower_threshold__                  | INT8  |  -127..128   | Temperature lower threshold to yield uplink from polling in __°C__ | -5 |
+| __heartbeat_interval_h__   | UINT8  | 0..255   | Interval for temperature and battery measurement and uplink, in __hours__ | 12 |
+| __acc_threshold_mg__       | UINT16 | 0..65535 | Accelerometer threshold to start movement detection, in __mg__ | 300 |
+| __acc_delay_ms__           | UINT16 | 0..65535 | Acceleration delay for detecting movement, in __ms__ | 1500 |
+| __flags__                  | UINT8  |          | See flags description | 00111110 |
+| __lic_100_percent__           | UINT16 | 0..4000 | LIC 100% percentage VCELL voltage in __mV__ | 3800 |
+| __lic_80_percent__           | UINT16 | 0..4000 | LIC 80% percentage VCELL voltage in __mV__ | 3650 |
+| __lic_60_percent__           | UINT16 | 0..4000 | LIC 60% percentage VCELL voltage in __mV__ | 3500 |
+| __lic_40_percent__           | UINT16 | 0..4000 | LIC 40% percentage VCELL voltage in __mV__ | 3250 |
+| __lic_20_percent__           | UINT16 | 0..4000 | LIC 20% percentage VCELL voltage in __mV__ | 2850 |
+| __min_AP__           | UINT8 | 1..6 | Minimum amount of AP(s) to yield an uplink | 3 |
+
+__Flags__:
+| Bit 7 | Bit 6 | Bit 5 | Bit 4 | Bit 3 |Bits [2:0]|
+|-------|-------|-------|-------|-------|----------|
+|reserved|reserved|GNSS enable|WiFi sniffing enable|Acc enable|Data rate|
+
+
+Data rate: 
+
+000: DR5 (EU868 SF7), 
+
+001: DR4 (EU868 SF8), 
+
+010: DR3 (EU868 SF9, US915 SF7) [__DEFAULT__], 
+
+011: DR2 (EU868 SF10, US915 SF8), 
+
+100: DR1 (EU868 SF11, US915 SF9), 
+
+101: DR0 (EU868 SF12), 
+
+110: DR1-3 array (EU868 SF9-11, US915 SF7-9),  
+
+111: ADR (SF7-12 for EU868)
+
+Duty cycling is enabled by default to conform with regulations.
+### F-010: Power states
+
+In case the HW variant with the PV cell, LIC and harvester, different power states are introduced to preserve energy.
+
+__Approximate Energy-Based Voltage Levels (for LICs)__:
+
+| Energy % | Voltage |
+|-------|-------|
+|100%|3.8V|
+|80%|3.65V|
+|60%|3.5V|
+|40%|3.25V|
+|20%|2.85V|
+|0%|2.5V|
+
+
+__Power states:__
+* __Below 20%__: Send only 1 __Low Power battery uplink__ per day containing only voltage levels for the VCC and the PV Cell voltage
+* __Between 20-40%__: Normal operation with accelerometer disabled (No location trigger by accelerometer)
+* __Above 40%__: Normal operation
+
+VCC measurement is performed before power-intensive operations, eg. location acquisition, sending uplink, etc.
+
+### F-011: LoRaWAN Join procedure
+
+After Power-On the device will attemt to Join the LoRaWAN network with OTAA with a random __Spreading Factor__.
+
+In case the HW variant with the PV cell, LIC and harvester, the join procedure will not start until the LIC is at least 20% to avoid boot-loop.
+
+__Join back-off strategy__: (Standard LBMv4 strategy)
+
+* During first hour after first join try => duty cycle of 1/100 ie. 36s over 1 hour
+* During the 10 hours following first hour after first join try => duty cycle of 1/1000 ie. 36s over 10 hours
+* Following the first 11 hours after first join try => duty cycle of 1/10000 ie. 8.7s over 24 hours
+
+
+
+## External Interface Requirements
+
+### EI-001: Button
+
+The smart label has only one button:
+- Press 10 sec to switch off the label
+- Press 0.2 sec to switch on (5 green blinks)
+
+### EI-002: LED
+
+The LED on SmartLabel is used by the software as follows:
+- Power on: 5 consecutive 100ms green blinks
+- Join successful: 3 consecutive 100ms green blinks
+- Join failed: 3 consecutive 100ms red blinks
+
+### EI-003: Radio Specification
+
+The device operates on:
+ - LoRaWan
+ - Region EU868, US915
+ - Version 1.0.4
+ - Class A