Default TX Power¶

Use the maximum power level that the end device can support and that is permitted for the region in which it will operate. Find the guidelines for your region in the latest LoRaWAN Regional Parameters document, in the section 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.

Default Data Rate¶

The default data rate depends on the device’s activation method.

For devices that are activated using Activation By Personalization (ABP), the default data rate is the minimum data rate allowed for the end device in the region in which it will operate. The minimum data rate allowed is specified in the latest LoRaWAN Regional Parameters document, in the section for your region, entitled Data Rate and End-device Output Power encoding.

For devices that are activated using Over-The-Air Activation (OTAA), the default data rate is the data rate derived during the join procedure.

Default Number of Retransmissions¶

The default number of retransmissions (NBTrans) is one (1).

Default Channels¶

The default channels to use are specified in the latest LoRaWAN Regional Parameters document, in the section for your region, entitled Band Channel Frequencies.

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]¶

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

  • If the other criteria are met (as described in the section Processing the LinkADRReq MAC Command and Responding with LinkADRAns), then the end-device should be set to operate at the specified TX output power.

  • When sending the LinkADRAns command, if the other criteria are met (as described in Processing the LinkADRReq MAC Command and Responding with LinkADRAns), and the command will be accepted, the PowerACK bit should be set to 1 to confirm that you were able to accept the request.

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

  • If the other criteria are met (as described in the section Processing the LinkADRReq MAC Command and Responding with LinkADRAns), then the end device should be set to operate at its highest possible power.

  • When sending the LinkADRAns command, if the other criteria are met (as described in the section Processing the LinkADRReq MAC Command and Responding with LinkADRAns), and the command will be accepted, the PowerACK bit should be set to 1 to confirm that you were able to accept the request even though the actual power level will be lower than the requested power level.

• 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 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 other criteria are met, (as described in Processing the LinkADRReq MAC Command and Responding with LinkADRAns), then the end device should be set to operate at the specified data rate.

  • When sending the LinkADRAns, if the other criteria are met (as described in the section Processing the LinkADRReq MAC Command and Responding with LinkADRAns), and the command will be accepted, the DataRateACK bit should be set to 1 to confirm that the data rate was successfully set.

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

  • Check the LinkADRReq command for any data rate and TX output power updates, as described in the sections Processing Data Rate Updates and Processing TX Output Power Updates, and make sure that the channels requested are compatible with the resulting data rate and TX output power.

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

  • If the other criteria are met (as described in Processing the LinkADRReq MAC Command and Responding with LinkADRAns), the end-device channels should be enabled.

  • When sending the LinkADRAns, if the other criteria are met (as described in Processing the LinkADRReq MAC Command and Responding with LinkADRAns), and the command will be accepted, the ChannelMaskACK bit should be set to 1 to confirm that you were able to accept the request.

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

    

    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.