Payload Format of tag XL
Configurable Parameters - Device Defaults and Parameter Limits
All listed parameters must be stored in the NVM. All adjusted values through downlinks must remain the same after a device reset or power down.
| Configuration Name | Default Value | Minimum | Maximum | Unit | Description |
|---|---|---|---|---|---|
| MOVING_INTERVAL | 300 | 120 | 65535 | seconds | Default value for localization fixes if the device is in motion. |
| STEADY_INTERVAL | 900 | 120 | 65535 | seconds | Default value for localization fixes if the device is not in motion. |
| HEARTBEAT_INTERVAL | 1 | 1 | 255 | hours | Heartbeat message interval. |
| BLE_FWU_ENABLED | 1 | 0 | 1 | - | BLE firmware update over the air enabled. |
| ADVERTISEMENT_FWU_INTERVAL | 30 | 5 | 255 | seconds | Time period during which the device opens the BLE advertisement for firmware updates. |
| GNSS_ENABLE | 1 | 0 | 1 | - | GNSS scanning enabled. |
| WIFI_ENABLE | 1 | 0 | 1 | - | WiFi scanning enabled. |
| ACCELERATION_ENABLE | 1 | 0 | 1 | - | Acceleration sensor enabled. |
| ACCELERATION_SENSITIVITY | 300 | 0 | 16000 | milli-g | Acceleration sensor threshold. |
| ACCELERATION_DELAY | 1500 | 1000 | 65535 | milliseconds | After a threshold detection, the device must remain in movement for at least the specified time to be considered a valid movement. |
Message Types
| Port | Name | Type | Description |
|---|---|---|---|
| 151 | Settings Downlink | Downlink | Contains a list of setter, getter and/or runner commands. |
| 151 | Settings Uplink | Uplink | Contains a list of device and/or runner settings. Sent in different situations. |
| 192 | GNSS-NG Localization Message | Uplink | One or more of these messages are sent after a successful GNSS-NG scan. |
| 197 | Wi-Fi Localization Message | Uplink | Sent after a successful Wi-Fi scan. |
Uplinks
Settings Uplink
A settings uplink is sent on port 151. The TLV payload format shall be used. It is defined as:
| Tag | Length | Number of Commands | Data |
|---|---|---|---|
| 0x4C | Variable number (uint8_t) | Variable number (uint8_t) | Commands in TLV format |
The settings uplink contains one or more settings in its data section. These settings are again in TLV format and are either device or runner settings:
| # | Device Setting | Tag | Size | Data | Format |
|---|---|---|---|---|---|
| 1 | Device Flags | 0x40 | 0x01 | bit 0: BLE_FWU_ENABLED bit 1: GNSS_ENABLE bit 2: WIFI_ENABLE bit 3: Set ACCELERATION_ENABLE bit 4-7: RFU | bit field |
| 2 | Asset Tracking Intervals | 0x41 | 0x04 | data 0: MOVING_INTERVAL data 1: STEADY_INTERVAL | uint16_t[2] |
| 3 | Acceleration Sensor Settings | 0x42 | 0x04 | data 0: ACCELERATION_SENSITIVITY data 1: ACCELERATION_DELAY | uint16_t[2] |
| 4 | HEARTBEAT_INTERVAL | 0x43 | 0x01 | Heartbeat interval in hours | uint8_t |
| 5 | ADVERTISEMENT_FWU_INTERVAL | 0x44 | 0x01 | Value in seconds | uint8_t |
| 6 | Battery Voltage | 0x45 | 0x02 | Battery voltage in mV | uint16_t |
| 7 | Firmware Hash | 0x46 | 0x04 | First 4 bytes of SHA-1 hash of git commit | uint8_t[4] |
| # | Runner Setting | Tag | Size | Data | Format |
|---|---|---|---|---|---|
| 1 | Run Alarm | 0x80 | 0x02 | data 0: Duration of started alarm in minutes (min: 0, max: 255) data 1: Period of alarm beeps in seconds (min: 0, max: 255) | uint8_t[2] |
GNSS-NG Localization Message
A GNSS-NG localization message is sent on port 192 (see Modem Service Protocol Payloads). One or more of these messages are sent after a successful GNSS-NG scan. They are generated by the Semtech's geolocation middleware. Please read the documentation of the geolocation middleware for more information.
Wi-Fi Localization Message
A Wi-Fi localization message is sent on port 197 (see Modem Service Protocol Payloads). This message is sent after a successful Wi-Fi scan. It is generated by the Semtech's geolocation middleware. Please read the documentation of the geolocation middleware for more information.
Message Usage
Welcome Messages
A welcome message is sent every time the device successfully joined to a LoRaWAN network (unconfirmed). It corresponds to a settings uplink for the tags [0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46]. Therefore, it contains all settings of the device including the battery voltage and the firmware hash.
Heartbeat Messages
A heartbeat message is sent at a fixed interval (unconfirmed). The HEARTBEAT_INTERVAL is stored in the settings. A heartbeat message corresponds to a settings uplink for the tag 0x45. Therefore, it only contains the battery voltage. If the HEARTBEAT_INTERVAL is adjusted via a settings downlink, a heartbeat message is sent immediately and the new interval is used for the next heartbeat message.
Settings Messages
For every received setting downlink, the device takes the actions for the received commands and sends a confirmed settings uplink. The actions are summarized in the following list:
- Setter command: Is used to change the value of a setting. First, the range of the value is checked. If the value is in the valid range, it is stored in NVM. The current value of the setting is added to the settings uplink.
- Getter command: Is used to read the value of a setting. The current value of the setting is added to the settings uplink.
- Runner command: Is used to execute an action with the given runner settings. The applied runner settings are added to the settings uplink.
The settings uplink uses the same order of settings as the commands of downlink that it received before. For example, if the received downlink contains the commands with tags [0x22, 0x20, 0x44, 0x80], the uplink will contain the settings with tags [0x42, 0x40, 0x44, 0x80]. The value of the settings correspond to the value of the applied settings. If one of the commands in the downlink tried to set a setting to a value out of range, the corresponding setting will not be changed. Hence, the settings uplink will contain the last value that was applied successfully instead of the value that was requested by the downlink.
Settings Messages with Alarm Command
If a setting downlink contains the alarm runner command 0x80 an alarm with the specified duration and interval is started. The parameters are stored in RAM, not in NVM. The device exits the alarm mode after the specified duration has elapsed. A running alarm is stopped if an alarm downlink is received with either duration or interval set to 0 (or both). As for other settings downlinks, the device sends a confirmed settings uplink after a downlink with alarm runner command. The uplink confirms the duration and interval that were used to start or stop the alarm.
Downlinks
Settings Downlink
A settings downlink is sent on port 151. The TLV payload format shall be used. It is defined as:
| Tag | Length | Number of Commands | Data |
|---|---|---|---|
| 0x4C | Variable number (uint8_t) | Variable number (uint8_t) | Commands in TLV format |
The settings downlink contains one or more commands in its data section. These commands are again in TLV format and are either setter, getter or runner commands:
| # | Setter Command | Tag | Size | Data | Format |
|---|---|---|---|---|---|
| 1 | Set Device Flags | 0x20 | 0x01 | bit 0: BLE_FWU_ENABLED bit 1: GNSS_ENABLE bit 2: WIFI_ENABLE bit 3: Set ACCELERATION_ENABLE bit 4-7: RFU | bit field |
| 2 | Set Asset Tracking Intervals | 0x21 | 0x04 | data 0: MOVING_INTERVAL data 1: STEADY_INTERVAL | uint16_t[2] |
| 3 | Set Acceleration Sensor Settings | 0x22 | 0x04 | data 0: ACCELERATION_SENSITIVITY data 1: ACCELERATION_DELAY | uint16_t[2] |
| 4 | Set HEARTBEAT_INTERVAL | 0x23 | 0x01 | Heartbeat interval in hours | uint8_t |
| 5 | Set ADVERTISEMENT_FWU_INTERVAL | 0x24 | 0x01 | Value in seconds | uint8_t |
| # | Getter Command | Tag | Size | Data | Format |
|---|---|---|---|---|---|
| 1 | Get Device Flags | 0x40 | 0x00 | - | - |
| 2 | Get Asset Tracking Intervals | 0x41 | 0x00 | - | - |
| 3 | Get Acceleration Sensor Settings | 0x42 | 0x00 | - | - |
| 4 | Get HEARTBEAT_INTERVAL | 0x43 | 0x00 | - | - |
| 5 | Get ADVERTISEMENT_FWU_INTERVAL | 0x44 | 0x00 | - | - |
| 6 | Get Battery Voltage | 0x45 | 0x00 | - | - |
| 7 | Get Firmware Hash | 0x46 | 0x00 | - | - |
| # | Runner Command | Tag | Size | Data / Description | Format |
|---|---|---|---|---|---|
| 1 | Run Alarm | 0x80 | 0x02 | data 0: Duration of alarm in minutes (min: 0, max: 255) data 1: Period of alarm beeps in seconds (min: 0, max: 255) | uint8_t[2] |
| 2 | Reset device | 0x81 | 0x00 | Triggers a system reset on the device | - |