Struct Synchronization

Source

pub struct Synchronization {
    pub reference_us: u64,
    pub cad_periodicity: CadPeriodicity,
    pub relay_xtal: XtalAccuracy,
    pub cad_to_rx: CadToRx,
}

Expand description

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.

Fields§

§reference_us: u64

When the relay scanned the channel the acknowledged frame went out on, TREF, in the device’s microseconds.

§cad_periodicity: CadPeriodicity

How often the relay scans.

§relay_xtal: XtalAccuracy

How accurate its crystal is.

§cad_to_rx: CadToRx

How long it takes to start receiving.

Implementations§

Source §

impl Synchronization

Source

pub fn from_ack( wor_start_us: u64, preamble_symbols: u16, symbol_us: u64, state: &StateSync, ) -> Synchronization

Works out when the relay scanned from the WOR ACK that answered a frame.

TREF = TLAST + PreambleLength * TSYMB - TOFFSET.

§Arguments

wor_start_us - when the acknowledged WOR frame started going out, TLAST.
preamble_symbols - its preamble length.
symbol_us - its symbol time.
state - what the acknowledgment said.

§Returns

The synchronization, referenced to the channel that frame used.

Source

pub fn next_wor( &self, now_us: u64, device_xtal_ppm: u32, symbol_us: u64, other_channel: bool, ) -> Option<WorSlot>

Picks the next scan to aim a WOR frame at, TS011-1.0.1 appendix 1.

TNEXT = N * CADPeriodicity + TREF with N = ceil((TNOW - TREF) / CADPeriodicity), DriftError = (RelayXtalAccuracy + EndDeviceXtalAccuracy) * (TNEXT - TREF) / 10^6, TSTART = TNEXT - DriftError / 2, moved one period on while that is already past, and PreambleLength = max(8, floor(DriftError / TSYMB) + 1 + 6 + CadToRx).

§Arguments

now_us - the time, TNOW.
device_xtal_ppm - the end device’s own crystal accuracy.
symbol_us - the symbol time of the WOR frame’s data rate.
other_channel - whether the frame goes out on the relay’s other channel, which it scans half a period apart.

§Returns

When to send and how long a preamble, or None once the drift exceeds a whole period, when the device is no longer synchronized and falls back to unsynchronized_preamble_symbols.

§Examples

use pamoja_lorawan::relay::{
    CadPeriodicity, CadToRx, Forward, StateSync, Synchronization, XtalAccuracy,
};

// TS011-1.0.1 appendix 1: a 133-symbol SF10 frame sent at 1 234 ms, and an
// acknowledgment reporting 892 ms from a 30 ppm relay scanning every 500 ms.
let state = StateSync {
    cad_to_rx: CadToRx::Symbols4,
    forward: Forward::Available,
    relay_data_rate: 3,
    xtal_accuracy: XtalAccuracy::Ppm30,
    cad_periodicity: CadPeriodicity::Ms500,
    t_offset_ms: 892,
};
let sync = Synchronization::from_ack(1_234_000, 133, 8_192, &state);
assert_eq!(sync.reference_us, 1_431_536);

// A minute later, from a 20 ppm device, the drift is 3 ms.
let slot = sync.next_wor(61_000_000, 20, 8_192, false).expect("still synchronized");
assert_eq!(slot.start_us, 61_430_036);
assert_eq!(slot.preamble_symbols, 11);

// Ten hours on, the drift passes a whole period.
assert_eq!(sync.next_wor(36_000_000_000, 20, 8_192, false), None);