Module mac 

The commands a network and a device configure each other with.

A frame carries a payload for the application, and it can carry commands for the device itself: change to this data rate, listen on this frequency, tell me how your battery is. They ride either in the frame options, unencrypted and at most FOPTS_MAX bytes of them, or as a whole payload on port zero, which a session encrypts with the network key. A frame that carries them in both places is one a device is told to ignore.

Two things here are easy to get wrong, and both are quiet when you do:

• A command identifier means different things in each direction. 0x03 going down is a request to change rate, and the same byte coming up is the answer to one. Nothing in the bytes says which, so MacCommand::parse is told the direction and there is no default.
• A command does not carry its own length. A reader is expected to know it, which means an identifier it does not know cannot be stepped over: everything after it is unreadable. MacCommands stops there rather than guessing, and leaves the rest in remaining so a caller can see what was not read.

Every layout here is from the LoRaWAN 1.0.3 specification, section 5, and the relay commands from TS011-1.0.1 section 10. Multi-byte fields go out low byte first as the rest of the protocol does.

Structs

MacCommands

Walks the commands packed into one field.

Enums

MacCommand

One command, in either direction.

Constants

CID_CONFIGURE_FWD_LIMIT

Sets a relay’s forwarding limits, TS011-1.0.1 section 10.6.

CID_CTRL_UPLINK_LIST

Reads or removes an end device of a relay’s trusted list, TS011-1.0.1 section 10.5.

CID_DEVICE_TIME

Asks the network what time it is.

CID_DEV_STATUS

Asks a device for its battery and how well it is hearing.

CID_DL_CHANNEL

Moves the downlink frequency of a channel away from its uplink one.

CID_DUTY_CYCLE

Holds a device to a share of the air.

CID_END_DEVICE_CONF

Configures how an end device uses a relay, TS011-1.0.1 section 10.2.

CID_FILTER_LIST

Sets a rule of a relay’s join request filter, TS011-1.0.1 section 10.3.

CID_LINK_ADR

Sets the data rate, the power, and which channels may be used.

CID_LINK_CHECK

Checks the link, and asks how well it was heard.

CID_NEW_CHANNEL

Creates or changes a channel.

CID_NOTIFY_NEW_END_DEVICE

A relay telling the network of an end device it could not verify, TS011-1.0.1 section 10.7.

CID_RELAY_CONF

Configures a relay’s wake-on-radio channels, TS011-1.0.1 section 10.1.

CID_RX_PARAM_SETUP

Sets where and how fast the second receive window listens.

CID_RX_TIMING_SETUP

Sets how long after sending a device starts listening.

CID_TX_PARAM_SETUP

Sets the power and the dwell time a region asks for.

CID_UPDATE_UPLINK_LIST

Adds an end device to a relay’s trusted list, TS011-1.0.1 section 10.4.

EIRP_DBM

The transmit powers the dwell time command can name, in dBm, by their coded value.

FILTER_EUI_MAX

The longest join filter a relay rule carries: a JoinEUI and a DevEUI.

FOPTS_MAX

How many bytes of commands a frame can carry beside a payload.

MAX_COMMAND

The longest single command, which is the one that adds an end device to a relay’s trusted list.

RELAY_ACK_OFFSET_HZ

The frequency offsets a relay’s second channel can be acknowledged at, TS011-1.0.1 table 35, by their coded value.

RELAY_BUCKET_MULTIPLIER

What a coded bucket size multiplies a reload rate by, TS011-1.0.1 table 55.

Functions

eirp_code

The code for a transmit power, when the table has one for it exactly.

eirp_dbm

What a coded transmit power means in dBm.

encode_all

Writes a run of commands into one buffer.

receive_delay_s

How long a device waits before its first receive window, in seconds.

relay_rssi_code

The coded signal strength a relay reports, TS011-1.0.1 sections 9.1 and 10.7: -15 - code dBm, clamped to what seven bits carry.

relay_second_channel

The second channel a relay configuration describes, where it names one.

relay_snr_code

The coded signal-to-noise ratio a relay reports, TS011-1.0.1 sections 9.1 and 10.7: code - 20 dB, clamped to what five bits carry.