documentation
In-Depth: LoRaWAN® 1.0.4 Class B and C for End Devices¶
This paper explores in depth how to use Class B and Class C in end devices implementing LoRaWAN® 1.0.4. Class B mode enables the end device to receive downlinks at regular intervals; Class C mode enables the device to receive downlinks at any time. This paper 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. We teach you how to configure your end device to receive Class B downlinks using beacons and ping slots, best practices to follow to increase the chance of receiving downlinks while maintaining reasonable battery life, and how to receive Class C downlinks.
Ideally you will be using software to handle the network layer of LoRaWAN such as LoRaMAC-Node™ or LoRa Basics™ Modem. This article gives you the background you need to fully understand what the software is doing and make informed decisions about what to use and when, which settings to choose, and how to ensure you are following best practices. We also cover elements that you must implement in the application layer. In addition, following this article will give you the background knowledge to confidently modify LoRaMAC-Node to your needs, and even port LoRaMAC-Node or LoRa Basics Modem to other languages and platforms.
Introduction to Class B and Class C Modes¶
Devices implementing Class A are only able to receive messages from the network server in one or two time periods directly after sending an uplink. Our paper In-Depth: Sending and Receiving Messages with LoRaWAN describes this in detail.
Class A devices may switch over into Class B mode, described in Enabling and Operating Class B Mode, which allows the device to open additional receive windows during which messages can be received from the network server. By default, these windows can be opened roughly once every 128 seconds; you can increase this frequency as described in Increasing the Number of Ping Slots Used in Each Beacon Window. Opening additional windows required for Class B operations consumes more power than Class A mode, but also enables a wider range of use-cases, providing it is acceptable for there to be a short delay before the message is received. For example, a Class B device may be used to shut down a valve in the event of an early earthquake warning.
For those use cases where immediate action is required, for example shutting off water in the event of a detected leak, end devices must operate in Class C mode. Class C mode, described below in Class C: Continuously Listening for Downlinks, allows for messages to be received by the device at any time except when it is transmitting Class A uplinks or listening for Class A downlinks. Class C mode consumes higher power than Classes A and B, requiring the device be continually connected to mains power unless the battery can be frequently changed.
A device can be programmed to switch between Classes A, B, and C modes at different times of day or month. Alternatively, switching could be triggered by use of a custom application downlink, which the end device can use to determine when to change the class. Moving between classes when appropriate will result in lower battery usage than keeping the device in Class C or B mode permanently.
Class B and C modes can also be used to send firmware updates over the air (FUOTA) to one or more devices. You can read more about FUOTA in the TR002 v1.0.0 FUOTA Process Summary Technical Recommendation.
Sending Messages to Multiple End Devices Simultaneously¶
Class B and C downlinks may be unicast, sent to a single end device; or multicast, sent to a group of end devices simultaneously. Multicasting is useful when you need to send a message to a group of devices at the same time, for example turning off all the streetlights in an area or turning off many different valves in the event of an early earthquake warning. Multicasting is also useful when performing firmware upgrades over the air, as you will need to update many devices and it would be very time-consuming to update them all individually.
End devices that will receive multicast messages must first be placed into a multicast group, where each device in the group shares an identical multicast network address, multicast session keys, and a multicast frame counter.
The LoRaWAN Link Layer Specification v1.0.4 does not define a standard approach for onboarding an end device into a multicast group but specifies that this process should be established using the application layer, external from the core LoRaWAN functionality. In practice, this means that it is up to you to define the format and contents of messages transmitted as application downlinks (not MAC commands), and program your end device to receive these messages and act upon them. The LoRaWAN Remote Multicast Setup Specification TS005-2.0.0 proposes a standard secure approach to constructing these messages, as well as a set of predefined actions the end device should take when receiving each message. If you are going to implement multicasting, you should implement and follow this standard, which may also allow you to take advantage of code libraries and SDKs that others may produce.
Sending Class B and C Messages¶
Class B and C downlinks are sent to a device from the network server. Each network server will support various options to supply the downlinks, including the use of APIs which enable integrations from third parties, as well as providing a user interface to enable manual submission of messages. The network server then sends the downlink to the device using a single gateway. If the device is operating in Class C mode, the network server broadcasts the message immediately. If the end device has informed the network server that it is operating in Class B mode, the network server will wait for a time slot before sending the message. Learn more about how these time slots are determined in Timing of Ping Slot Windows below.
Note
The network server selects the gateway it will use by identifying which has the highest chance of ensuring the message is received by the device, based on the gateways it recently received Class A uplinks from.
Because the network server uses statistics from recent Class A uplinks it has received to select the gateway, it is important that the end device sends regular Class A uplinks to the network server. We discuss this below in Updating the Network Downlink Route.
Enabling and Operating Class B Mode¶
The following procedure explains how the end device should notify the network server that it is ready to commence Class B operations, and the steps to take to sync its clock with the network servers so that it can receive a high number of downlinks while consuming as little power as possible.
Request the Network Server Time¶
The end device first sends a Class A uplink containing a DeviceTimeReq MAC command. There is no payload associated with the DeviceTimeReq MAC command; it is sent as a single octet command identifier (CID) set to 0x0D as described in section 5, MAC Commands (page 27) of the LoRaWAN Link Layer Specification v1.0.4. Follow the guidelines in the Sending Messages (Uplinks) and Opening Receive Windows section of our In-Depth: End Device Messaging LoRaWAN 1.0.4 paper for advice on sending uplinks containing MAC commands.
When transmission of the uplink containing DeviceTimeReq ends, the end device should note its internal time, referred to here as END_OF_DEVICETIMEREQ_TRANSMISSION_TIME.
Note
The DeviceTimeReq MAC command can be sent within the FOpts field, taking advantage of encryption, unless there is application data to send at the same time.
Open the Class A RX windows as described in Receiving Messages (Downlinks) and wait for the DeviceTimeAns MAC command in the response. As shown in Figure 1, DeviceTimeAns contains the number of seconds and fractional seconds since the GPS epoch (January 6th, 1980, 00:00:00 UTC) on the network server at the end of the uplink transmission. Read the full specification of DeviceTimeReq and DeviceTimeAns in section 5.9 ‘End-Device Time Commands (DeviceTimeReq, DeviceTimeAns)’ (page 41) of the LoRaWAN Link Layer Specification v1.0.4
Figure 1: Fields Contained in DeviceTimeAns¶
The end device can now use the DeviceTimeAns along with the internal time noted at the end of transmission (END_OF_DEVICETIMEREQ_TRANSMISSION_TIME) and adjust its internal clock accordingly so that it matches the network server’s clock.
Warning
The GPS epoch does not consider leap seconds and is not considered UTC time. If your end device uses UTC time, adjust accordingly.
Listen for Beacons¶
Each gateway that supports Class B operations broadcasts a message, referred to as a beacon, once every 128 seconds. Beacons allow the end device to continue to align its internal clock with the network server and, if the gateway has support for adding gateway information, may also allow the end device to detect whether the gateway the beacon is received from has changed.
Warning
Not all gateways support Class B mode. Gateways must have GPS to support Class B since GPS timing is used for the precise broadcast of the beacons. Choose gateways that have GPS and list Class B support in their datasheets to use Class B.
Timing of Beacons¶
The end device needs to calculate the precise moment the first beacon will be broadcast so that it can listen for the beacon. The end device should have already aligned its internal clock to the internal clock of the network server as described in the prior step Request the Network Server Time.
The network broadcasts beacons once every 128 seconds since its calculation of the start of the GPS epoch (January 6th, 1980, 00:00:00 UTC). The end device uses its local time, already synced to the network server as described in the prior step Request the Network Server Time, to work out when to begin listening for the first beacon. As shown in Figure 2, the end device must also consider the following adjustments that will need to be made:
-
a 1.5 millisecond delay (TBeaconDelay) to allow time for the gateway to begin broadcasting
-
a minor difference (TAccuracy) where the message is broadcast by the gateway slightly earlier or later than expected. This timing precision should be provided by the gateway manufacturer. After the first beacon is received, the Prec field can be used to determine the maximum timing difference to expect in subsequent beacons as described in section 13.5, ‘Beacon Precise Timing’ (page 70) of the LoRaWAN Link Layer Specification v1.0.4.
Figure 2: Timing of beacons¶
Follow the guidelines in section 13.5, ‘Beacon Precise Timing’ (page 70) of the LoRaWAN Link Layer Specification v1.0.4 to find the full set of algorithms to use to calculate when to begin listening for the beacon.
Note
The end device will use the timing provided in each beacon to remain synced to the network server clock as described in the upcoming section Processing and Using the Beacon. It then continues to listen for beacons at the appropriate times, always considering TBeaconDelay and the TAccuracy communicated in the previous beacon’s Prec field.
Data Rate and Frequency of Beacons¶
The frequency and data rate on which to listen for the beacon depends on the region the end device will operate in.
Dynamic channel plan regions use a single default channel and data rate to broadcast all beacons. Dynamic channel plan regions include EU868 and are listed on page 21 of the RP002-1.0.3 LoRaWAN Regional Parameters specification. The default channel and data rate to use are specified in the ‘Class B beacon and default downlink channel’ subsection for the region in chapter 2 of the RP002-1.0.3 LoRaWAN Regional Parameters specification.
All other regions, including US915, AU915, and CN470, employ frequency hopping whereby the gateway broadcasts the beacon on each channel in a sequence, alternating between the channels on each broadcast. These regions all use a single default data rate. Find each region’s data rate and an algorithm to calculate the channel hopping sequence in the ‘Class B beacon’ section for the region in chapter 2 of the RP002-1.0.3 LoRaWAN Regional Parameters specification.
Handle Requests to Update the Frequency¶
The network server may request that the end device update the frequency it uses to receive beacons by sending a new frequency using the BeaconFreqReq MAC command. When the BeaconFreqReq MAC command is received, the end device must validate whether the new frequency is allowed by its radio. The end device then informs the network server of whether it can use the new frequency or not by sending the BeaconFreqAns MAC command back to the network server using a Class A uplink.
Details of the BeaconFreqReq and BeaconFreqAns MAC commands can be found in section 12.2 ‘BeaconFreqReq’ (page 63) in RP002-1.0.3 LoRaWAN Regional Parameters specification.
When the end device sends a BeaconFreqAns confirming that it can use the new frequency, the network server will update the frequency it uses for sending beacons, and the end device must now listen for beacons on the new frequency. The new single frequency replaces any frequency-hopping algorithm currently in use.
The network server can request that the end device return to its default frequency setting by sending a BeaconFreqReq MAC command with the Frequency field set to 0. After the end device responds confirming this is possible, it should return to using the default frequency for dynamic channel plan regions, or the frequency hopping algorithm for all other regions.
Processing and Using the Beacon¶
The beacon receive window should remain open for long enough to detect a preamble. If no preamble is detected, the end device must stop listening until the next expected beacon broadcast. Consult the Handling Absence of Beacons section for advice on how the end device should behave when no beacons are detected.
If a preamble is detected, the precise time it begins to be received must be stored by the end device, referred to here as BEACON_PREAMBLE_RECEIVE_TIME.
The end device should then demodulate and process the beacon. The beacon frame length and position of the contents depend on the spreading factor defined by the data rate, which varies between regions. Locate the spreading factor to use in the region your end device will operate in by consulting the ‘Class B beacon’ or ‘Class B beacon and default downlink channel’ subsection within the section for the region in chapter 2 of the RP002-1.0.3 LoRaWAN Regional Parameters specification. Cross-reference the spreading factor with Table 74 (page 67) of the LoRaWAN Link Layer Specification v1.0.4 to identify the frame format for your region.
The beacon contains 3 fields which are used in the next steps: Time, Param, and GwSpecific.
Sync the Clock to the Time Reference¶
The four Time octets in the beacon communicate the number of seconds elapsed since the GPS epoch at the moment the beacon was transmitted, encoded as explained in section 13.2 ‘Beacon Frame Format’ (page 68) of the LoRaWAN Link Layer Specification v1.0.4.
The end device should align its internal timing reference with the time contained in the Time field, using the moment the beacon was first detected, referred to earlier as BEACON_PREAMBLE_RECEIVE_TIME.
Store the Time Field¶
The end device must store the contents of the Time field temporarily for use in the ping slot timing algorithm described in Timing of Ping Slot Windows.
Update TAccuracy Using the Prec Bit¶
The Param octet contains the Prec bit which communicates the timing precision of the beacons, discussed in the earlier Timing of Beacons section. The contents of the Prec bit should be used to update the value of TAccuracy, first converting the Prec bit by following the algorithm in section 13.2 ‘Beacon Frame Format’ (page 68) of the LoRaWAN Link Layer Specification v1.0.4.
Use of GwSpecific (Optional)¶
The GwSpecific octets are not sent by all gateways, so this may not be present.
If the GwSpecific octets are present, they are used to either communicate the GPS coordinates of the antenna broadcasting the beacon, or the network’s NetID alongside a gateway identifier. The rules for understanding the data in the GwSpecific octets are found in section 13.3 ‘Beacon GwSpecific Field Format’ (page 68) of the LoRaWAN Link Layer Specification v1.0.4.
Learn how to use the information in GwSpecific to improve the performance of Class B devices that can move in the best practice section Updating the Network Downlink Route.
Notify the Network Server That End Device is in Class B Mode¶
Now that the beacon has been detected and processed, the end device can notify the network that it is going to begin listening for Class B downlinks by sending a Class A uplink with the Class B bit set to 1. See our In-Depth: Sending and Receiving Messages with LoRaWAN paper for details on how to send an uplink and where to set the Class B bit. This message can be otherwise empty; it does not need to also contain application data or MAC commands, as shown in Figure 3.
Figure 3: Format of an Empty Message Communicating Class B Bit¶
Listen for Class B Downlinks¶
The network server will now send any queued Class B downlink messages at specific times after a beacon has been transmitted. This section explains how the end device can calculate the exact times to open additional receive windows at the time the downlink messages are being broadcast, as well as identify the appropriate data rate and frequency to listen on.
Timing of Ping Slot Windows¶
Beacons are broadcast once every 128 seconds. At the point when a beacon is first detected, there is a period of 2.120 seconds during which no downlinks will be received, allowing time for the beacon to be demodulated. This period is referred to as BEACON_RESERVED in the specification.
Just before the next beacon will be received there is a period of 3 seconds during which no downlinks will be transmitted, allowing time to complete transmission of any Class B downlinks before the next beacon is broadcast. This period is referred to as the BEACON_GUARD in the specification.
There is a beacon window (BEACON_WINDOW) of 122.880 seconds during which a Class B downlink may be received between the BEACON_RESERVED period directly after the preceding beacon is received and the BEACON_GUARD period before the next beacon is received.
Figure 4: Timing of BEACON_RESERVED, BEACON_WINDOW and BEACON_GUARD¶
The beacon window period is divided into 4096 windows of 30ms each, referred to in the specification as ping slots. One or more of these ping slots is then selected by the network server to broadcast any queued downlinks, as shown in Figure 5.
Figure 5: Ping Slots Within the BEACON_WINDOW, with an Example of a Downlink Being Broadcast in Ping Slot 3¶
The ping slot that is used to send a downlink is randomized per beacon period and per end device, which reduces the chance of the gateway having to transmit multiple downlinks at the same time. An algorithm is run by the network server to identify the ping slot or slots it will use in each beacon period; the end device runs the same algorithm so that it begins to listen at the same time as the network server is transmitting.
Use the algorithm in section 11.2 ‘Slot Randomization’ (page 60) of the LoRaWAN Link Layer Specification v1.0.4 to calculate the times when the downlink windows must be opened. This algorithm requires the following inputs:
-
End device address (DevAddr)
When listening for unicast messages, use the DevAddr that was set during the end device activation process, as described in our paper In-Depth: LoRaWAN End Device Activation.
When listening for multicast messages, use the multicast network address as the DevAddr; this is configured outside of the LoRaWAN core specification. See Sending Messages to Multiple End Devices Simultaneously for more details on multicasting.
-
Periodicity
When listening for unicast messages, the Periodicity is a configurable setting that the end device and network server use to calculate the number of ping slots that will be used for transmission during each beacon window. The algorithm to use to convert the Periodicity value into the number of ping slots which will be used per beacon window (PingNb) is found in section 11.2 ‘Slot Randomization’ (page 60) of the LoRaWAN Link Layer Specification v1.0.4.
The end device should begin by using the default Periodicity value, defined as 7 in section 2.3 ‘Default Settings’ of the RP002-1.0.3 LoRaWAN Regional Parameters specification. The Periodicity value 7 means a single ping slot is used per beacon period, as shown in the example in Figure 5, meaning the end device needs to only listen during a single 30ms period during the 122.880 second beacon window.
The end device can modify the periodicity to increase the number of ping slots used during each beacon window as explained in Increasing the Number of Ping Slots Used in Each Beacon Window.
When listening for multicast messages, the value of Periodicity is defined by the application layer, outside of the LoRaWAN specification. TS005-2.0.0 LoRAWAN Remote Multicast Setup Specification contains a recommended approach to managing periodicity when using multicasting.
-
Beacon time
The beacon time value is found in the beacon payload received at the start of the beacon window, in the Time field. The end device should have saved this value, as described in Store the Time Field, and can now retrieve it.
The algorithm will output the ping slot or slots that will be used and calculate the time each will be opened.
If the end device is expecting both unicast and multicast messages, as shown in Figure 6, the algorithm should be run twice, first with the unicast DevAddr and Periodicity, then a second time with the multicast DevAddr and Periodicity. The end device can then listen on the unicast and multicast slots that will be used during the beacon window.
Figure 6: Multicast and Unicast Ping Slots in Use in the Same Beacon Window¶
Note
If one of the Class B slots is required to be opened at the same time as a Class A receive window, the Class A receive window has priority. Listen on the Class A frequency and data rate to open the Class A receive window, instead of the Class B frequency and data rate.
Increasing the Number of Ping Slots Used in Each Beacon Window¶
The end device may increase the number of unicast ping slots per beacon window using the Periodicity field of the PingSlotParam octet in the PingSlotInfoReq MAC command.
Note
Changing the Periodicity only changes the ping slots for unicast downlinks; the periodicity for multicast downlinks is not modified using the PingSlotInfoReq command. The LoRaWAN Remote Multicast Setup Specification v1.0.0 proposes an approach to managing periodicity for multicast downlinks.
Before sending the MAC command, close the Class B operations on the end device, stopping the windows that listen for beacons and ping slots.
Send the PingSlotInfoReq MAC command as a Class A uplink, with the Class B Enabled Bit (ClassB) set to 0.
The specification of the PingSlotInfoReq MAC command is found in section 12.1 ‘PingSlotInfoReq’ (page 62) of the LoRaWAN Link Layer Specification v1.0.4. The Periodicity value can be set between 0 and 7, which is represented as an unsigned 3-bit integer.
After sending the PingSlotInfoReq, the end device must listen for a PingSlotInfoAns with an empty payload in one of the Class A receive windows.
If no PingSlotInfoAns is received, then the end device must not update its Periodicity value and should attempt to retry the MAC command. If using Adaptive Data Rate (ADR), the device can commence the backoff procedure explained in our paper Implementing Adaptive Data Rate (ADR) to try to regain connectivity with the network server.
If a PingSlotInfoAns is received, then the end device must update its Periodicity value to the transmitted value. The end device can then restart Class B operations by again listening for a beacon, transmitting the Class B bit in a Class A uplink when a beacon is received, and resuming listening for downlinks.
Warning
Avoid modifying the Periodicity unless you have a strong reason to do so. A Periodicity of 0 would mean a ping slot is opened every second during the beacon window, and while this will increase the number of opportunities to receive a downlink, it also increases power consumption. Any value lower than 7 increases the number of ping slots within the beacon window, so choose the value carefully, using the algorithm described in Periodicity.
Data Rate Used to Receive Downlinks¶
The default data rate for unicast or multicast ping slots is the same data rate that is used to receive the beacon, as described in section 2.3 ‘Default Settings’ of the RP002-1.0.3 LoRaWAN Regional Parameters specification under the setting for PING_SLOT_DATARATE.
The default data rate depends on the region the end device will operate in.
If the region your end device will operate in uses a dynamic channel plan, find the default beacon data rate in the ‘Class B beacon and default downlink channel’ subsection for the region in chapter 2 of the RP002-1.0.3 LoRaWAN Regional Parameters specification.
For all other regions, the beacon data rate is found in the ‘Class B beacon’ subsection within the section for the region.
Frequency Used to Receive Downlinks¶
The default frequency for unicast or multicast ping slots depends on the region your end device will operate in.
If the region your end device will operate in uses a dynamic channel plan, the frequency to use is described as the ‘Class B default downlink pingSlot frequency’ in the ‘Class B beacon and default downlink channel’ subsection within the section for the region in chapter 2 of the RP002-1.0.3 LoRaWAN Regional Parameters specification.
For the CN470 region, section 2.9.8 ‘CN470-510 Class B Beacon’ (page 60) of the RP002-1.0.3 LoRaWAN Regional Parameters specification describes how to work out which frequency will be used.
For the US915 and AU915 regions, the end device should use the channel defined by following the algorithm defined in section 14.2 ‘Frequency-Hopping Beacon Transmission’ (page 73) of the RP002-1.0.3 LoRaWAN Regional Parameters specification which explains how to use the Time field of the preceding beacon and the DevAddr to calculate the channel to use for a given ping slot.
Open Receive Windows to Listen for Class B Downlinks¶
The end device now knows when to begin listening, and the data rate and frequency to listen on. The ping slot window should remain open for long enough to detect a preamble. If no preamble is detected, the device should stop listening. If a preamble is detected, then the window should remain open until the message has been demodulated. Process the message by following the method described in Processing Class B Downlinks.
Handle Requests to Update Downlink Frequency and Data Rate¶
The network server may request that the end device change the frequency and data rate unicast downlinks will be received on by sending the PingSlotChannelReq MAC command. When the PingSlotChannelReq MAC command is received, the end device must validate whether the new frequency and data rate are allowed by its radio. The end device then informs the network server of whether it could use the new frequency and data rate or not by sending the PingSlotChannelAns MAC command as soon as possible using a Class A uplink.
Details of the PingSlotChannelReq and PingSlotChannelAns MAC commands can be found in section 12.3 ‘PingSlotChannelReq’ (page 64) in RP002-1.0.3 LoRaWAN Regional Parameters specification.
When an end device sends a PingSlotChannelAns confirming that it can use the new frequency and data rate, the network server will update the frequency and data rate it uses for sending Class B unicast downlinks, and the end device must now listen for such downlinks on the new frequency and data rate. The new single frequency replaces any frequency hopping algorithm currently in use.
The network server can request that the end device return to its default frequency setting by sending a PingSlotChannelReq MAC command with the Frequency field set to 0. After the end device responds confirming that this is possible, it should return to using the default frequency, including any frequency hopping algorithms previously in use.
Processing Class B Downlinks¶
Class B downlinks use the same format and can be interpreted in the same way as Class A downlinks, with the following exceptions:
-
The FPending bit in Class B downlinks does not share the same meaning with the FPending bit when sent in Class A downlinks. Read section 9.2 ‘Downlink Frames’ (page 54) of the LoRaWAN Link Layer Specification v1.0.4 to understand how the FPending bit in a Class B downlink is used to prioritize ping slot sequences in the event of ping slot collision.
-
Class B downlinks may not contain MAC commands. A downlink containing MAC commands should be ignored.
If the Class B downlink was multicast, in addition to the above considerations the end device should also verify that the ACK bit is set to 0 and the FType field is set to 011 (unconfirmed data downlink), otherwise the entire frame should be discarded.
Read the Processing the Downlink Packet section of our paper In-Depth: Sending and Receiving Messages with LoRaWAN to learn how to interpret Class A, B, and C downlinks.
Responding to Confirmed Class B Downlinks¶
If the end device receives a confirmed downlink (the FType field is set to 101), the end device must send a Class A uplink with the ACK bit set to 1 (a response) within the time frame described in Responding to Confirmed Downlinks.
Continuing in Class B Mode¶
After the first beacon period of 128 seconds, the end device should continue opening subsequent beacon reception windows as described in Listen for Beacons.
If a beacon is detected during the reception window, the end device should continue to update its internal timing reference with the Time value supplied in the beacon, as described in Processing and Using the Beacon, to avoid clock drift. If the end device is monitoring gateways to determine when to send an uplink, described in Use of GwSpecific (Optional), then this data should be updated with each received beacon. The end device must also continue to open the ping slot windows, as described in Listen for Class B Downlinks.
If no beacon is received, the end device should continue to open the ping slot windows at the expected times following the guidance in Listen for Class B Downlinks, and should also work through the measures described in Handling Absence of Beacons.
The end device does not need to follow the steps in Notify the Network Server End Device is in Class B Mode again until Class B mode is disabled. The network server will remember that Class B mode is enabled on this device until a Class A uplink is received with the ClassB bit set to 0.
Warning
Make sure that all Class A uplinks have the ClassB bit set to 1 during Class B operations, otherwise you will accidentally stop the network from sending Class B downlinks.
All subsequent downlinks received should be processed as described in Processing Class B Downlinks.
If the end device needs to close Class B mode, it should be programmed at that point to send an uplink with the ClassB bit set to 0.
Note
If you want to be able to change modes remotely, program the end device to close Class B mode on receipt of a custom application downlink. You could use an otherwise unused Frame Port (FPort) value between 1 and 223 with an empty Frame Payload (FRMPayload) to achieve this with minimal data. Learn how to send messages in our paper In-Depth: Sending and Receiving Messages with LoRaWAN.
Class B Best Practices¶
Handling Absence of Beacons¶
If the end device does not detect a beacon at the expected time, continue to listen for beacons and Class B downlinks using the end device’s internal clock for a period of two hours. Beacons might not be received for a short period for a range of reasons, including a gateway being temporarily disabled or excessive interference. During this two-hour period, the internal clock on the end device may drift from the internal clock on the network server, which would lead to missed beacons and downlinks. To compensate for this drift, the times when the end device begins and ends listening for beacons and Class B downlinks should be progressively expanded, listening slightly earlier and for slightly longer with each passing beacon period.
During this two-hour window, if a beacon is detected, the internal clock must be updated and the duration the end device listens for beacons and ping slots should be reset to the original size. The two-hour timer must then be reset, so that from this moment, the end device will continue listening for beacons and Class B downlinks for another two hours without a beacon.
Learn more in section 10 ‘Class B Beacon Acquisition and Tracking’ (page 57) of the LoRaWAN Link Layer Specification v1.0.4.
Class C: Continuously Listening for Downlinks¶
End devices in Class C mode listen for downlinks except when they are broadcasting Class A uplinks or the Class A receive windows are open, as described in the Opening the Downlink Windows section of our paper In-Depth: Sending and Receiving Messages with LoRaWAN.
Class C mode is enabled by identifying the end device as a Class C capable device when you register it on the network server. The network server will then immediately send any downlinks it receives using a single gateway.
Listen for Class C Downlinks¶
To operate in Class C mode, the end device should listen using a combination of frequency and data rate parameters referred to as RXC. As shown in figures 7 and 8, the end device should only stop listening on the RXC frequency and data rate when it is sending a Class A uplink, or when it is listening for Class A downlinks during the Class A receive windows.
Figure 7: Device Listening on RXC for Class C Downlinks Except When a Downlink is Received During Receive Window 1 (RX1)¶
Figure 8: Device Listening on RXC for Class C Downlinks Except When Class A Receive Windows Are Open¶
Class C downlinks may be unicast, sent to a single end device; or multicast, sent to a group of end devices simultaneously. We cover this in Sending Messages to Multiple End Devices Simultaneously.
When listening for unicast Class C downlinks, the end device should listen on the same frequency and data rate used by the second Class A receive window, RX2. Find the RX2 data rate and frequency in the ‘Receive Windows’ section for the region your end device operates in within the RP002-1.0.3 LoRaWAN Regional Parameters specification.
When listening for multicast downlinks, the end device should listen on the frequency and data rate defined by you when configuring multicast operations. The LoRaWAN Remote Multicast Setup Specification TS005-2.0.0 provides guidance on setting up multicasting. If your application needs to listen for both unicast and multicast downlinks at the same time, you must configure the network server and application to use the RX2 frequency and data rate for multicast downlinks.
Warning
If the end device is demodulating a Class C downlink when the RX1 or RX2 window needs to be opened, the demodulation should be terminated, and the end device must open the RX1 or RX2 window.
Handle Requests to Update the Unicast Data Rate and Frequency¶
The network server may request that the end device update the frequency and data rate that RX2 uses, and therefore unicast downlinks will be received by sending the RXParamSetupReq MAC command. When the RXParamSetupReq MAC command is received, the end device must validate whether the new frequency and data rate are allowed by its radio. The end device then informs the network server of whether it could use the new frequency and data rate or not by sending the RXParamSetupAns MAC command as soon as possible using a Class A uplink.
Details of the RXParamSetupReq and RXParamSetupAns MAC commands can be found in section 5.4 ‘Receive Windows Parameters (RXParamSetupReq, RXParamSetupAns)’ (page 33) of the LoRaWAN Link Layer Specification v1.0.4.
When an end device sends a RXParamSetupAns confirming that it can use the new frequency and data rate, the network server will update the frequency and data rate it uses for sending Class C unicast downlinks, and the end device must now listen for such downlinks on the new frequency and data rate.
Warning
When the network server transmits the RXParamSetupReq MAC command, it will not send any more Class C downlinks until it receives the RXParamSetupAns response from the end device. It is therefore important that the end device responds with the RXParamSetupAns message in a Class A uplink as soon as possible following the receipt of the RXParamSetupReq command.
Processing Class C Downlinks¶
Class C downlinks use the same format and can be interpreted in the same way as Class A downlinks, with the following exception:
-
Class C downlinks may not contain MAC commands. A downlink containing MAC commands should be ignored.
If the Class C downlink was multicast, in addition to the above exception, the following apply:
-
The end device should verify that the ACK bit is set to 0 and the FType field is set to 011 (unconfirmed data downlink), otherwise the entire frame should be discarded.
-
The FPending bit in Class B downlinks does not share the same meaning with the FPending bit when sent in Class A downlinks. Read section 9.2 ‘Downlink Frames’ (page 54) of the LoRaWAN Link Layer Specification v1.0.4 to understand how the FPending bit in a Class B downlink is used to prioritize ping slot sequences in the event of ping slot collision.
Read the Processing the Downlink Packet section of our paper In-Depth: Sending and Receiving Messages with LoRaWAN to learn how to interpret Class A, B, and C downlinks.
Responding to Confirmed Class C Downlinks¶
If the end device receives a confirmed downlink (the FType field is set to 101), the end device should send a Class A uplink with the ACK bit set to 1 (a response) within the time frame described in Responding to Confirmed Downlinks.
Responding to Confirmed Downlinks¶
If the end device receives a confirmed downlink (the FType field is set to 101), the end device should send a Class A uplink with the ACK bit set to 1 (a response) within the time frame described below.
The end device must not transmit the response before the time defined by RETRANSMIT_TIMEOUT plus the maximum time on air of an uplink frame. The value of RETRANSMIT_TIMEOUT is defined as a random delay of between 1 and 3 seconds in section 2.3 of RP002-1.0.3 LoRaWAN Regional Parameters specification.
If the end device is not using ADR and is not setting the ADR bit in uplinks, the Class A uplink response must be sent before the end of the CLASS_B_RESP_TIMEOUT for Class B mode, or CLASS_C_RESP_TIMEOUT for Class C mode, both of which are defined as 8 seconds in section 2.3 of RP002-1.0.3 LoRaWAN Regional Parameters specification.
If the end device is using ADR and is setting the ADR bit in uplinks, the Class A uplink response must be sent before the end of the amount of time derived using the algorithm declared in the specification.
The Class B algorithm, found in section 9.3.1 ‘Unicast downlink ping frame format’ (page 55) of the LoRaWAN Link Layer Specification v1.0.4, is:
CLASS_B_RESP_TIMEOUT * NbTrans + RECEIVE_DELAY2 * (NbTrans-1)
The Class C algorithm, section 15 ‘Continuously Listening End-Device (Class C)’ (page 75) of the LoRaWAN Link Layer Specification v1.0.4, is:
CLASS_C_RESP_TIMEOUT * NbTrans + RECEIVE_DELAY2 * (NbTrans-1)
The variables used in these algorithms are defined as follows:
-
Class B response timeout (CLASS_B_RESP_TIMEOUT) / Class C response timeout (CLASS_C_RESP_TIMEOUT)
These are both defined as 8 seconds in section 2.3 of RP002-1.0.3 LoRaWAN Regional Parameters specification.
-
Number of retransmissions (NbTrans)
The default value of NBTrans should be set to 1 as defined in the specification section 5.2 Link ADR Commands (page 29) of the TS001-1.0.4 LoRaWAN L2 1.0.4 Specification.
The value of NBTrans is updated by the network using the NBTrans field in the Redundancy octet of the LinkADRReq MAC command. If the end device received an NBTrans value in a LinkADRReq MAC command and responded with an LinkADRAns, then it should be using the updated value as NBTrans. Read more in the Link Adaptive Data Rate (ADR) Commands section of our paper A Deep Dive into LoRaWAN MAC Commands.
During the ADR Backoff Procedure, the NBTrans value is reset to 1.
-
RECEIVE_DELAY2
This is the amount of time the end device waits after the end of Class A uplink transmission before opening the second receive window. RECEIVE_DELAY2 should be set to RECEIVE_DELAY1 plus 1 second, as defined in section 2.3 Default Settings of the RP002-1.0.3 LoRaWAN Regional Parameters specification. RECEIVE_DELAY1 refers to the amount of time the end device waits after the end of Class A uplink transmission before opening the first receive window.
Following device reset, RECEIVE_DELAY1 should be set to one second, as defined in section 2.3 Default Settings of the RP002-1.0.3 LoRaWAN Regional Parameters specification.
If the end device has since joined the network using OTAA, the value of RECEIVE_DELAY1 should have been updated to the value communicated in the RXDelay field in the join accept, as described in the Handle the Downlink Configuration Settings (DLSettings and RXDelay) section of our paper In-Depth: LoRaWAN End Device Activation.
The network server may also attempt to update the RECEIVE_DELAY1 value at any time using the Del field in the MAC command RXTimingSetupReq as described in section 5.7 Setting Delay between TX and RX (page 39) of the LoRaWAN Link Layer Specification v1.0.4. If the end device received a RXTimingSetupReq and responded with an RXTimingSetupAns, then it should be using this Del value as the RECEIVE_DELAY1.
To ensure that the response reaches the network server, it is recommended to transmit the response NbTrans times before the end of maximum allowed delay. Best practice is to broadcast each copy of the response at a random time within the permitted period.
Read more about responding to confirmed uplinks in section 9.3.1, Unicast downlink ping frame format (page 55), of the LoRaWAN Link Layer Specification v1.0.4.
Class B and C Best Practices¶
Updating the Network Downlink Route¶
The network server analyzes the gateways it received Class A uplinks through to calculate which gateway to use to transmit downlinks to the end device. Over time, environmental factors can cause interference, or the end device may be moved, meaning that the gateway with the highest chance of reaching the end device may change. To keep the network updated, the end device must regularly broadcast Class A uplinks. This must be handled outside of the LoRaWAN network layer, so you must consider this when designing your application. The decision on how frequently to send a regular uplink should consider your use case, how essential the Class B downlinks are to device operation, and ensuring reasonable battery life.
If you know that your end device will move regularly, you can program the device to send an additional uplink after it has moved significantly. This uplink will be sent via the nearest gateways in the new location, and the network will select one of these to send subsequent downlinks to.
If your end device has a GPS on board, or an accelerometer, this can be used to detect that the device has moved and trigger the uplink. Alternatively, the end device can use the gateway specific (GwSpecific) octets of the beacon, which identify the gateway that beacons were received from. The GwSpecific octets from each beacon can be compared against a record of recent beacons to identify when a new gateway is seen. If a new gateway is seen, the end device can assume it may have moved and issue a Class A uplink to update the network. Because not every gateway will include a gateway specific field, GPS or accelerometer is more reliable option if available. Learn more about the GwSpecific field in section 13.3 ‘Beacon GwSpecific field Format’ (page 68) of the LoRaWAN Link Layer Specification v1.0.4.
Conclusion¶
In this paper you have learned how to implement Class B and C mode following the LoRaWAN Link Layer Specification v1.0.4 while implementing best practices to ensure that your end device receives messages with the lowest possible latency while consuming minimal battery life. You have also begun to learn about multicasting.
Read the other papers in this series: In-Depth: LoRaWAN End Device Activation, Implementing Adaptive Data Rate, and A Deep Dive into LoRaWAN MAC Commands.
Complete the series so you will be able to use LoRaMAC-Node or LoRa Basics Modem with confidence, modifying settings and debugging as required. Given the required programming skills, you should also be able to code or contribute open-source code for LoRaWAN network layer libraries on your preferred platform.
Further Reading¶
Read these technical specifications for a full understanding of LoRaWAN 1.0.4 and concepts related to Class B and Class C:
Read our papers on other LoRaWAN 1.0.4 concepts:
To view an example of how LoRaWAN is 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. Read our LoRaMAC-Node Hands-on Lab to learn how to use the LoRaMAC-Node reference implementation.