This guide contains implementation details primarily for gateway manufacturers intending to implement the LoRa Basics™ Station protocol.
Note:The standard implementation of the LoRa Basics™ Station protocol found at the Github page is already compatible with the behaviour mentioned in this guide. Custom implementations must be aware of the following items and must ensure that these are accounted for.
The Gateway Server component of The Things Stack contains a native downlink scheduler, that optimizes downlink capacity of gateways. Implementations of the LoRa Basics™ Station also contain a scheduler. The Things Stack prefers its own scheduler over the LoRa Basics™ Station scheduler for the following reasons:
- Only the The Things Stack has knowledge of all the possible downlink paths to a device via multiple gateways. An individual gateway has no knowledge of other gateways. If downlinks fail on a particular gateway, then the server will retry via a different gateway.
- Only the The Things Stack can effectively enforce duty cycling and make sure that gateways operate within regional limits. This prevents operators from manipulating gateways to circumvent regulations.
The Things Stack enforces the use of its scheduler over the LoRa Basics™ Station scheduler by manipulating the downlink parameters.
LoRa Basics™ Station uses the
xtime value to calculate the time a downlink is put on air. According to the LoRa Basics™ Station specification, the
xtime value has to be echoed unchanged by the server to the gateway. However, The Things Stack deviates from this expectation by manipulating the
xtime to force the gateway to schedule downlinks based on the server’s scheduler instead of the gateway scheduler.
xtime parameter is encoded as follows. The Things Stack only manipulates bits
47-0, based on an internal clock that is maintained for each gateway. The rest of the upper bits are returned as-is.
|63||Sign (always positive)|
|62-56||Radio unit where the time stamp originated from (max 128)|
|55-48||Session ID; Random value to disambiguate different SX1301 sessions (should never be 0).|
|47-0||Microseconds since SX1301 start (rollover every 9y » uptime of sessions).|
Custom implementations of LoRa Basics™ Station working with The Things Stack must ensure that the
Session ID bits (55-48) are never zero and take into account the fact that the bits 47-0 are modified.
LoRa Basics™ Station allows the server to provide both the RX1 and RX2 parameters of the downlink message,
dnmsg. This is so that the gateway can retry downlinks in RX2, if it failed in RX1. The Things Stack however only sets the RX1 values (
RX1Freq), thereby forcing the gateway to schedule only once. Errors in scheduling and subsequent retries are handled in The Things Stack and not on the gateway. If The Things Stack wants to force the gateway to schedule in the RX2 window, it sends the RX2 parameters in the same RX1 fields of the
dnmsg but offsets the downlink time (
xtime) to make the gateway schedule in the correct window.
Custom implementations of LoRa Basics™ Station working with The Things Stack only need to schedule downlink messages that are sent by the The Things Stack and let the latter handle retries and conflicts.
Use of DevEui field in Downlink Messages
Gateways using the LoRa Basics™ Station protocol report the successful transmission of downlink messages via the Transmit Confirmation (
dntxed) message. In order to correlate the confirmation message to a downlink, the LoRa Basics™ Station protocol provides two options to the LNS. The LNS is offered the flexibility to implement either of these mechanisms.
a. Using the
DevEui and the
- In this mode, the LNS uses a per-device downlink counter. Gateways echo the
diidfields sent on the downlink message on the corresponding Transmit Confirmation message.
- The LNS then forwards the transmit confirmation upstream.
- This is useful for debugging using LoRa Basics™ Station gateway logs since the
DevEuiwill be printed. However, this exposes the DevEui of end devices to gateways which is not desirable in cases where the gateway is not owned/operated by the device owner.
- The Things Stack does not use this method to correlate Transmit Confirmations.
b. Using only the
- The LNS can choose to make the
diidfield globally unique per gateway (per session). The LNS can then maintain a correlation of the
diidvalues to downlink messages.
- When the gateway sends a Transmit Confirmation message, the LNS can then use the echoed
diidvalue to look up the downlink message and retrieve information on the end device and forward the transmit confirmation upstream.
- In this mode, the
DevEuifield of the downlink message is not used by the LNS but should be set to a non-zero value.
- This is the approach used by The Things Stack, where the
DevEuiis set to
0000000000000001for all downlink messages.