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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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 B and C Best Practices¶
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.
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.
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.