Class LoraChannelPlan

Namespace

Pamoja.Lora

Assembly

Pamoja.Lora.dll

A regional channel plan, published or private.

public sealed class LoraChannelPlan : IDisposable

Inheritance

object

LoraChannelPlan

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

A channel plan is what a regulator and the LoRa Alliance publish about one band: which data rates exist, what each carries, how much of the time a node may hold a frequency, and where it listens for a downlink. The plan reports those facts and costs a transmission out against them; it never refuses one, because a deployment may hold licensed spectrum or be working under emergency provisions and only the operator knows which.

A plan assembled by LoraPlanBuilder is the same kind of thing as a published region, not a lesser one, and answers every question it does.

Properties

Name

The specification's name for the band, such as EU863-870.

public string Name { get; }

Property Value

string

Methods

ChannelBlocks(LoraChannelSet)

Returns the plan's channel blocks.

public IReadOnlyList<LoraChannelBlock> ChannelBlocks(LoraChannelSet which = LoraChannelSet.Default)

Parameters

which LoraChannelSet

The join set, the default set, or the numbered downlink channels.

Returns

IReadOnlyList<LoraChannelBlock>

The blocks, in the order the plan lists them.

ChannelFrequencyHz(ushort)

Returns the center frequency of one of the plan's default channels.

public uint? ChannelFrequencyHz(ushort channel)

Parameters

channel ushort

The channel number, counting across the default blocks.

Returns

uint?

The center frequency in hertz, or null past the last channel the plan starts a device with.

DataRate(byte, LoraDirection)

Returns the data rate a number selects.

public LoraDataRate? DataRate(byte dataRate, LoraDirection direction = LoraDirection.Uplink)

Parameters

dataRate byte

The data-rate number.

direction LoraDirection

Which table to read; the 900 MHz plans differ.

Returns

LoraDataRate?

The data rate, or null past the end of the plan's table. A number the region reserves is a rate of kind Reserved, which is different from one the plan never defines.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

DownlinkChannelFrequencyHz(ushort)

Returns the frequency of a numbered downlink channel.

public uint? DownlinkChannelFrequencyHz(ushort channel)

Parameters

channel ushort

The downlink channel number, counting across the downlink blocks.

Returns

uint?

The frequency in hertz, or null past the last downlink channel.

DutyCyclePermille(uint)

Returns the share of time a transmitter may hold a frequency.

public uint? DutyCyclePermille(uint frequencyHz)

Parameters

frequencyHz uint

The frequency in hertz.

Returns

uint?

The limit in parts per thousand, where 1000 means unrestricted, or null if the frequency falls in no sub-band this plan describes.

Remarks

This reports the limit; it does not impose it. Pair it with MinOffTimeMicros(int, uint) to turn the limit into the silence a frame costs.

ForCn470(LoraCn470Plan)

Returns one of the CN470-510 channel plans.

public static LoraChannelPlan ForCn470(LoraCn470Plan plan)

Parameters

plan LoraCn470Plan

The plan to describe.

Returns

LoraChannelPlan

The plan, which also carries the runs of join channels that select each of the others.

Exceptions

PamojaException

CN470-510 is not compiled into this build of the native library.

ForRegion(LoraRegion)

Returns the published plan for a region.

public static LoraChannelPlan ForRegion(LoraRegion region)

Parameters

region LoraRegion

The band to describe.

Returns

LoraChannelPlan

The plan, which answers every question about that band.

Exceptions

PamojaException

The region is not one this build of the native library carries.

Info()

Returns the scalar facts of the plan.

public LoraPlanInfo Info()

Returns

LoraPlanInfo

The plan's scalars.

IsAvailable(LoraRegion)

Reports whether a region is compiled into this build.

public static bool IsAvailable(LoraRegion region)

Parameters

region LoraRegion

The band to check.

Returns

bool

true if the region is available.

Remarks

A library trimmed for a device carries only the bands it operates in, so a host offering a choice asks this before offering one.

JoinPlanForChannel(ushort)

Returns the run of join channels a join channel belongs to.

public LoraJoinPlanPlace? JoinPlanForChannel(ushort joinChannel)

Parameters

joinChannel ushort

The join channel, counted through the runs in order.

Returns

LoraJoinPlanPlace?

Where the channel sits and where its accept and second receive window fall, or null if no run holds it.

JoinPlans()

Returns the runs of join channels that select a plan.

public IReadOnlyList<LoraJoinPlan> JoinPlans()

Returns

IReadOnlyList<LoraJoinPlan>

The runs, in join channel order; empty for every plan but the published CN470-510 ones.

Lease()

Holds the native plan open, for a package that builds on a plan.

public NativeLease Lease()

Returns

NativeLease

The lease, whose pointer stays valid until it is disposed.

Remarks

A plan is one of the few things another pamoja package needs to hand back to the native core, which is why this is here; nothing else should reach for it. The plan cannot be freed while a lease is held, even by a finalizer.

Exceptions

ObjectDisposedException

The plan was already disposed.

LinkSettings(byte)

Returns the radio settings an uplink data rate selects.

public LoraLink? LinkSettings(byte dataRate)

Parameters

dataRate byte

The uplink data-rate number.

Returns

LoraLink

The settings, ready to hand to AirtimeMicros(int), or null if the number is reserved or not carried by LoRa.

MaskControl(byte)

Returns what a ChMaskCntl value does.

public LoraMaskControl? MaskControl(byte value)

Parameters

value byte

The value, 0 to 7.

Returns

LoraMaskControl?

The control, or null past 7.

MaxEirpDbm(uint)

Returns the power ceiling that applies at a frequency, in dBm EIRP.

public sbyte MaxEirpDbm(uint frequencyHz)

Parameters

frequencyHz uint

The frequency in hertz.

Returns

sbyte

The ceiling, falling back to the plan's default where no sub-band says otherwise.

MaxPayload(byte, LoraPayloadTable)

Returns what a data rate may carry in one frame.

public LoraMaxPayload? MaxPayload(byte dataRate, LoraPayloadTable table = LoraPayloadTable.UplinkDirect)

Parameters

dataRate byte

The data-rate number.

table LoraPayloadTable

Which of the plan's payload tables to read.

Returns

LoraMaxPayload?

The limits, or null where the plan publishes none.

NextBackoffDataRate(byte)

Returns the next lower data rate for adaptive back-off.

public byte? NextBackoffDataRate(byte dataRate)

Parameters

dataRate byte

The data rate currently in use.

Returns

byte?

The next lower data rate, or null at the slowest the plan has.

Remarks

A device that has lost the network steps down this chain, trading airtime for range until it is heard again.

RelayChannels()

Returns the plan's default relay channels.

public IReadOnlyList<LoraRelayChannel> RelayChannels()

Returns

IReadOnlyList<LoraRelayChannel>

The channels by the index a relay configuration names: RP002-1.0.5 sections 3.4.9 to 3.13.9, and none where a region defines none.

Rules()

Returns how the plan defines and uses its channels.

public LoraPlanRules Rules()

Returns

LoraPlanRules

The plan's channel rules.

Rx1DataRate(byte, byte, bool)

Returns the downlink data rate the first receive window listens at.

public byte? Rx1DataRate(byte uplinkDataRate, byte offset, bool dwellLimited = false)

Parameters

uplinkDataRate byte

The data rate the uplink was sent at.

offset byte

The RX1 data-rate offset the network assigned.

dwellLimited bool

Whether to use the dwell-limited mapping.

Returns

byte?

The downlink data rate, or null if the uplink data rate or offset is outside what the plan defines.

Rx1FrequencyHz(ushort, uint)

Returns where the first receive window listens after an uplink on a channel.

public uint? Rx1FrequencyHz(ushort uplinkChannel, uint uplinkHz)

Parameters

uplinkChannel ushort

The channel number the uplink went out on.

uplinkHz uint

The frequency it went out on.

Returns

uint?

The uplink's own frequency on a plan with no numbered downlink channels, otherwise the downlink channel the uplink channel maps to, or null where the plan leaves the window undefined.

Rx2()

Returns where the second receive window listens.

public LoraRx2 Rx2()

Returns

LoraRx2

The frequency and data rate.

SubBands()

Returns the plan's sub-bands and the transmit limits inside each.

public IReadOnlyList<LoraSubBand> SubBands()

Returns

IReadOnlyList<LoraSubBand>

The sub-bands, in the order the plan lists them.

TxPowerDbm(byte, sbyte)

Returns the radiated power a transmit-power index selects, in dBm.

public sbyte? TxPowerDbm(byte index, sbyte maxEirpDbm)

Parameters

index byte

The transmit-power index, where zero is the ceiling.

maxEirpDbm sbyte

The ceiling the index steps down from.

Returns

sbyte?

The radiated power, or null past the highest index the plan defines.