Application downlink
This section defines the downlinks sent by the network. The network can be either LoRaWAN or LTE.
Message header
The uplinks are composed by a common header followed by a data part. The data part content depends on the downlink type.
Basic header
The basic header has a single byte. The multi-frame mode is not supported for downlink messages (since an uplink is needed to trigger the downlink message in LoRaWAN class A).
Basic header
Byte 0 | ||
b7-6 | b5-3 | b2-0 |
F | Type | ACK-TK |
Byte 0 description
- F. Free for use.
- Type. Frame type.:
- 1 -- Command. Commands are neither acknowledged nor answered (Reset, BLE bootloader, SOS enter/leave, and so on).
- 2 -- Request. Requests expect a response uplink.
- 3 -- Answer. Answer a query from the tracker.
- ACK-TK: Ack-token. Value (in [0..7]) extracted from the last downlink received. It is used to acknowledge the downlinks.
Commands
The commands do not expect either responses or statuses from the tracker. The proper receipt and execution of a command can be inferred by analyzing the ACK-TK field of uplinks received after sending the command.
The format of a command is the following
| Byte 0 | Byte 1 | Variable |
|---|---|---|
| Basic header (Type =1) | Command | Data |
Note
- Byte 0. Basic header with type = 1
- Byte 1. Command:
- 0 -- Clear the config in flash and reset the tracker
- 1 -- Reset the tracker
- 2 -- Start SOS
- 3 -- Stop SOS
- 4 -- System status request
- 5 -- Position-On-Demand (POD)
- 6 -- Set GPS almanac
- 7 -- Set BEIDOU almanac
- 8 -- Start BLE connectivity
- 9 -- Stop BLE connectivity
- 10 -- System event
Set GPS almanac
This command is used to setup GPS almanac entries. The format of the data part is the following
| Common | Almanac entry 1 | Almanac entry 2 | ... |
|---|---|---|---|
| 2 bytes | 16 bytes | 16 bytes | … |
| Date | Data-entry 1 | Data-entry 2 | ... |
Notes
- Date: Number of days since April 7^th^ 2019. Big endian.
- Data-entry is formatted as follow:
Almanac Entry | |
1 byte | 15 bytes |
SV ID | Almanac data |
- SV-ID: Satellite identifier in the constellation. Starts at index 0.
- It's up to the server to adapt the number of entries to send based on the network type (LoRaWAN or Cellular) and the data-rate used for the downlink if LoRaWAN is used. However, the maximum size of 255 (full downlink size including network encapsulation) must be respected.
Set BEIDOU almanac entry request
TO BE DONE.
System event command
This command offer the possibility to trigger events, the possible events are related to user class and core class.
The format of the data part is the following:
| Class id | Event type |
|---|---|
| 1 byte | 1 byte |
Requests
Downlink requests expect a response from the tracker.
The format of a request is the following
| Byte 0 | Byte 1 | Bytes [2-variable] |
|---|---|---|
| Basic header (Type =2) | Request | Data |
Note
- Byte 0. Basic header with type = 2.
- Byte 1. Request types:
- 0 -- Generic configuration set request.
- 1 -- Parameter class configuration set request.
- 2 -- Generic configuration get request.
- 3 -- Parameter class configuration get request.
- 4 -- BLE connectivity status request.
Generic configuration set request
This request is used to configure any parameter in the tracker. This downlink should be used when multiple classes of parameters are affected by the downlink.
The data part is a list of parameter entries as defined below. Note that the format is the same than the answer of generic configuration get request from the tracker.
Parameter entry 1 | … | |||
3 Bytes | Variable | ... | ||
C-ID | L-ID | S/T | Data | ... |
Notes
- C-ID. Parameter class identifier
- L-ID: Local parameter identifier
- S/T: Parameter size and type
- Bit 7-3: Variable size
- Bit 2-0: type
- 0 -- Deprecated
- 1 -- Integer 32 bits
- 2 -- Floating point (4 bytes)
- 3 -- ASCII string
- 4 -- Byte array
- Data: Variable data part
- Deprecated. No data.
- Integer 32 bits. 4 bytes in big endian (MSB first)
- Floating point. Single precision, 4 bytes n big endian (MSB first)
- ASCII string. Max 31 characters. It should exclude the NULL char.
- Byte array. Max 32 bytes. For 32 bytes, the parameter size will be 0.
This message is answered by the tracker with the answer of generic configuration set request.
Parameter class configuration set request
This request is used to configure a single parameter class in the tracker. Multiple parameters belonging to this class can be modified.
The data part is a list of parameter entries as defined below. Note that the format is the same than the answer of a parameter class get request from the tracker.
Common | Parameter entry 1 | Parameter entry 2 | … | ||||
1 Byte | 2 Bytes | Variable | 2 Bytes | Variable | ... | ||
C-ID | L-ID | S/T | Data | L-ID | S/T | Data | ... |
Notes
- C-ID. Parameter class identifier. This field appears only once per message.
- L-ID: Local parameter identifier
- S/T Parameter size and type.
- Bit 7-3: Parameter size
- Bit 2-0: type
- 0 -- Deprecated
- 1 -- Integer 32 bits
- 2 -- Floating point (4 bytes)
- 3 -- ASCII string
- 4 -- Byte array
- Data: Variable data part
- Deprecated. No data
- Integer 32 bits. 4 bytes in big endian (MSB first)
- Floating point. Single precision, 4 bytes n big endian (MSB first)ASCII string. Max 31 characters. It should exclude the NULL char
- Byte array. Max 32 bytes. For 32 bytes, the parameter size will be 0
This message is answered by the tracker with the answer of a parameter class set request.
Generic configuration get request
This request is used to query some configuration parameters from the tracker. This downlink should be used when multiple classes of parameters are affected by the downlink.
The data part is a list of parameter entries as defined below.
2 Bytes | 2 Bytes | ... | ||
C-ID | L-ID | C-ID | L-ID | ... |
Notes
- C-ID. Parameter class identifier
- L-ID: Local parameter identifier
This message is answered by the tracker with the answer of generic configuration get request.
Parameter class configuration get request
This request is used to query configuration parameters belonging to a same parameter
The data part is a list of parameter entries as defined below.
| 1 Byte | 1 Byte | 1 Byte | ... |
|---|---|---|---|
| C-ID | L-ID | L-ID | ... |
Notes
- C-ID. Parameter class identifier. This field appears only once per message
- L-ID: Local parameter identifier
This message is answered by the tracker with the answer of a parameter class get request.
BLE connectivity status request
This request is used to query the BLE connectivity status, There is no data part for this request.
Answers
The answers are responses to the tracker queries.
The format of a request is the following
| Byte 0 | Byte 1 | Bytes [2-variable] |
|---|---|---|
| Basic header (Type =3) | Answer type | Data |
Note
- Byte 0. Basic header with type = 3.
- Byte 1. Answer types matches the query type:
- 0 -- Aiding-position. The aiding position is needed by the tracker.
- 1 -- Update system time. The system time update is needed.
- 2 -- Update GPS almanac. GPS almanac entries need to be refreshed. Data contains the list of satellites for which the update is needed.
- 3 -- Update BEIDOU almanac. BEIDOU almanac entries need to be refreshed. Data contains the list of satellites for which the update is needed.
Aiding position
TO BE DEFINED
Update system time
TO BE DEFINED
Update GPS almanac
This answer is used to setup GPS almanac entries. The format of the data part is the following
| Common | Almanac entry 1 | Almanac entry 2 | ... |
|---|---|---|---|
| 2 bytes | 16 bytes | 16 bytes | … |
| Date | Data-entry 1 | Data-entry 2 | ... |
Notes
- Date: Number of days since April 7^th^ 2019 in big endian format.
- Data-entry is formatted as follow:
Almanac Entry | |
1 byte | 15 bytes |
SV ID | Almanac data |
- SV-ID: Satellite identifier in the constellation. Start at 0.
- Due to the limited payload size on the LoRa network (EU868, DR0-2, Max: 59 bytes), only 3 entries can be updated in a downlink.