Overview

Modem and Geolocation Services

Modem and Geolocation Services offer a family of services and sets of API endpoints to complete or extend the functionality of LoRa® transceivers, Semtech modems or LoRa® end devices in LoRa® networks:

• Modem Service: This service implements the server-side engine of the Modem protocols and exposes an HTTP API. The protocols are driven by clients submitting received modem uplinks to the Modem Service which then updates and maintains an internal modem device state. Dependent on the modem uplinks, the service returns downlink messages, completed file uploads (Large File Upload), received streaming records (see Reliable Data Stream) or resolved positions (see LoRa Edge Platform). The virtual device state can be queried, and management commands be triggered, by the client at any time. The Modem Service and protocol especially support all geolocation features of the LoRa Edge™ chip portfolio (see LoRa Edge Platform).

• Geolocation Services for LoRa Edge transceivers: The Geolocation API Primitives allow requesting location estimates based on GNSS or Wi-Fi scan results from custom solutions based on LoRa Edge transceivers without modem features.

• Geolocation Services for network-centric LoRa® metadata: Device location estimates can be calculated from the metadata of LoRa® radio frames (RSSI, SNR, and TOA). The Geolocation Services accept time of arrival (TOA) and/or RSSI/SNR information information (along with the geolocation information of the receiving gateways) to calculate a location. At minimum, the Geolocation Services require the metadata for at least one radio frame of a device (single-frame mode). Accuracy can be improved by specifying the history of a device, i.e. multiple radio frames (multi-frame mode).

Note

Because the Modem Service operates on decrypted LoRaWAN® payloads, it can be used with any LoRaWAN network server. The service does not interact directly with any network server to retrieve uplinks or schedule downlinks. It is the client’s responsibility to forward uplink messages to the Modem Service, and to schedule the downlink messages which are part of the response.

LoRa Edge Platform

Introduction

LoRa Edge is an ultra-low-power platform, with chips such as the LR1110 and LR1120, that integrate a long range LoRa® transceiver, multi-constellation scanner, and passive Wi-Fi AP MAC address scanner targeting asset management applications. The built-in GNSS scanner allows fast and energy-efficient outdoor geolocation. The LoRa Edge GNSS Geolocation System achieves low energy geolocation by offloading time-intensive and compute-intensive operations to back-end system components.

The NAV3-based Tracker code version LBM SWL2001 V4.3 and above is capable to extract the assistance position data directly from the satellites and therefore can rely on a single backend component for its operation:

• GNSS Position Solving Component: LoRa Edge devices do not resolve the full position on the device. Instead, the measurements from GNSS signals are combined into a binary message (the NAV message) and are expected to be sent (via any communication channel) to the GNSS Position Solver backend component for final position calculation. This component is required in all operation modes.

Both the Legacy LoRa Edge NAV1/2-based tracker code and the network-aided NAV3-based tracker code rely on external delivery of the assistance information and therefore require these additional backend system components:

• GNSS Almanac Update Component (required in “GNSS-assisted” mode): LoRa Edge chips are able to reduce the GNSS scanning time by taking into account coarse orbital parameters for different GNSS constellations (the Almanac parameters). In conjunction with a coarse time and position estimate, LoRa Edge chips use this information to optimize the search for, and acquisition of, GNSS signals. Over time, the true satellite positions diverge from the fixed Almanac parameters, which requires them to be updated. This can be achieved by a backend component which estimates the quality of the Almanac image on the device and issues updates when needed. This component is required if GNSS-assisted mode is used.

• GNSS Assistance Component (required in assisted mode): In order to operate the GNSS Geolocation System in assisted mode, coarse estimates of time and position must be provided to the LoRa Edge chips. This information can be obtained in a variety of ways, including application-level knowledge. In LoRaWAN the Application Layer Clock Synchronization protocol can retrieve assistance time information. The assistance position information can generally be derived from past position solutions.

LoRa Cloud™ and LoRa Edge Chips

The LoRa Cloud™ Modem and Geolocation API offers all the services necessary to make most efficient use of the LoRa Edge geolocation functionality for modem-based devices:

• Wi-Fi Geolocation Solver: LoRa Edge Wi-Fi scan data transformed into an LoRa Edge Wi-Fi positioning protocol message and can be submitted as an Uplink Message with type wifi to the Modem Service API. A position lookup is done based on the MAC addresses encoded in the message.

• GNSS Geolocation Solver: LoRa Edge NAV messages of any encoding (NAV1, NAV2, and NAV3) can be submitted as an Uplink Message with type gnss to the Modem Service API. This triggers the computation of the position solution. To improve the positioning accuracy and success rate, multiple NAV messages can be grouped into multi-frame positioning requests by utilizing the LoRa Edge GNSS-NG (NAV-Group) positioning protocol.

For legacy LoRa Edge NAV1/2-based tracker code and the network-aided NAV3-based tracker code, which rely on external delivery of assistance information, LoRa Cloud™ Modem and Geolocation API provides seamless assistance management capabilities:

• Assistance Position: The GNSS Geolocation Solver generates assistance position downlink messages whenever an update to the on-device assistance position is necessary.

• Clock Synchronization: To achieve the required clock synchronization of a LoRa Edge based device, the Clock Synchronization over-the-air protocol that is built into the Modem Service can be used. This provides the required precision to operate the geolocation features.

• Seamless Almanac Update over-the-air: LoRa Edge GNSS status messages can be submitted as a Uplink Message message to the Modem Service API, with message type modem. If the Almanac image contains outdated entries, an update message will be generated to keep the Almanac image up-to-date. This approach is optimized for devices with low communication bandwidths.

• Almanac Image: In regular intervals, up to date Almanac images are served via the Full Almanac Image Modem Service API. These Almanac images are useful to bootstrap the LoRa Edge chip’s Almanac data when the required downlink bandwidth is available (e.g. during end-device production or manual on-boarding).

The Geolocation API Primitives augment the Modem and Geolocation Services with additional features which allow building highly optimized geolocation strategies for specific use cases. Also, these APIs are useful for custom LoRa Edge based geolocation approaches which do not rely on modem features.

• Multi-Frame GNSS Geolocation Solver for LoRa Edge: The combination of multiple LoRa Edge GNSS scans can often lead to an improved position estimation. For this purpose, multiple LoRa Edge NAV messages from a static position can be combined into a single LoRa Edge Multi-Frame GNSS Solver request.

Advanced Transport Services

The Modem Service provides two protocols to reliably receive application data from the reporting devices. The purpose of these protocols is to simplify the applications by taking care of the message encoding and integrity checking, so that the applications can simply send their data as over a socket. The protocols can handle variable packet sizes and packet loss by adding forward error correction codes to the data. Both protocols are supported by all Semtech modems that are compatible with the LoRaWAN protocol. The Modem Service transparently reassemble the redundant fragments and provide the original integrity-checked data to the application. The transported application data is processed transparently by the services, so it can be encrypted by the application before being transported to ensure data privacy.

Large File Upload

The purpose of the file upload protocol is to handle the upload of a file from the device to the Modem Service, creating an identical copy of the file in the Cloud. Applications can conveniently submit logical file data to the file upload protocol and have it transported reliably without having to deal with any message encoding and decoding.

To facilitate this, the file is split into blocks, which are redundantly encoded and sent as a continuous stream of fragments to the server. Each fragment is encoded as a combination of multiple blocks of the original file. Independent of the order in which the fragments are received, the service can extract information from each fragment and can successively reconstruct the original blocks.

When the service has received enough redundant fragments to fully reconstruct the file, it notifies the device, which then stops sending fragments. The number of fragments needed to reconstruct the original file depends on the file size, the packet sizes, and the packet loss.

Reliable Data Stream

The purpose of the data streaming protocol is to create a reliable pipe for variable-sized application data records from the device to the Modem Service. This protocol is named Reliable Octet Stream Encoding or ROSE.

Conceptually, the data streaming service behaves like a pipe: the device appends data and the server reads data. This service is designed to be resilient against message loss. It can tolerate the loss of multiple consecutive messages and yet can still reconstruct the original octet stream.

The device application can submit records of octets of variable length. Records can have a length ranging from 1–254 octets. These records are transported via ROSE to a server and are reassembled by the Modem Service. A server application then retrieves the records from Modem service and process them.

On the device, a record is handed from the application to the ROSE encoder and is transformed into a sequence of octets. This sequence consists of the original record data, along with some metadata, that makes it possible to detect the start and end of a record.

The encoded record sequence is appended to a FIFO. The FIFO holds the most recent record, as well as several of the previous records. It is used by the ROSE encoder to construct frames in keeping with the LoRaWAN protocol. Each frame contains LoRaWAN protocol metadata, ROSE protocol metadata, systematic, and redundancy data. The metadata allows the decoder to reconstruct the stream offset. The systematic data consists of plain text octets from the FIFO, and the redundancy data includes a combination of older octets that facilitate the reconstruction of lost data.

On the server side, the incoming ROSE frames are catalogued. Although some frames may not be received due to noise or interference, the original underlying octet stream can be reconstructed nevertheless—as long as enough frames with redundancy data arrive. The systematic data can be placed directly into the reconstructed octet stream and the collective redundancy data is used to reconstruct the missing information.

As soon as a record can be reconstructed, its content is returned to the server-side application, together with the stream offset. The stream offset can be used to order records or to detect gaps. As each record is accompanied by its stream offset, an application can infer that data between two positions (A and B) is missing. It is important to understand, however, that the ROSE decoder will fail to reconstruct all records if too many consecutive frames have been lost over the air.

Concepts

Device Owner

The concept of a Device Owner allows to logically split a population of devices into separate groups. Each API access token is associated with only one Device Owner. Hence, the API token defines the group of devices to which the API calls can be applied. The Geolocation APIs are not associated with any particular device and can thus be invoked by any token. The LoRa Cloud™ Service portal can be used to create and manage device owners.

Tokens

All API requests are authorized by a submitted token. The initial tokens for a device owner can be retrieved from the LoRa Cloud™ Service portal. A token management API allows for revoking or rotating access tokens.

Message Flow

Modem uplink messages are expected to be delivered by the client to the /uplink/send or /device/send API endpoints in the order in which they were sent by the device. A resulting downlink message may be generated in response and is expected to be scheduled for the LNS (LoRa® network server) by the client. The API response also includes device information and may also contain completed uploads, stream records or computed position locations.