documentation
HOME » DOCUMENTATION » TECHNICAL DOCUMENTS » Implementing Adaptive Data Rate (ADR) » Implementing Adaptive Data Rate (ADR)

Implementing Adaptive Data Rate (ADR)

This paper is a deep dive into the Adaptive Data Rate (ADR) feature of LoRaWAN® for end device software developers and managers of teams building LoRa® devices that implement the LoRaWAN Link Layer Specification 1.0.4. You will gain an understanding of what ADR is, learn best practices on when to use ADR, and learn how to implement it on your end devices.

After reading this article you should have the underlying knowledge necessary for handling ADR, from declaring that your end device should implement ADR, to handling the MAC commands the network server sends the end-device, to regaining connectivity with the network server by following the ADR backoff scheme.

Already using software such as LoRaMAC-Node™ to handle ADR? This article will give 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.

ADR and Its Key Benefits

Adaptive Data Rate (ADR) describes the scheme whereby the network server individually controls the data rate, RF transmit power, channels used, and the number of retransmissions each end device in the network makes when sending uplinks.

The network server uses the Received Signal Strength Indicator (RSSI) of the messages received from an end device to determine how close the end device is to the nearest gateway(s). This allows the network server to select the most appropriate settings for each end device.

The benefits of ADR are that it helps preserve the battery life of an end device and that it reduces interference, giving all end devices on the network the best chance of communicating successfully.

Deciding When to Implement ADR

If your device is always static (i.e., in the same fixed location), then you should always use ADR.

If your end device is mobile, for example, if it is a geolocation tracker, ADR will not be suitable for your use case. When ADR is in use, the network server adjusts the data rate, TX Power, and channel plan using the received signal strength of uplinks to determine how near or far from the gateway the device appears to be. If the device then moves before the network server has calculated and transmitted the new settings, the settings will be unsuitable for the new location.

Mobile end devices are not necessarily in continuous motion, and they may need to send regular uplink messages during periods when they are static. During the periods when the device is static, it would benefit from using ADR. If possible, design your end devices so that your code can determine whehter a device is currently in motion or not. If your end device can determine its status, then you can use ADR when the device is static and stop using ADR when the device is in motion.

How to Implement ADR

The network server indicates whether it can support ADR at any given time by setting the ADR bit on downlinks. The ADR bit is passed in Frame Control (FCtrl) field of the Frame Header (FHDR), as shown in the following diagram.

ADR bit shown in Frame Control (FCtrl) field of the Frame Header (FHDR)

Position of the ADR bit in downlinks sent by the network server to the end device

The ADR bit will be set when the network server is supporting ADR, and it will be unset when the network server is not supporting ADR. Typically, the network server only temporarily suspends supporting ADR.

Regardless of whether the ADR bit is passed down by the network server, if the end device is static, the best practice is to try to implement ADR.

To implement ADR, the end device needs to do the following:

  1. Inform the network server that it is able and ready to use ADR by passing up the ADR Bit. Learn more in the Inform the Network Server That the End Device is Ready to Use ADR section of this document.

  2. Listen for Link ADR Request (LinkADRReq) MAC commands in downlinks. Implement the changes if possible, and respond to the network server. See Handling ADR MAC Commands for more information.

  3. As soon as a modification to the default settings has been made, implement ADR backoff (in case the new settings leave the end-device unable to communicate with the network server again). For more information, see ADR Backoff.

Even if the end device is not using ADR (for instance, if it is mobile), it should still listen for LinkADRReq MAC commands in downlinks and accept and implement channel mask control changes.

Inform the Network Server That the End Device is Ready to Use ADR

The end device indicates it is able and ready to use ADR by setting the ADR bit on uplinks. The ADR bit is passed in the Frame Control (FCtrl) field of the Frame Header (FHDR), as shown in the following diagram.

ADR bit shown in the Frame Control (FCtrl) field of the Frame Header (FHDR)

Position of the ADR bit in uplinks sent from the end device to the network server

Set the ADR bit to indicate that the end device is ready to use ADR. Only unset the ADR bit if the device is mobile and therefore not able to implement ADR.

Handling ADR MAC Commands

ADR MAC commands should be handled even if the end device is not passing ADR up in the uplinks. Even devices in motion that are not using ADR should still update their channel plan in response to a request from the network server in the ADR MAC command.

In this section, we describe ADR MAC commands and how to handle them according to the LoRaWAN 1.0.4 specification. You do not need to handle these commands yourself unless you are writing your own LoRaWAN stack on your end device. However, you can verify that the library you use implements ADR by inspecting the data packets and comparing them with the specification below.

ADR MAC commands are passed to the end device in downlinks, in the same way all MAC commands are passed. 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 downlink inside the Frame Payload.

When MAC commands are sent with other data in a downlink (also referred to as piggybacking), the Frame Options Length (FOptsLen) field in the MAC payload will be 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 will not be encrypted.

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 downlink, the Frame Port (FPort) field in the MAC payload is set to 0, and the FRMPayload field in the MAC payload contains the MAC commands. In addition, the FOpts field in the Frame Header will be absent, and the FOptsLen field in the Frame Control will be set to 0.

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) that indicates which MAC command type will follow in the subsequent octets. The length of the following octets depends on the MAC command type identified in the preceding CID. Link ADR Request MAC commands (LinkADRReq) are identified by the CID 0x03, and have four more octets, as illustrated in the following diagram, which shows the structure of the LinkADRReq command.

Diagram showing the structure of the LinkADRReq MAC Command

Structure of the LinkADRReq MAC command

As shown in the image above, these are the fields of interest in the LinkADRReq MAC command:

  • Data Rate (DataRate), inside the Requested Data Rate and TX Output Power (DataRate_TXPower) field in the LinkADRReq command. This indicates the new data rate the end device should use when sending uplinks. See Processing Data Rate Updates for more information.

  • TX Output Power (TXPower), inside the DataRate_TXPower field in the LinkADRReq command. This indicates the new TX Power the end device should use when sending uplinks. See Processing TX Output Power Updates for more information.

  • Channel Mask Control (ChMaskCntl) in the Redundancy field and the Channel Mask (ChMask) field in the LinkADRReq command. Together, these indicate the channels the end device should use when sending uplinks. See Processing Channel Mask Updates for more information.

  • Number of Transmissions Per Uplink Frame (NBTrans), inside the Redundancy field in the LinkADRReq command. This indicates the number of times each uplink should be retransmitted. See Processing NBTrans Updates for more information.

The end device responds to LinkADRReq commands by sending Link ADR Answer (LinkADRAns) MAC commands back to the network server. A LinkADRAns consists of two octets. The first contains the CID, which indicates the MAC command type. The second is a Status octet that indicates which requested changes were accepted.

Diagram showing the structure of the LinkADRAns MAC Command

Structure of the LinkADRAns MAC command

Processing the LinkADRReq MAC Command and Responding with LinkADRAns

The steps for processing a LinkADRReq MAC command depends on whether one or multiple LinkADRReq commands were sent in the downlink.

If there are multiple LinkADRReq commands in the downlink, the following actions are taken for each command in the block that is not the last command:

  1. Process the channel mask control and channel mask update, if supplied. Do this, even if the end device is not using ADR and not passing the ADR bit in the uplinks.

  2. If a channel mask update has been made in the LinkADRReq, respond with a LinkADRAns command, accepting or rejecting the channel mask update.

If there is a single LinkADRReq in the downlink, or if this is the last command in a block of multiple LinkADRReq commands, take the following actions:

  1. Check the data rate, TX output power, and NBTrans updates in the command and determine whether it is possible to apply each, following the guidance in the sections Processing TX Output Power Updates, Processing Data Rate Updates, and Processing NBTrans Updates below.

  2. Check the channel mask control and channel mask update and determine whether it is possible to apply the requested changes, following the guidance in Processing Channel Mask Updates.

  3. The next step depends on whether you are passing the ADR bit in uplinks:

    • If the end device is passing the ADR bit in uplinks:

      • If all the updates can be applied:

        Apply all updates and respond with a LinkADRAns command accepting the requested updates.

      • If any of the updates cannot be applied:

        Do not apply any updates and respond with a LinkADRAns command rejecting the requested updates.

    • If the end device is not passing the ADR bit in the uplinks:

      • If the channel mask control and channel mask update can be applied:

        Apply the updates and respond with a LinkADRAns command that accepts the channel mask control and channel mask updates by setting the ChannelMaskACK to 1 and rejects any other updates that were requested.

      • If the channel mask control and channel mask update cannot be applied:

        Do not apply the updates and respond with a LinkADRAns command rejecting all requested updates.

Processing TX Output Power Updates

The TX output power configuration (TXPower) is found in the Requested Data Rate and TX Output Power (DataRate_TXPower) field of the Link ADR Request MAC Command (LinkADRReq). When converted to decimal, this will be a number between 0 and 15.

You need to map the TX output power in the message to a real-world configuration. The mapping depends on your region and is specified in the latest LoRaWAN Regional Parameters document. Locate the section entitled Data Rate and End-device Output Power encoding for your region. Table 10 of the RP002-1.0.3 LoRaWAN Regional Parameters document shows the following TXPower codes for the EU863 configuration.

Table showing the mapping of TXPower codes to EU863 configuration. Source RP002-1.0.3 LoRaWAN Regional Parameters

Table showing the mapping of TXPower codes to EU863 configuration. [Source: RP002-1.0.3 LoRaWAN
Regional Parameters]

  • If the TX output power specified in the LinkADRReq is a power the end device can use:

  • If the TX output power specified in the LinkADRReq is a higher TX output power than the end device can use:

  • If the TX output power specified in the LinkADRReq command is a lower TX output power than the end device can use:

    • The end device should continue to operate at the previously-configured TX output power.

    • When sending the LinkADRAns command, the PowerACK bit should not be set. Because you cannot accept this update, you may be unable to accept other requests in the case where you must accept or reject all requests together. Read more about handling combinations of requests in Processing the LinkADRReq MAC Command and Responding with LinkADRAns.

  • If the TX output power is 15 (0xF):

    • Ignore this field; consider this to be the same as if no request has been made to alter the TX output power. The end-device should continue to operate at the previously-configured TX output power.

Processing Data Rate Updates

The Data Rate configuration (DataRate) is found in the Requested Data Rate and TX Output Power (DataRate_TXPower) field of the Link ADR Request MAC command (LinkADRReq) When converted to decimal, this will be a number between 0 and 15.

You need to map the data rate in the message to a specific configuration. The configuration depends on your region and is found in the latest LoRaWAN Regional Parameters document. For example, see Table 8 from the RP002-1.0.3 LoRaWAN Regional Parameters document below. Locate the section entitled Data Rate and End-device Output Power encoding) for the region where your end device will be deployed.

Table showing the mapping of Data Rate codes to EU863-870 configuration. Source: RP002-1.0.3 LoRaWAN Regional Parameters

Table showing the mapping of Data Rate Codes to the EU863-870 configuration. [Source: RP002-1.0.3 LoRaWAN Regional Parameters]

  • If the data rate specified in the message is a number between 0 and 14:

    • Check the LinkADRReq command for any channel mask control and channel mask updates, as described in Processing Channel Mask Updates, and make sure that the data rate requested is supported by the channels that will be enabled in this request.

    If the data rate requested can be supported:

    If the data rate requested cannot be supported:

    • The end device should continue to operate at the previously-configured data rate.

    • When sending the LinkADRAns command, the DataRateACK bit should not be set. Because you cannot accept this update, you may be unable to accept other requests in the case where you must accept or reject all requests together. Read more about handling combinations of requests in Processing the LinkADRReq MAC Command and Responding with LinkADRAns.

  • If Data Rate is 15 (0xF)

    • Ignore this field. Consider this to be the same as if no request has been made to alter the data rate. The end device should continue to operate at the previously-configured data rate.

Processing Channel Mask Updates

The Channel Mask Control (ChMaskCntl) is found in the Redundancy field of the Link ADR Request MAC command (LinkADRReq). The Channel Mask (ChMask) is found in the ChMask field of the LinkADRReq command. The Channel Mask Control defines how the Channel Mask should be interpreted. When converted to decimal, the Channel Mask Control will be a number between 0 and 7.

The meaning of the Channel Mask Control field depends on the region in which the end device operates, and is found in the latest LoRaWAN Regional Parameters document. Locate the section entitled LinkAdrReq command for the region where your end device is deployed.

For EU863-870, the document explains that:

  • a ChMaskCntl value of 0 instructs the end device to inspect the ChMask field to know which channels to turn on and off, between channels 0 and 15.

  • a ChMaskCntl value of 6 instructs the end device to turn on all channels, and to ignore the ChMask field.

For US902-928, the ChMaskCntl changes the groups of channels the ChMask should be applied to, as shown in Table 19 of the RP002-1.0.3 LoRaWAN Regional Parameters document:

Table showing the Mapping of ChMaskCntl to US902-928 configuration. Source: RP002-1.0.3 LoRaWAN Regional Parameters

Table showing the mapping of ChMaskCntl to the US902-928 configuration. [Source: RP002-1.0.3 LoRaWAN Regional Parameters]

The difference between EU863-870 and US902-928 illustrates the importance of checking the ChMaskCntl and of using the LoRaWAN Regional Parameters document to interpret the output.

The Channel Mask field is a bitmask that defines which of the channels identified by the Channel Mask Control should be used for sending uplinks. The usable channels are indicated by “1”. A bit set to 0 means the channel should not be used. Bit 0 is used to identify channel 1, and bit 15 is used to identify channel 16. If the bit mask is 1000 0000 0000 0001 then only Channel 1 and Channel 16 should be used.

  • If the Channel Mask Control and Channel Mask enable channels that are defined and can be enabled:

    If the channels requested to be enabled are compatible with the resulting data rate and TX output power:

    If the channels requested to be enabled are not compatible with the resulting data rate and TX output power:

    • The end device channels should remain unchanged.

    • When sending the LinkADRAns command, the ChannelMaskACK should not be set. If a data rate update was requested, the DataRateACK should not be set. If a TX output was requested, the PowerACK should not be set.

  • If the Channel Mask Control and Channel Mask results in all channels being disabled, or enables an undefined channel:

    • The end device channels should remain unchanged.

    • When sending the LinkADRAns command, the ChannelMaskACK should not be set. Because you cannot accept this update, you may be unable to accept other requests in the case where you must accept or reject all requests together. Read more about handling combinations of requests in Processing the LinkADRReq MAC Command and Responding with LinkADRAns.

Processing NBTrans Updates

The Number of Transmissions per Uplink Frame (NBTrans) field is found in the Redundancy field of the Link ADR Request MAC command (LinkADRReq). When converted to decimal, the NBTrans field will be a number between 0 and 15.

The NBTrans field tells the end device how many transmissions should be made for each uplink frame. This setting is used by the network server to increase and decrease the number of retransmissions, to control both network traffic and redundancy.

The mapping for the NBTrans field is as follows:

  • 0: use the default value of NBTrans, which is 1.

  • 1-15: use the value set, so for 1, send one transmission, for 2, send two transmissions, up to 15.

If a value greater than 1 is used, you should also follow these rules when sending uplinks:

  1. Use frequency hopping as usual.

  2. Wait until RX2 has expired before retransmission.

  3. When a downlink is received during RX1 or RX2, stop retransmission of that same uplink frame.

ADR Backoff

As soon as the end device is no longer using the default TX output power, data rate, channel plan, or NBTrans, implement ADR backoff.

Note

Even if the device is mobile and does not implement ADR, the channel plan can still be modified, so ADR backoff should still be used.

You do not need to implement ADR backoff yourself (unless you are writing your own LoRaWAN stack on your end-device). However, you can verify that the library you use implements ADR backoff correctly by inspecting the data packets and comparing them with the specification below.

There are three variables referenced throughout the process that you need to store and update on the end device.

  • ADR_ACK_LIMIT: This is the total number of unique uplinks that the end-device sends without receiving a response before the network should be forced to respond by setting ADRACKReq bit. This number is defined in the Regional Parameters document in the section Default Settings. In version RP002-1.0.3, ADR_ACK_LIMIT is set to 64.

  • ADR_ACK_DELAY: The total number of downlink frames not containing a response to the ADRACKReq bit that will be tolerated before trying to regain connectivity. The network server is required to respond within ADR_ACK_DELAY downlink frames after the ADRACKReq bit is set. The network server and end-device should therefore use the same setting. This number is defined in the Regional Parameters document in the section Default Settings. At version RP002-1.0.3, ADR_ACK_DELAY is set to 32.

  • ADRACKCnt: The counter to count the number of uplinks sent before receiving a downlink. This starts off being set to 0.

Note

LoRaWAN 1.1 allows the ADR_ACK_LIMIT and ADR_ACK_DELAY to be defined by the network server and passed to the end-device during the OTAA process. MAC commands exist to change the value of ADR_ACK_LIMIT and ADR_ACK_DELAY, using ADRParamSetupReq and ADRParamSetupAns, so these should default to 64 and 32, respectively, and then should update based on the ADRParamSetupReq if implementing LoRaWAN version 1.1.

ADR Backoff Flow

Whenever the app modifies the default settings in response to a LinkADRReq MAC command, set the ADRACKCnt to 0 and restart this flow.

When sending a new uplink frame, the LoRaWAN standard requires that you increment the uplink frame counter. Whenever you increment the uplink frame counter, increment ADRACKCnt by 1.

After sending an uplink, two receive (RX) windows open to allow you to process a server response. When the second RX window closes, the next step depends on whether the end device received a downlink response within either of the two RX windows.

If the end device did not receive a response in either of the two RX windows:

  • If the ADR acknowledgement request (ADRACKReq) bit is not currently being set on uplinks, i.e., if the end device is not specifically requesting a response from the server yet:

    • If ADRACKCnt >= ADR_ACK_LIMIT, i.e., if ADR_ACK_LIMIT (64) uplinks have been sent without receiving a response:

      • Set the ADRACKReq bit on all uplink transmissions. This informs the server that the end device would like the server to respond to uplinks.

      ADRACKReq bit shown in Frame Control (FCtrl) field of the frame header (FHDR)

      Position of the ADRACKReq bit in uplinks sent from the end device to the network server

  • If the ADRACKReq bit is currently being set on uplinks, i.e., if the end device is requesting a response from the server:

    1. If ADRACKCnt >= ADR_ACK_LIMIT + ADR_ACK_DELAY, i.e., after the ADR_ACK_LIMIT (64) uplinks without a response, the ADRACKReq bit was set requesting a response from the server, and there has since been ADR_ACK_DELAY (32) additional uplinks without a response from the server:

      • Set the TX power to the default setting for the operating region, described in the section Default TX Power.

    2. When a further ADR_ACK_DELAY (32) additional uplinks have been sent without a response from the server:

      • Change the data rate to the next lower data rate for your region. The next data rate to use is specified in the most recent LoRaWAN Regional Parameters document, in the section for your region, entitled Data Rate and End-device Output Power encoding. For example, if your device is destined for the EU863-870 region and you are referencing document RP002-1.0.3, you would consult section 2.4.3, EU863-870 Data Rate and End-device Output Power encoding, on page 26.

      If the end device is already operating on the lowest possible data rate, skip to step 4.

    3. Repeat step 2, stepping the data rate down each time a further ADR_ACK_DELAY (32) additional uplinks have been sent without a response from the server, until you reach the lowest possible data rate.

    4. When the next ADR_ACK_DELAY (32) additional uplinks have been sent without a response from the server:

      • Reset NbTrans to the default setting, described in Default Number of Retransmissions.

      • If the device’s region uses a dynamic channel plan; set the channel plan to the default setting for the operating region, as described in Default Channels. If the device’s region uses a fixed channel plan, enable all channels. Check the Regional Parameters Summary Table section in the latest Regional Parameters document to find out which type of region your device is operating in.

    • If at any point the above settings result in an invalid combination of TX power, data rate, or channel mask:

      • Set the TX power to the default setting for the operating region, as described in Default TX Power.

      • Reset NbTrans to the default setting, as described in Default Number of Retransmissions.

      • If the device’s region uses a dynamic channel plan; set the channel plan to the default setting for the operating region, as described in Default Channels. If the device’s region uses a fixed channel plan, enable all channels.

If the end device did receive a response within the two RX windows, or if at any point during the ADR backoff the end device receives a downlink:

  • Reset the ADRACKCnt to 0. This restarts the backoff flow.

  • Clear the ADRACKReq bit if it is currently being set.

The table below shows an example ADR backoff, for a device in the EU863 region.

ADR backoff example

ADRACKCnt

ADRACKReq

Data Rate

TX Power

NbTrans

Channels

0 to 63

0

DR2

Max -9 dBm

3

Using a channel mask

64

Changed to 1

DR2

Max -9 dBm

3

Using a channel mask

65 to 95

1

DR2

Max -9 dBm

3

Using a channel mask

96

1

DR2

Changed to default, e.g., Max -14 dBm

3

Using a channel mask

97 to 127

1

DR2

Max -14 dBm

3

Using a channel mask

128

1

Changed to DR1

Max -14 dBm

3

Using a channel mask

129 to 159

1

DR1

Max -14 dBm

3

Using a channel mask

160

1

Changed to DR0

Max -14 dBm

3

Using a channel mask

161 to 191

1

DR0

Max -14 dBm

3

Using a channel mask

192

1

DR0

Max -14 dBm

Changed to 1

Changed to default channels

193 onwards, until a connection is regained

1

DR0

Max -14 dBm

1

Default channels

Conclusion

In this paper you have learned what ADR is, the best practices for using ADR, and how to implement ADR on your end device. Whether you are using an open source LoRaWAN software package or your own software to handle the LoRa MAC layer and ADR, you can verify that your software is correctly passing the ADR bit to the network server, handling LinkADRReq MAC commands, and implementing ADR backoff.

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.

Download the LoRaMac-Node end device stack implementation to view an example of how ADR is implemented within the LoRa MAC layer implementation for LoRaWAN Link Layer specification 1.0.4 in C.