A Deep Dive into LoRaWAN® MAC Commands¶

This paper is goes into depth regarding the MAC Commands used for LoRaWAN® network administration. It is aimed at end device software developers and managers of teams building devices with LoRa® that implement the LoRaWAN Link Layer Specification v1.0.4. This paper helps you gain an understanding of different types of MAC commands, what each command is used for, and how to interpret the commands.

Already using software such as LoRaMAC-Node™ to handle MAC commands? This article gives you the background you need to understand how the software is working, review the code, and gain confidence that your end device is following the standards and best practices defined in the LoRaWAN Link Layer Specification.

Sending and Receiving MAC Commands¶

MAC commands are sent from the network server to the end device in downlinks, or from the end device to the network server in uplinks.

There are two methods which can be used to send MAC commands: either inside the Frame Options (FOpts) field at the same time as other data is sent inside the Frame Payload (FRMPayload), or as a separate packet using the entire Frame Payload.

When MAC commands are sent with other data in a packet (also referred to as piggybacking), the Frame Options Length (FOptsLen) field in the MAC payload are set to a value greater than zero (0). The MAC commands themselves are sent in the FOpts field in the Frame Header. The commands in the FOpts field are not encrypted in LoRaWAN 1.0.x.

MAC commands sent with a regular data downlink¶

When MAC commands are sent in a separate packet, the Frame Port (FPort) field in the MAC payload is set to 0. The FRMPayload field in the MAC payload contains the MAC commands. The FOpts field in the Frame Header are absent. The FOptsLen field in the Frame Control is also set to 0, and the FRMPayload field must be encrypted as described in the section 4.3.3 MAC frame payload encryption (FRMPayload) in the LoRaWAN Link Layer Specification 1.0.4.

MAC commands sent in a separate data frame¶

MAC commands can be sent individually or in a group of concurrent MAC commands. All MAC commands begin with a single octet containing a Command Identifier (CID). This CID indicates which MAC command type follows in the subsequent octets. The length of the subsequent octets depends on the type of MAC command, as identified in the preceding CID.

The diagram below shows the structure of three different MAC command requests, and illustrates how each command can have a different length. As mentioned, all MAC commands start with a CID octet. The LinkCheckReq MAC command contains only the CID octet and has no payload. DutyCycleReq contains two octets in total, the CID octet followed by a single octet containing data related to the request. LinkADRReq has a total of five octets, the CID octet followed by four octets containing the data.

Structure of the LinkCheckReq , DutyCycleReq , and LinkADRReq MAC Commands¶

The receiver of a request MAC command may be required to respond by sending the corresponding MAC command in return (an answer). These answers follow the same format as requests, with a single octet containing the CID followed by as many subsequent octets as are defined in the LoRaWAN Link Layer Specification v1.0.4 for the related MAC command answer.

Each of the example requests above has a matching answer. The diagram below shows the structure of the three answers to these requests. LinkCheckAns contains the CID octet followed by two octets that contain the data requested. DutyCycleAns contains only the CID octet and has no payload. LinkADRAns contains the CID octet followed by a single octet indicating status.

Structure of the LinkCheckAns , DutyCycleAns , and LinkADRAns MAC Commands¶

The structure for each of the MAC commands can be found in the sections of the LoRaWAN Link Layer Specification v1.0.4 listed below.

Overview of MAC Commands¶

There are 13 types of commands, each having a request command and an answer command.

The following MAC command types relate to all modes of operation (Class A, Class B, and Class C):

*MAC Command Groups Used by All Operation Modes*¶
Command Type	Command Pair	CID
Link Check Commands	`LinkCheckReq` , `LinkCheckAns`	`0x02`
End Device Time Commands	`DeviceTimeReq` , `DeviceTimeAns`	`0x0D`
End Device Status	`DevStatusReq` , `DevStatusAns`	`0x06`
Link Adaptive Data Rate (ADR) Commands	`LinkADRReq` , `LinkADRAns`	`0x03`
End Device Transmit Duty Cycle	`DutyCycleReq` , `DutyCycleAns`	`0x04`
Create / Modify a Channel	`NewChannelReq` , `NewChannelAns`	`0x07`
Modify Downlink Channel Frequency	`DlChannelReq` , `DlChannelAns`	`0x0A`
Receive Window Timing	`RXTimingSetupReq` , `RXTimingSetupAns`	`0x08`
Receive Windows Parameters	`RXParamSetupReq` , `RXParamSetupAns`	`0x05`
End Device Transmit Parameters	`TXParamSetupReq` , `TXParamSetupAns`	`0x09`

The following MAC command types are “Class B” commands and should only be implemented if the end device operates in Class B mode.

*MAC Command Groups Used by Class B Operation Mode Only*¶
Command type	Command pair	CID
Class B - Ping Slot Information	`PingSlotInfoReq` , `PingSlotInfoAns`	`0x10`
Class B - Ping Slot Channel Configuration	`PingSlotChannelReq` , `PingSlotChannelAns`	`0x11`
Class B - Beacon Frequency Configuration	`BeaconFreqReq` , `BeaconFreqAns`	`0x13`

MAC Commands Initiated by the End Device¶

For the three MAC command types listed below, the request is initiated by the end device. The answer is sent back from the network server to the end device. The end device should be aware of these requests and capable of initiating them. These requests should receive an answer in the first and second receive windows (RX1 and RX2) immediately following the request. If the answer is not received, the end device should employ a retry mechanism to repeat the original request.

Link Check Commands (LinkCheckReq , LinkCheckAns)

Used to check network connectivity. The network server responds to the request with an estimate of the received signal strength (RSSI) of the request and the number of gateways that received the request.

Learn more in the section 5.1 Link Check Commands of the LoRaWAN Link Layer Specification v1.0.4.

End Device Time Commands (DeviceTimeReq , DeviceTimeAns)

Used to request the current network time from the network server. The network server responds with the seconds and subsequent fractional seconds that have passed since the GPS epoch (January 6th, 1980, at 00:00:00 UTC). Syncing the device time with the network time can be used to accelerate beacon discovery when enabling Class B mode.

Learn more in the sections 5.9 End-Device Time Commands and 8.1: Introduction to Class B, Principle of Synchronous Network-initiated Class B Downlinks of the LoRaWAN Link Layer Specification v1.0.4.

Class B Ping Slot Information (PingSlotInfoReq , PingSlotInfoAns)

Used in Class B operations to allow the end device to inform the network server of its intent to change the periodicity of its ping slots. The network server responds with an empty payload.

Learn more in the sections 12.1 PingSlotInfoReq and 8.1: Introduction to Class B, Principle of Synchronous Network-initiated Class B Downlinks of the LoRaWAN Link Layer Specification v1.0.4.

MAC Commands Initiated by the Network Server¶

For the remaining ten MAC command types, the request is initiated by the network server. The answer is sent back from the end device to the network server. These commands can be further grouped as follows:

Commands that modify end device downlink parameters. These commands also modify the end device configuration for all operation modes.
Commands that modify other end device configuration for all operation modes.
Commands that modify other end device configuration for Class B operation mode.
The end device status command. This command is used to request information from the end device.

The following sections list the commands in each group. Some of the commands require knowledge of the settings for your region. To find the settings for your region, download the latest LoRaWAN Regional Parameters document from the LoRaWAN for Developers page on the LoRa Alliance® website. Some of the commands are only supported in certain regions.

Commands that Modify End Device Configuration (Downlink Parameters)¶

These commands modify downlink parameters. There are additional rules to follow to avoid loss of connectivity when handling these commands:

The network server must be made aware of whether these commands have been accepted by the end device as quickly as possible. Connectivity will be impacted if the network server is unaware of the status of these settings on the end device. For the commands listed below that modify the downlink parameters, the end device must send an answer with every single uplink until a Class A downlink is received back from the network server.

In addition to the commands listed in this section, the Class B Ping Slot Channel Configuration PingSlotChannelAns should also be sent with every single uplink until a Class A downlink is received back from the network server.

For other MAC commands, the end device must send back a single answer uplink.
When devices that use Activation by Personalization (ABP) are reset, this action must not reset the configurations set by these commands that modify downlink parameters.

Receive Windows Parameters (RXParamSetupReq , RXParamSetupAns)

The network server adjusts the data rate offset between the uplink and the first receive window (RX1) using the RXParamSetupReq command. The network server also adjusts the frequency and data rate for the second receive window following an uplink (RX2) using the same command. The end device verifies the validity of the settings. If the settings are valid, the end device applies the new settings. In either case, the network server responds with a RXParamSetupAns command, informing the network server whether or not it was able to apply the settings.

Learn more in section 5.4 Receive Windows Parameters of the LoRaWAN Link Layer Specification v1.0.4.

Receive Window Timing (RXTimingSetupReq , RXTimingSetupAns)

The network uses the RXTimingSetupReq command to configure the delay between the end of the uplink transmission and the opening of the first receive window. The request contains the length of the desired delay, between 1 and 15 seconds. The end device changes its settings to the new delay. The end device then sends the RXTimingSetupAns command with an empty payload to confirm receipt of the request.

Learn more in section 5.7 Setting Delay between TX and RX of the LoRaWAN Link Layer Specification v1.0.4.

Modify Downlink Channel Frequency (DlChannelReq , DlChannelAns)

This command pair is not supported in all regions.

The network server modifies the frequency used to send downlinks in the first reception slot (RX1) using the DlChannelReq command. The request contains the index of the channel to modify with the new frequency that the channel will use for downlinks. If the command is not supported in the region the end device operates in, the end device does not send an answer. The end device then modifies the channel if it is able, and responds with a DlChannelAns command indicating whether or not the channel was modified.

Learn more in section 5.6 Creation / Modification of a Channel of the LoRaWAN Link Layer Specification v1.0.4.

Note

This command is only accepted by end devices operating in a region with a dynamic channel plan. Check the channel plan type for your region in the latest LoRaWAN Regional Parameters document, in the section Regional Parameters Summary Table.

End Device Transmit Parameters (TXParamSetupReq , TXParamSetupAns)

This command pair is not supported in all regions.

The network server modifies the maximum continuous time of a packet over the air (dwell time) to a setting that is lower than the regional limitation using the TXParamSetupReq command. The maximum allowed Effective Isotropic Radiated Power (EIRP) is modified to a setting lower than the regional limitation using the same command. If the TXParamSetupReq command is not supported in the region where the end device operates, the end device does not send an answer. If the command is supported, the end device changes its settings to the requested settings if they are lower than the regional limit. The end device then responds with a TXParamSetupAns command with an empty payload to confirm receipt of the request.

Learn more in section 5.8 End-Device Transmit Parameters of the LoRaWAN Link Layer Specification v1.0.4.

Note

Find out if your region supports this command, the maximum dwell time for your region, and the maximum EIRP for your region in the latest LoRaWAN Regional Parameters document, in the section entitled YOUR_REGION Data Rate and End-device Output Power encoding.

Commands that Modify Other End Device Configuration for all Operation Modes¶

Link Adaptive Data Rate (ADR) Commands (LinkADRReq , LinkADRAns)

The network adjusts an end device’s data rate, transmission output power, channels used for uplink access, and the number of transmissions made per uplink frame using the LinkADRReq command. The end device validates the settings in the request. If valid, the end device applies the settings. The end device then sends the LinkADRAns command (containing details on which settings could be accepted) back to the network server.

Learn more about Adaptive Data Rate (ADR) in our Implementing Adaptive Data Rate paper, and in sections 5.1 Link ADR Commands, and 4.3.1.1 Adaptive data-rate control in frame header of the LoRaWAN Link Layer Specification v1.0.4.

End Device Transmit Duty Cycle (DutyCycleReq , DutyCycleAns)

The network server uses the DutyCycleReq command to set a maximum aggregated transmit duty cycle of an end device that is lower than the regional limitation. The end device changes its settings to the lower of the two values, either the regional limitation or the limit in the request. The end device then sends the DutyCycleAns command with an empty payload to confirm receipt of the request.

Learn more in section 5.3 End-Device Transmit Duty Cycle of the LoRaWAN Link Layer Specification v1.0.4.

Note

Find the duty cycle limit for your region in the latest LoRaWAN Regional Parameters document, in the section entitled YOUR_REGION Band Channel Frequencies, where YOUR_REGION represents the region your device operates in.

For example, if your device is destined for the EU863-870 region, and you are referencing document RP002-1.0.3, you would consult the section entitled EU863-870 Band Channel Frequencies, on page 25.

Create / Modify a Channel (NewChannelReq , NewChannelAns)

This command pair is not supported in all regions.

The network server creates or modifies the definition of a radio channel using the NewChannelReq command. The network server also uses the command to disable a radio channel. The request contains the index of the channel to create or modify, the frequency of the channel, and the range of uplink data rates allowed on the channel. If the command is not supported in the region, the end device does not send an answer. If the command is supported, the end device then validates whether or not the channel is allowed to be created or modified in the region. If allowed, the end device makes the changes requested and responds with a NewChannelAns indicating that the request was acted upon. If not allowed, the end device responds with a NewChannelAns indicating the reason the request could not be acted upon.

Learn more in section 5.6 Creation / Modification of a Channel of the LoRaWAN Link Layer Specification v1.0.4.

Note

This command is only accepted in regions with a dynamic channel plan. Check the channel plan type for your region in the latest LoRaWAN Regional Parameters document, in the section Regional Parameters Summary Table.

If the channel index in the request matches a default channel in the region where the end device operates, the end device must not modify the channel. Find the default channels for your region in the latest LoRaWAN Regional Parameters document, in the section entitled YOUR_REGION Band Channel Frequencies.

Commands that Modify Other End Device Configuration for Class B Operation Mode¶

The following MAC commands only need to be implemented by end devices supporting the Class B mode of operation.

Class B - Ping Slot Channel Configuration (PingSlotChannelReq , PingSlotChannelAns)

Using the PingSlotChannelReq command, the network server modifies the data rate and frequency of the channel on which the end device expects to receive Class B downlink pings. The end device determines whether the data rate and channel frequency are compatible with its radio. If both checks pass, the end device applies the new settings. In either case, the end device responds to the network server with a PingSlotChannelAns command indicating whether or not it was able to apply the settings. This answer should be sent with every uplink until a Class A downlink is received from the server.

Learn more in sections 12.3 PingSlotChannelReq, 8.1 Principle of Synchronous Network-initiated Class B Downlinks , and 14 Class B Unicast and Multicast Downlink Channel Frequencies of the LoRaWAN Link Layer Specification v1.0.4.

Class B - Beacon Frequency Configuration (BeaconFreqReq , BeaconFreqAns)

The network server modifies the frequency on which the end device expects to receive the Class B Beacon using the BeaconFreqReq command. The end device checks to see if the channel frequency is one it can use. If the channel frequency can be used, the end device modifies the settings. In either case, the end device responds with a BeaconFreqAns command indicating whether it was able to apply the settings.

Learn more in sections 12.3 BeaconFreqReq, and 13.2 Beacon Frame Format of the LoRaWAN Link Layer Specification v1.0.4.

End Device Status Command¶

The following is the only MAC command in this group that does not modify end device configuration. This command requests information from the end device.

End Device Status (DevStatusReq , DevStatusAns)

The network server uses the DevStatusReq command to request the battery level and radio status of the end device. The end device then sends a DevStatusAns command to inform the network server of its status. The response contains the Signal-to-Noise Ratio (SNR) of the last received DevStatusReq. The response also contains battery status data indicating either that the end device is connected to an external power source, the current battery level, or that the battery level cannot be retrieved.

Learn more in section 5.5 End-Device Status of the LoRaWAN Link Layer Specification v1.0.4.

Conclusion¶

In this paper we have explained how to send and receive MAC commands. You should now understand the different types of MAC commands that can be used. You have also learned that some MAC commands need to be sent from an end device to request information, and others need to be handled by the end device to update the configuration of the device or return information to the network server. You are aware of which commands are region-specific, and how to find out whether region-specific commands are supported in the region where your end device operates. Additionally, you should now be familiar with some best practices regarding how to handle commands that modify downlink parameters. Whether you are using an open source LoRaWAN software package or your own software to handle the LoRa® MAC layer, you can verify that your software is correctly handling MAC commands and sending the appropriate answers for your region.

Read the LoRaWAN Link Layer Specification 1.0.4 and download and read the LoRaWAN Regional Parameters document from the LoRa Alliance LoRaWAN for Developers page to learn about other aspects of the LoRa MAC layer and view the source material for this paper.

To view an example of how MAC commands are implemented within the LoRa MAC layer implementation for LoRaWAN Link Layer specification 1.0.4 in C, download the LoRaMac-Node end device stack implementation.