Class LorawanRelay

Namespace

Pamoja.Lorawan

Assembly

Pamoja.Lorawan.dll

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

public static class LorawanRelay

Inheritance

object

LorawanRelay

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

A relay sleeps, waking every scan period to look for radio activity. An end device out of a gateway's reach first sends a wake-on-radio (WOR) frame whose preamble spans that sleep and which says where its uplink follows. The relay may acknowledge with its own timing, so the next preamble can be short, then forwards the uplink on port FPort.

Fields

FPort

The port every message between a relay and its network uses.

public const byte FPort = 226

Field Value

byte

ForwardOverhead

The bytes a forwarded uplink adds in front of the end device's frame.

public const int ForwardOverhead = 6

Field Value

int

MinWorPreambleSymbols

The shortest WOR preamble, in symbols.

public const ushort MinWorPreambleSymbols = 8

Field Value

ushort

RelayForwardDelayMicros

The gap between a relay hearing an uplink and forwarding it.

public const uint RelayForwardDelayMicros = 50000

Field Value

uint

RxrDelayMicros

How long after an uplink an end device's RXR window opens at the latest.

public const uint RxrDelayMicros = 18000000

Field Value

uint

TrustedEndDevices

How many end devices a relay verifies wake-on-radio frames for.

public const int TrustedEndDevices = 16

Field Value

int

WorAckDelayMicros

The gap between a WOR frame and its acknowledgment.

public const uint WorAckDelayMicros = 50000

Field Value

uint

WorAttemptsWithoutAck

How many WOR frames go without an acknowledgment before the uplink goes anyway.

public const byte WorAttemptsWithoutAck = 8

Field Value

byte

WorDataDelayMicros

The gap between a WOR frame, or its acknowledgment, and the LoRaWAN frame after it.

public const uint WorDataDelayMicros = 50000

Field Value

uint

Methods

EncodeForward(LorawanForwardedUplink)

Writes an uplink a relay forwards on port 226, section 9.1.

public static byte[] EncodeForward(LorawanForwardedUplink forwarded)

Parameters

forwarded LorawanForwardedUplink

The metadata, the frequency, and the end device's frame.

Returns

byte[]

The relay uplink's payload.

Remarks

A strength or ratio past what its field carries goes out as the closest value.

Exceptions

PamojaException

A data rate or frequency the fields cannot carry.

NextWor(LorawanSynchronization, ulong, uint, ulong, bool)

Picks the relay scan a synchronized end device aims its next WOR frame at, appendix 1.

public static LorawanWorSlot? NextWor(LorawanSynchronization synchronization, ulong nowMicros, uint deviceXtalPpm, ulong symbolMicros, bool otherChannel = false)

Parameters

synchronization LorawanSynchronization

What the device knows of the relay.

nowMicros ulong

The time.

deviceXtalPpm uint

The device's crystal accuracy.

symbolMicros ulong

The symbol time of the WOR frame's data rate.

otherChannel bool

Whether the frame goes out on the relay's other channel.

Returns

LorawanWorSlot?

When to send and how long a preamble, or null once the drift exceeds a period.

OpenWor(ReadOnlySpan<byte>, LorawanWorKeys, uint, LorawanCarrier)

Checks a WOR frame ahead of a Class A uplink and reads where the uplink follows.

public static LorawanCarrier OpenWor(ReadOnlySpan<byte> frame, LorawanWorKeys keys, uint wfcnt, LorawanCarrier wor)

Parameters

frame ReadOnlySpan<byte>

The frame a relay received.

keys LorawanWorKeys

The keys of the device it names.

wfcnt uint

The full 32-bit counter the relay takes it to carry.

wor LorawanCarrier

The carrier it arrived on.

Returns

LorawanCarrier

Where and how fast the uplink follows.

Exceptions

PamojaException

The frame is not an uplink WOR, or its integrity code does not verify.

OpenWorAck(ReadOnlySpan<byte>, LorawanWorKeys, uint, uint, LorawanCarrier, LorawanCarrier)

Checks and reads a WOR ACK, section 6.2.

public static LorawanStateSync OpenWorAck(ReadOnlySpan<byte> frame, LorawanWorKeys keys, uint devAddr, uint wfcnt, LorawanCarrier ack, LorawanCarrier uplink)

Parameters

frame ReadOnlySpan<byte>

The acknowledgment an end device received.

keys LorawanWorKeys

The device's WOR keys.

devAddr uint

Its address.

wfcnt uint

The counter of the WOR frame it sent.

ack LorawanCarrier

The carrier the acknowledgment arrived on.

uplink LorawanCarrier

The carrier the WOR frame named.

Returns

LorawanStateSync

What the relay said about itself.

Exceptions

PamojaException

The integrity code does not verify, or the periodicity is reserved.

ParseForward(ReadOnlySpan<byte>)

Reads an uplink a relay forwarded, section 9.1.

public static LorawanForwardedUplink ParseForward(ReadOnlySpan<byte> payload)

Parameters

payload ReadOnlySpan<byte>

The relay uplink's payload on port 226.

Returns

LorawanForwardedUplink

The metadata, the frequency, and the end device's frame.

Exceptions

PamojaException

A payload too short or a reserved WOR channel.

ParseWor(ReadOnlySpan<byte>)

Reads a WOR frame, leaving an uplink's carrier sealed.

public static LorawanWor ParseWor(ReadOnlySpan<byte> frame)

Parameters

frame ReadOnlySpan<byte>

The bytes a relay received.

Returns

LorawanWor

The frame.

Exceptions

PamojaException

A reserved or proprietary type, or a length that is not the type's.

RootWorSKey(ReadOnlySpan<byte>)

Derives an end device's root relay session key from its network session key, section 4.4.

public static byte[] RootWorSKey(ReadOnlySpan<byte> networkKey)

Parameters

networkKey ReadOnlySpan<byte>

The 16-byte network session key.

Returns

byte[]

The 16-byte root key.

Exceptions

PamojaException

The key is not 16 bytes.

SecondChannel(byte, byte, byte, uint)

Reads the second channel a relay or end device configuration describes.

public static LoraRelayChannel? SecondChannel(byte secondChannelIndex, byte dataRate, byte ackOffset, uint frequencyHz)

Parameters

secondChannelIndex byte

The coded index, 1 for a second channel.

dataRate byte

Its data rate.

ackOffset byte

The coded acknowledgment offset, table 35.

frequencyHz uint

Its frequency.

Returns

LoraRelayChannel?

The channel with its acknowledgment frequency, or null when none is named.

Synchronization(ulong, ushort, ulong, LorawanStateSync)

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

public static LorawanSynchronization Synchronization(ulong worStartMicros, ushort preambleSymbols, ulong symbolMicros, LorawanStateSync state)

Parameters

worStartMicros ulong

When the acknowledged WOR frame started going out.

preambleSymbols ushort

Its preamble length.

symbolMicros ulong

Its symbol time.

state LorawanStateSync

What the acknowledgment said.

Returns

LorawanSynchronization

The synchronization.

TOffsetMs(ulong, ulong)

The offset a relay reports in a WOR ACK, appendix 1.

public static ushort? TOffsetMs(ulong scanStartMicros, ulong preambleEndMicros)

Parameters

scanStartMicros ulong

When the scan that detected the frame started.

preambleEndMicros ulong

When the frame's preamble ended: when it finished arriving, less the airtime of its sync word and payload.

Returns

ushort?

The offset in milliseconds, or null when the preamble ended before the scan or more than eleven bits of milliseconds after it.

UnsynchronizedPreamble(LorawanCadPeriodicity, ulong, LorawanCadToRx)

The WOR preamble of an end device that does not know when the relay scans, section 5.2.

public static ushort UnsynchronizedPreamble(LorawanCadPeriodicity cadPeriodicity, ulong symbolMicros, LorawanCadToRx cadToRx)

Parameters

cadPeriodicity LorawanCadPeriodicity

How often the relay scans.

symbolMicros ulong

The symbol time of the WOR frame's data rate, in microseconds.

cadToRx LorawanCadToRx

The relay's time to start receiving.

Returns

ushort

The preamble length in symbols.

WorAck(LorawanWorKeys, uint, uint, LorawanCarrier, LorawanCarrier, LorawanStateSync)

Builds a relay's WOR ACK, section 6.2.

public static byte[] WorAck(LorawanWorKeys keys, uint devAddr, uint wfcnt, LorawanCarrier ack, LorawanCarrier uplink, LorawanStateSync state)

Parameters

keys LorawanWorKeys

The end device's WOR keys.

devAddr uint

Its address.

wfcnt uint

The counter of the acknowledged WOR frame.

ack LorawanCarrier

The carrier the acknowledgment goes out on.

uplink LorawanCarrier

The carrier the WOR frame named for the uplink.

state LorawanStateSync

What the relay tells the device.

Returns

byte[]

The seven-byte acknowledgment.

Exceptions

PamojaException

A state or carrier the fields cannot carry.

WorJoinRequest(LorawanCarrier)

Builds the WOR frame ahead of a join request, section 5.3.1.

public static byte[] WorJoinRequest(LorawanCarrier uplink)

Parameters

uplink LorawanCarrier

Where and how fast the join request follows.

Returns

byte[]

The five-byte frame.

Exceptions

PamojaException

A data rate past 15 or a frequency the field cannot carry.

WorKeys(ReadOnlySpan<byte>, uint)

Derives an end device's WOR keys from its root relay session key, section 4.5.

public static LorawanWorKeys WorKeys(ReadOnlySpan<byte> rootKey, uint devAddr)

Parameters

rootKey ReadOnlySpan<byte>

The 16-byte root key.

devAddr uint

The device's address.

Returns

LorawanWorKeys

The integrity and encryption keys.

Exceptions

PamojaException

The key is not 16 bytes.

WorUplink(LorawanWorKeys, uint, uint, LorawanCarrier, LorawanCarrier)

Builds the WOR frame ahead of a Class A uplink, section 5.3.2.

public static byte[] WorUplink(LorawanWorKeys keys, uint devAddr, uint wfcnt, LorawanCarrier uplink, LorawanCarrier wor)

Parameters

keys LorawanWorKeys

The device's WOR keys.

devAddr uint

Its address.

wfcnt uint

The WOR frame counter, raised for every WOR frame.

uplink LorawanCarrier

Where and how fast the uplink follows.

wor LorawanCarrier

The carrier this WOR frame goes out on.

Returns

byte[]

The fifteen-byte frame.

Exceptions

PamojaException

A carrier the fields cannot carry.