The four protocols supported by Modem Service are distinguished by the msgtype field and/or
the port.The following default port-protocol-mapping applies unless otherwise configured via Configure Device Ports:
msgtype Protocols Default Port updf Modem Protocol 199 updf LoRa Edge GNSS positioning protocol 198 updf LoRa Edge GNSS-NG (NAV-Group) positioning protocol 192 updf LoRa Edge Wi-Fi positioning protocol 197
The following msgtype-protocol-mapping applies for non-LoRaWAN transports:
Modem Protocol
The modem messages are exchanged between a modem and Modem Service over the configured modem
port. These messages are sent and processed directly by the modem. Applications control the modem
functionality via the modem device API and the LoRa Cloud API and are not required
to inspect messages to use of the modem management features.
LoRa Edge GNSS positioning protocol
The LoRa Edge GNSS positioning messages consist of a single tag-value pair per message in uplink and
downlink direction. Their purpose is to deliver GNSS scan results to the geolocation solver and
communicate aiding information adjustments back to the device.
LoRa Edge GNSS positioning uplink messages are generated directly by a LoRa Edge chip and can be retrieved using the
GNSSReadResults command (See the LoRa Edge User Manuals for more details).
Note: The response to the LoRa Edge chip’s GNSSReadResults SPI command starts with a destination byte.
For successful GNSS scans, the destination byte is always 0x01.
This destination byte is not part of the GNSS positioning message and must be removed before transmitting the message.
Uplink Message:
Downlink Message:
The following tag-value pairs are defined:
| Direction | Tag | Value | Value length | Description |
|---|---|---|---|---|
| Uplink | 0x00 | U-GNSSLOC-REQAID | 0 bytes | Aiding position request |
| Uplink | >0x00 1 | U-GNSSLOC-NAV | variable | Navigation message (NAV1/NAV2/NAV3) |
| Downlink | 0x00 | D-GNSSLOC-AIDP | 3 bytes | Aiding position update |
- 1
- LoRa Edge GNSS positioning protocol uplink messages with non-zero tag byte are Navigation messages.
U-GNSSLOC-REQAID – 0x00: Aiding position request
The value of the REQAID message is empty.
All LoRa Edge GNSS positioning protocol uplink messages with non-zero tag byte are Navigation messages (NAV messages).
They carry the signal measurements which are necessary to compute a position solution.
Navigation messages come in three versions, NAV1, NAV2, and NAV3, depending on the microcode version which runs on LoRa Edge chipset.
Description of the fields:
- TAG
- A NAV-internal tag byte. Depends on the internal structure of the NAV message. Non-zero.
- GNSS_SCAN_RES
- GNSS scan result containing GNSS signal measurements.
D-GNSSLOC-AIDP – 0x00: Aiding position update
Description of the fields:
- POS
An estimate of the device’s position encoded in WGS84 latitude/longitude coordinates.
Description of the fields:
- LAT = LAT_LSB | (LAT_MSB << 8)
- WGS84 latitude coordinate of the aiding position. Type:
int12, unit:180/2^12 deg- LON = LON_LBS | (LON_MSB << 4)
- WGS84 longitude coordinate of the aiding position. Type:
int12, unit:360/2^12 deg>
Examples:
Min Value:
POS='000880': LAT = -2048*180/2**12 [-90.000 deg], LON = -2048*360/2**12 [-180.000 deg]Max Value:
POS='fff77f': LAT = 2047*180/2**12 [ 89.9560 deg], LON = 2047*360/2**12 [ 179.912 deg]
LoRa Edge GNSS-NG (NAV-Group) positioning protocol
The LoRa Edge GNSS NAV-Group protocol allows to combine multiple NAV-messages into groups
which are evaluated as multi-frame GNSS solver requests.
The device-side implementation of this protocol is available as part of the LoRa Basics Modem Geolocation
SDK (SWSD004) starting from version 1.2.0.
Grouping of NAV-messages is done with the help of the U-GNSSNG-NAV payload of the GNSS-NG protocol:
The U-GNSSNG-NAV payload consists of a 1-byte Group Header Byte (GHDR) followed by a single U-GNSSLOC-NAV record. The purpose of the GHDR byte is to flag NAV-messages, which result from a staticposition and thus can be combined into a multi-frame solution. Such multi-frame solutions from a static positionare more precise and have a higher chance of resulting in a position solution.
Description of the fields:
- GHDR
Group Header.
Description of the fields:
- EOG
- End of Group Flag. When set to 1, the device indicates that the NAV-messages of the group should be evaluated to a position.
- RFU
- Reserved for future use. Must be set to
0b00.- GRP_TOKEN
- The group token is a 5-bit unsigned integer ranging from 2 to 31 (including). Values 0 and 1 are not allowed. Upon reset,
the first value of the group token must be chosen as a random value between 2 and 31 (including) and is incremented by 1 for each
new group thereafter. Group token 31 is followed by 2.
Subsequent messages with a constant group token value are associated to the same group.- <
- U-GNSSLOC-NAV*
- A message of type U-GNSSLOC-NAV which gets added to the current group. Note, that U-GNSSLOC-REQAID is not an allowed value.
In addition to the encoding of grouped NAV messages, the GNSS-NG protocol allows to exchange control flow information via
Extension messages:
Extension messages
Uplinks:
Extention messages in uplink direction are identified by the Extension Marker EXT_MRK which is the second byte set to 0.
If EXT_MRK is not 0, then the message is interpreted as a U-GNSSNG-NAV message.
If EXT_MRK is 0, then the message is interpreted according as a Tag-Value-Pair according to the following structure:
Downlinks:
In downlink direction, the messages are always Tag-Value-Pairs:
The following tag-value pairs are defined for up- and downlink directions:
| Direction | Tag | Value | Value length | Description |
|---|---|---|---|---|
| Uplink | 0x00 | U-GNSSNG-APC0 | 3 bytes | Aiding position check type 0 |
| Uplink | 0x01 | U-GNSSNG-APC1 | variable | Aiding position check type 1 |
| Downlink | 0x00 | D-GNSSNG-AIDP | 3 bytes | Aiding position update |
U-GNSSNG-APC0 – 0x00: Aiding Position Check Type 0
The purpose of the Aiding Position Check Type 0 message is to allow the device to request a new assistance position.
The device could trigger this message when it has indication that the current available assistance position has an error
which is larger than 150 km with the respect to the device’s current position.
The intent of this message is to trigger a D-GNSSNG-AIDP downlink message which updates the device’s assistance position
with a new value. LoRa Cloud may infer this value from various sources, including but not limited to the
gnss_assist_position API parameter and the WiFi position history.
Description of the fields:
- POS
- Coordinates of the current aiding position of the device. Encoded as in D-GNSSLOC-AIDP.
U-GNSSNG-APC1 – 0x01: Aiding Position Check Type 1
The purpose of the Aiding Position Check Type 1 message is to allow the device to request a new assistance position while
simultaneously providing an autonomous scan result as an indication for its current position.
The device could trigger this message when it has indication that the current available assistance position has an error
which is larger than 150 km with the respect to the device’s current position.
The doppler observations contained in the NAV message will be used to calculate an updated assistance position and
D-GNSSNG-AIDP downlink is triggered. In case the NAV message does not yield any result, the U-GNSSNG-APC1 message
is treated as a Type 0 (U-GNSSNG-APC0) message.
Description of the fields:
- POS
- Coordinates of the current aiding position of the device. Encoded as in D-GNSSLOC-AIDP.
- NAV
- A message of type U-GNSSLOC-NAV from an autonomous scan which can be used to calculate a more accurate assistance position.
Note, that U-GNSSLOC-REQAID is not an allowed value.
D-GNSSNG-AIDP – 0x00: Aiding position update
The aiding position downlink message is identical to D-GNSSLOC-AIDP. It can be sent in response to any U-GNSSNG-* uplink message.
Description of the fields:
- POS
- Coordinates of the new aiding position of the device. Encoded as in D-GNSSLOC-AIDP.
LoRa Edge Wi-Fi positioning protocol
The Wi-Fi positioning protocol messages consist of a single tag-value pair per message in uplink direction.
Downlinks are not defined for this protocol.
The following tag-value pairs are defined:
| Direction | Tag | Value | Value Length | Description |
|---|---|---|---|---|
| Uplink | 0x00 | U-WIFILOC-MAC | N*6 bytes | Wi-Fi AP list |
| Uplink | 0x01 | U-WIFILOC-MACRSSI | N*7 bytes | Wi-Fi AP list with RSSI |
N: Number of scanned APs
U-WIFILOC-MAC – 0x00: Wi-Fi AP MAC List
Description of the fields:
- MAC
- MAC address of scanned AP. See MAC Address Encoding.
U-WIFILOC-MACRSSI – 0x01: Wi-Fi AP MAC List with RSSI
Description of the fields:
- RSSI
- RSSI associated to AP in dB. 8-bit signed integer.
- MAC
- MAC address of scanned AP. See MAC Address Encoding.
MAC Address Encoding
A 48-bit MAC address denoted as M6:M5:M4:M3:M2:M1 is encoded in:
where
- M6
- Most significant byte of MAC address.
- M1
- Least significant byte of MAC address.