Module relay

Expand description

A LoRaWAN relay, TS011-1.0.1: what an end device and a relay say to each other.

A relay is an end device that listens on behalf of others. It sleeps, waking every CadPeriodicity to scan a channel for radio activity. An end device out of a gateway’s reach first sends a wake-on-radio (WOR) frame with a preamble long enough to span that sleep, which says where and how fast its LoRaWAN uplink will follow. The relay may answer with a WOR ACK describing its own timing, so the next WOR frame can be short, then listens for the uplink and forwards it to the network on port LA_FPORT_RELAY over its own session. A downlink for the end device comes back the same way and goes out in the device’s RXR window.

This module holds the frames and the arithmetic, sans IO like device:

WorKeys: the integrity and encryption keys an end device and a relay share, from the root key root_wor_s_key derives out of the network session key, section 4.
Wor: the two WOR frames, wor_join_request and wor_uplink, section 5.3.
wor_ack and open_wor_ack with StateSync: the acknowledgment, section 6.2.
ForwardedUplink: an uplink a relay forwards and its metadata, section 9.1.
Synchronization, unsynchronized_preamble_symbols and t_offset_ms: how long a WOR preamble must be and when it goes out, section 5.2 and appendix 1.
Relay: the relay itself, an end device that scans for those frames, answers them, forwards the uplinks behind them and sends the network’s answers on, chapters 3, 7 and 8. It keeps the tables its network configures, a JoinFilter, its TrustedDevices and its ForwardLimits, each usable on its own.

The relay commands a network configures both sides with are MacCommand variants, and each region’s default WOR channels are ChannelPlan::relay_channels.

§Examples

An end device wakes a relay, which checks the frame and acknowledges it:

use pamoja_lorawan::relay::{
    open_wor_ack, wor_ack, wor_uplink, CadPeriodicity, CadToRx, Carrier, Forward, StateSync,
    Wor, XtalAccuracy,
};
use pamoja_lorawan::Session;

let session = Session::new(0x2601_1BDA, [0x2B; 16], [0x99; 16]);
let keys = session.wor_keys();
let wor = Carrier::new(865_100_000, 3);
let ack = Carrier::new(865_300_000, 3);
let uplink = Carrier::new(868_100_000, 5);

// The end device says its next uplink goes out on 868.1 MHz at DR5.
let frame = wor_uplink(&keys, session.dev_addr(), 1, uplink, wor)?;

// The relay, holding the same keys, reads it back.
let Wor::Uplink(sealed) = Wor::parse(&frame)? else { unreachable!() };
assert_eq!(sealed.open(&keys, 1, wor)?, uplink);

// And tells the device how it scans.
let state = StateSync {
    cad_to_rx: CadToRx::Symbols4,
    forward: Forward::Available,
    relay_data_rate: 5,
    xtal_accuracy: XtalAccuracy::Ppm30,
    cad_periodicity: CadPeriodicity::Ms500,
    t_offset_ms: 892,
};
let answer = wor_ack(&keys, session.dev_addr(), 1, ack, uplink, state)?;
assert_eq!(open_wor_ack(&answer, &keys, session.dev_addr(), 1, ack, uplink)?, state);

Structs§

Acknowledgment: A WOR ACK to send.
Carrier: Where a frame goes and how fast: a frequency and a data rate.
FilterRule: One rule of a join request filter: the leading bytes of JoinEUI then DevEUI it matches, and what it does with a match.
ForwardLimits: A relay’s four relay-wide limits, TS011-1.0.1 tables 23 and 24.
ForwardedUplink: An end device’s uplink as a relay forwards it: the payload of a relay uplink on LA_FPORT_RELAY.
JoinFilter: A relay’s join request filter: a default action and up to fifteen rules, decided by the longest prefix that matches, TS011-1.0.1 section 8.6.
Listen: When and where to listen for the uplink a wake-on-radio frame announced.
Relay: A LoRaWAN relay: an end device that scans for wake-on-radio frames, acknowledges and forwards the uplinks behind them, and sends the network’s answers on in each end device’s RXR window.
RelayConfig: Which channels a relay scans and how often, as RelayConfReq sets them, TS011-1.0.1 section 10.1.
RelaySettings: What a relay’s radio can do, which every WOR ACK it sends reports.
RxrDownlink: A downlink for an end device, to send in its RXR window, TS011-1.0.1 chapter 7.
Scan: A scan for wake-on-radio frames, due next.
SealedWor: A wake-on-radio frame ahead of a Class A uplink, before its integrity code is checked.
StateSync: What a relay tells an end device about itself in a WOR ACK, TS011-1.0.1 table 14.
Synchronization: What an end device knows of a relay’s scans once a WOR ACK has arrived, TS011-1.0.1 section 3.9 and appendix 1.
TokenBucket: A token bucket: it earns a number of tokens an hour up to its size, and a relay spends one on each message it lets through.
TrustedDevice: An end device a relay trusts: its keys, the WOR frame counter it expects next, and how much of it the relay forwards.
TrustedDevices: The end devices a relay trusts, TRUSTED_ED_NUMBER of them, each at the index the network gave it.
UplinkMetadata: What a relay heard of an uplink, TS011-1.0.1 table 27.
WorKeys: The integrity and encryption keys of one end device’s wake-on-radio frames.
WorSlot: When a synchronized end device’s next WOR frame goes out, and with how long a preamble.

Enums§

CadPeriodicity: How often a relay scans a channel for a wake-on-radio preamble, TS011-1.0.1 table 18.
CadToRx: How many symbols a relay takes from detecting activity to receiving, TS011-1.0.1 table 15.
CounterReset: What ConfigureFwdLimitReq does to the token counters, TS011-1.0.1 table 63.
FilterAction: What a filter rule does with the join requests it matches, TS011-1.0.1 table 48.
Forward: Whether a relay will forward the uplink after a WOR frame, TS011-1.0.1 table 16.
RelayActivation: How an end device manages its relay mode, TS011-1.0.1 table 40.
RelayError: Why a relay did not do what a frame or a call asked.
RelayHeard: What a frame a relay’s own device heard turned out to be.
RelaySync: What an end device knows about when its relay listens, TS011-1.0.1 section 3.9.
Wake: What a wake-on-radio frame led a relay to do.
Wor: A wake-on-radio frame, as a relay reads it.
WorChannel: Which of a relay’s channels a WOR frame arrived on, TS011-1.0.1 table 28.
XtalAccuracy: How accurate a relay’s crystal is, TS011-1.0.1 table 17.

Constants§

FILTER_RULES: How many rules a relay’s join request filter holds, rule 0 being the default, TS011-1.0.1 section 8.6.
FORWARD_OVERHEAD: The bytes ForwardUplinkReq adds in front of the end device’s frame: three of metadata and three of frequency.
LA_FPORT_RELAY: The port every message between a relay and its network uses, TS011-1.0.1 section 9.
MIN_WOR_PREAMBLE_SYMBOLS: The shortest WOR preamble, in symbols, TS011-1.0.1 appendix 1.
RELAY_FWD_DELAY_US: The gap between a relay hearing an uplink and forwarding it, in microseconds.
RELOAD_PERIOD_US: How often every bucket earns its reload rate, in microseconds: an hour.
RXR_DELAY_US: How long after an uplink an end device’s RXR window opens at the latest, in microseconds.
TRUSTED_ED_NUMBER: How many end devices a relay verifies wake-on-radio frames for, RP002-1.0.5 section 5.4.5.
UNLIMITED_DEVICE_RATE: The reload rate a trusted end device’s bucket is coded with to mean no limit, TS011-1.0.1 table 54.
UNLIMITED_RELAY_RATE: The reload rate a relay-wide bucket is coded with to mean no limit, TS011-1.0.1 table 64.
WOR_ACK_DELAY_US: The gap between a WOR frame and its acknowledgment, in microseconds.
WOR_ACK_LEN: The length of a WOR ACK.
WOR_ATTEMPTS_WO_ACK: How many WOR frames an end device sends without an acknowledgment before its uplink goes out anyway, by default, RP002-1.0.5 section 5.4.5.
WOR_DATA_DELAY_US: The gap between a WOR frame, or its acknowledgment, and the LoRaWAN frame after it, in microseconds.
WOR_JOIN_REQUEST_LEN: The length of a WOR frame ahead of a join request: its header and five bytes.
WOR_UPLINK_LEN: The length of a WOR frame ahead of a Class A uplink.

Functions§

open_wor_ack: Checks and reads a WOR ACK, TS011-1.0.1 section 6.2.
root_wor_s_key: Derives the root relay session key of an end device, TS011-1.0.1 section 4.4.
smart_enable_uplinks: How many uplinks may go unanswered before a device in RelayActivation::Dynamic mode starts using a relay, TS011-1.0.1 table 41.
t_offset_ms: The milliseconds a relay reports from the start of its scan to the end of the WOR preamble, rounded up, TS011-1.0.1 appendix 1.
unsynchronized_preamble_symbols: The preamble length of an end device that does not know when the relay scans, TS011-1.0.1 section 5.2.
wor_ack: Builds a relay’s WOR ACK, TS011-1.0.1 section 6.2.
wor_join_request: Builds the wake-on-radio frame ahead of a join request, TS011-1.0.1 section 5.3.1.
wor_uplink: Builds the wake-on-radio frame ahead of a Class A uplink, TS011-1.0.1 section 5.3.2.

Module relay

Module relay Copy item path

§Examples

Structs§

Enums§

Constants§

Functions§

Module relay