Semtech, in its commitment to enhance user experience and streamline content, has successfully integrated the LoRa Developer Portal content into Semtech.com. As a result of this consolidation effort, the LoRa® Developer Portal will be discontinued on May 1st. After this date, you will be automatically redirected to Semtech.com.
For any technical support related to LoRa, please feel free to reach out to our experts here. If you have sales inquiries, please contact us here.
documentation
HOME » DOCUMENTATION » TECHNICAL DOCUMENTS » LoRaWAN® MAC Commands » MAC Commands

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.

Diagram illustrating MAC commands sent with a regular data downlink

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.

Diagram illustrating MAC Commands Sent in a Separate Data Frame

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.

Diagram showing the structure of the ``LinkCheckReq``, ``DutyCycleReq``, and ``LinkADRReq`` MAC Commands

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.

Diagram showing the structure of the ``LinkCheckAns``, ``DutyCycleAns``, and ``LinkADRAns`` MAC Commands

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 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.

« RETURN TO TECHNICAL DOCUMENTS