Class GatewayStation

Namespace

Pamoja.Gateway

Assembly

Pamoja.Gateway.dll

The LoRa Basics Station protocol, from either side.

public static class GatewayStation

Inheritance

object

GatewayStation

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

A station and its network server exchange JSON messages over a websocket the caller owns, so nothing here opens a socket: split a frame the radio heard with Heard(ReadOnlySpan<byte>, byte, uint, GatewayStationLevels?), build any other message as a GatewayStationMessage, send what Encode(GatewayStationMessage) writes, and read whatever arrives with Parse(string).

Fields

DiscoveryPath

The path a station appends to its configured address to find its server.

public const string DiscoveryPath = "/router-info"

Field Value

string

ProtocolVersion

The protocol version a station reports.

public const uint ProtocolVersion = 2

Field Value

uint

Methods

Discovery(ReadOnlySpan<byte>)

Writes the request a station sends to find its network server.

public static string Discovery(ReadOnlySpan<byte> router)

Parameters

router ReadOnlySpan<byte>

The station asking, eight bytes.

Returns

string

The text to send on DiscoveryPath.

Exceptions

ArgumentException

router is not eight bytes.

DiscoveryParse(string)

Reads the request a station sent to find its network server, as the server does.

public static byte[] DiscoveryParse(string text)

Parameters

text string

The request text.

Returns

byte[]

The station asking, eight bytes.

Exceptions

PamojaException

The text is not this request.

Encode(GatewayStationMessage)

Writes a message as the websocket carries it.

public static string Encode(GatewayStationMessage message)

Parameters

message GatewayStationMessage

The message, of any kind.

Returns

string

The text to send.

Exceptions

ArgumentOutOfRangeException

The kind is not one of GatewayStationKind's values.

ArgumentException

An identifier the kind needs is missing or is not eight bytes: JoinEui and DevEui for a join request, DevEui for a downlink or a report. Or the message is of Other and names no Msgtype.

EuiOf(string)

Reads an identifier written in any form the protocol accepts.

public static byte[] EuiOf(string text)

Parameters

text string

The identifier, in ID6, EUI, or plain hexadecimal form.

Returns

byte[]

Its eight bytes.

Exceptions

PamojaException

The text is not an identifier.

Heard(ReadOnlySpan<byte>, byte, uint, GatewayStationLevels?)

Reads a frame the radio heard into the message that reports it.

public static GatewayStationMessage Heard(ReadOnlySpan<byte> frame, byte dataRate, uint frequencyHz, GatewayStationLevels? levels = null)

Parameters

frame ReadOnlySpan<byte>

The bytes as they arrived, header through integrity code.

dataRate byte

The data rate it arrived at.

frequencyHz uint

The frequency it arrived on, in hertz.

levels GatewayStationLevels

How it was heard.

Returns

GatewayStationMessage

The message to send up.

Exceptions

PamojaException

The frame is shorter than the fields its header names, or carries a kind a station does not send up.

Id6(ReadOnlySpan<byte>)

Writes an identifier in the ID6 form the protocol prefers.

public static string Id6(ReadOnlySpan<byte> eui)

Parameters

eui ReadOnlySpan<byte>

The identifier, eight bytes.

Returns

string

The identifier, such as 1:203:405:607.

Exceptions

ArgumentException

eui is not eight bytes.

Parse(string)

Reads a message that arrived over the websocket.

public static GatewayStationMessage Parse(string text)

Parameters

text string

The message text.

Returns

GatewayStationMessage

The message.

Exceptions

PamojaException

It is not a message this protocol defines.

RouterAccepted(ReadOnlySpan<byte>, ReadOnlySpan<byte>, string)

Writes the answer that sends a station to the websocket its session runs on.

public static string RouterAccepted(ReadOnlySpan<byte> router, ReadOnlySpan<byte> muxs, string uri)

Parameters

router ReadOnlySpan<byte>

The station being answered, eight bytes.

muxs ReadOnlySpan<byte>

The server endpoint that carries the session, eight bytes.

uri string

The websocket address.

Returns

string

The answer to send back on DiscoveryPath.

Exceptions

ArgumentException

router or muxs is not eight bytes.

RouterParse(string)

Reads the answer a discovery endpoint gives.

public static GatewayStationRouter RouterParse(string text)

Parameters

text string

The answer text.

Returns

GatewayStationRouter

Where to connect, or why the station was refused, and whom the answer names.

Exceptions

PamojaException

The answer is not this protocol.

RouterRefused(ReadOnlySpan<byte>, string)

Writes the answer that refuses a station, saying why.

public static string RouterRefused(ReadOnlySpan<byte> router, string error)

Parameters

router ReadOnlySpan<byte>

The station being refused, eight bytes.

error string

What is wrong, in words the operator can act on.

Returns

string

The answer to send back on DiscoveryPath.

Exceptions

ArgumentException

router is not eight bytes.

Xtime(byte, byte, long)

Builds a station clock value from the radio it was read on, the run of the station, and the microseconds that run had counted.

public static long Xtime(byte unit, byte session, long micros)

Parameters

unit byte

The radio unit, 0 to 127.

session byte

The run of the station, which the reference station never leaves at 0.

micros long

The microseconds the run had counted, below 2^48.

Returns

long

The value a message carries as its xtime.

Exceptions

ArgumentOutOfRangeException

unit is past 127, or micros is negative or does not fit 48 bits.

XtimeParts(long)

Takes a station clock value apart into its radio unit, run, and microseconds.

public static GatewayStationXtime XtimeParts(long xtime)

Parameters

xtime long

The value a message carried.

Returns

GatewayStationXtime

Its parts.