UM2073

User manual
STM32 LoRa® software expansion for STM32Cube™

Introduction
This user manual describes the LoRa® Expansion Package implementation on the
STM32Lx Series; this software is called I-CUBE-LRWAN. This document also explains how
to interface with the LoRaWAN™ to manage the LoRa® wireless link.
LoRa® is a type of wireless telecommunication network designed to allow long range
communications at a very low bit-rate and enabling long-life battery operated sensors.
LoRaWAN™ defines the communication and security protocol that ensures the
interoperability with the LoRa® network.
The LoRa® Expansion Package is compliant with the LoRa Alliance™ specification protocol
named LoRaWAN™.
The I-CUBE-LRWAN main features are the following:
• Application integration ready
• Easy add-on of the low-power LoRa® solution
• Extremely low CPU load
• No latency requirements
• Small STM32 memory footprint
• Low-power timing services provided
The I-CUBE-LRWAN Expansion Package is based on the STM32Cube™ HAL drivers (see
Section 2).
This user manual provides customer application examples on NUCLEO-L053R8,
NUCLEO-L152RE and NUCLEOL476RG using Semtech expansion boards
SX1276MB1MAS, SX1276MB1LAS, SX1272MB2DAS, SX1262DVK1DAS,
SX1262DVK1CAS and SX1262DVK1BAS.
This document targets the following tools:
• P-NUCLEO-LRWAN1, STM32 Nucleo pack for LoRa® technology
• B-L072Z-LRWAN1, STM32 Discovery kit embedding the CMWX1ZZABZ-091 LoRa®
module (Murata)
• I-NUCLEO-LRWAN1, LoRa® expansion board for STM32 Nucleo, based on the
WM-SG-SM-42 LPWAN module (USI®)
• LRWAN-NS1, expansion board featuring the RiSiNGHF® modem RHF0M003 available in
P-NUCLEO-LRWAN3

December 2018 UM2073 Rev 8 1/52

www.st.com 1
Contents UM2073

Contents

1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1 Acronyms and abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2 LoRa standard overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2 Network architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2.1 End-device architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2.2 End-device classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2.3 End-device activation (joining) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.4 Regional spectrum allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3 Network layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.1 Physical layer (PHY) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.3.2 MAC sublayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4 Message flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4.1 End-device activation details (joining) . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4.2 End-device data communication (class A) . . . . . . . . . . . . . . . . . . . . . . . 14
2.5 Data flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3 I-CUBE-LRWAN middleware description . . . . . . . . . . . . . . . . . . . . . . . 17

3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.3 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.4 Hardware related components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.4.1 Radio reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.4.2 SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.4.3 RTC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.4.4 Input lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4 I-CUBE-LRWAN middleware programming guidelines . . . . . . . . . . . . 23

4.1 Middleware initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.2 Middleware MAC layer functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.2.1 MCPS services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

2/52 UM2073 Rev 8

UM2073 Contents

4.2.2 MLME services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

4.2.3 MIB services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.3 Middleware MAC layer callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.3.1 MCPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.3.2 MLME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.3.3 MIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.3.4 Battery level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.4 Middleware MAC layer timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.4.1 Delay Rx window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.4.2 Delay for Tx frame transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.4.3 Delay for Rx frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.5 Middleware utilities functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.5.1 Timer server APIs description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.5.2 Low-power functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.5.3 System time functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.5.4 Trace functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.5.5 Queuing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.6 Emulated secure-element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.7 Middleware End_Node application function . . . . . . . . . . . . . . . . . . . . . . . 30
4.7.1 LoRa End_Node initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.7.2 LoRa End_Node Join request entry point . . . . . . . . . . . . . . . . . . . . . . . 35
4.7.3 LoRa End-Node start Tx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.7.4 Request End-Node Join Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.7.5 Send an uplink frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.7.6 Request the current network time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.7.7 Request the next beacon timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.7.8 Switch Class Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.7.9 Get End-device current class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.7.10 Request Beacon Acquisition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.7.11 Send unicast ping slot info periodicity . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.8 LIB End_Node application callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.8.1 Current battery level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.8.2 Current temperature level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.8.3 Board unique ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.8.4 Board random seed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.8.5 Make Rx frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

UM2073 Rev 8 3/52

4
Contents UM2073

4.8.6 Request Class mode switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

4.8.7 End_Node Class mode change confirmation . . . . . . . . . . . . . . . . . . . . 38
4.8.8 Send a dummy uplink frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

5 Example description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
5.1 Single MCU end-device hardware description . . . . . . . . . . . . . . . . . . . . . 39
5.2 Split end-device hardware description (two-MCUs solution) . . . . . . . . . . 40
5.3 Package description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.4 End_Node application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.4.1 Activation methods and keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.4.2 Debug switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.4.3 Sensor switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.5 PingPong application description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
5.6 AT_Slave application description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.7 AT_Master application description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

6 System performances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.1 Memory footprints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.2 Real-time constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.3 Power consumption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

7 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

4/52 UM2073 Rev 8

UM2073 List of tables

List of tables

Table 1. List of acronyms and abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Table 2. LoRa classes intended usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Table 3. LoraWAN regional spectrum allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Table 4. Middleware initialization function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Table 5. MCPS services function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Table 6. MLME services function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Table 7. MIB services functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Table 8. MCPS primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Table 9. MLME primitive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 10. Battery level function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 11. Delay Rx functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 12. Delay for Tx frame transmission function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 13. Delay for Rx frame function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 14. Timer server functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 15. Timer server functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 16. System time functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Table 17. Trace functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Table 18. Middleware queuing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Table 19. Secure-Element functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Table 20. LoRa class A initialization function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Table 21. LoRa End_Node Join request entry point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Table 22. LoRa End-Node start Tx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Table 23. End-Node Join Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Table 24. Send an uplink frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Table 25. Current network time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Table 26. Next beacon timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Table 27. Switch Class Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Table 28. Get End-Device current Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Table 29. Request Beacon Acquisition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Table 30. Unicast ping slot periodicity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Table 31. Current battery level function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Table 32. Current Temperature function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Table 33. Board unique ID function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Table 34. Board random seed function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Table 35. Make Rx frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Table 36. LoRa has Joined function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Table 37. End_Node Class mode change confirmation function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Table 38. Send a dummy uplink frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Table 39. Nucleo-based supported hardware. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Table 40. LoRa radio expansion boards characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Table 41. STM32L0xx IRQ priorities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Table 42. Switch options for the application's configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Table 43. BSP programming guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Table 44. Memory footprint values for End_Node application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Table 45. Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

UM2073 Rev 8 5/52

5
List of figures UM2073

List of figures

Figure 1. Network diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Figure 2. TX/Rx time diagram (class A) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Figure 3. Tx/Rx time diagram (class B) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Figure 4. Tx/Rx time diagram (class C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Figure 5. LoRaWAN layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Figure 6. Message sequence chart for joining (MLME primitives) . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Figure 7. Message sequence chart for confirmed-data (MCPS primitives) . . . . . . . . . . . . . . . . . . . . 15
Figure 8. Message sequence chart for unconfirmed-data (MCPS primitives) . . . . . . . . . . . . . . . . . . 15
Figure 9. Data flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Figure 10. Project files structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Figure 11. Main design of the firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Figure 12. LoRaMacCrypto module design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Figure 13. Operation model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Figure 14. LoRa state behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Figure 15. LoRa Class B system state behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Figure 16. Concept for split end-device solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Figure 17. I-CUBE-LRWAN structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Figure 18. PingPong setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Figure 19. Rx/Tx time diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Figure 20. STM32L0 current consumption against time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

6/52 UM2073 Rev 8

UM2073 Overview

1 Overview

The I-CUBE-LRWAN Expansion Package for STM32Cube™ runs on STM32 32-bit

microcontrollers based on the Arm®(a) Cortex®-M processor.

1.1 Acronyms and abbreviations

Table 1. List of acronyms and abbreviations
Term Definition

ABP Activation by personalization

APP Application
API Application programming interface
BSP Board support package
FSM Finite state machine
HAL Hardware abstraction layer
IOT Internet of things
LoRa Long range radio technology
LoRaWan LoRa wide-area network
LPWAN Low-power, wide-area network
MAC Media access control
MCPS MAC common part sublayer
MIB MAC information base
MLME MAC sublayer management entity
MPDU MAC protocol data unit
OTAA Over-this-air activation
PLME Physical sublayer management entity
PPDU Physical protocol data unit
SAP Service access point

a. Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

UM2073 Rev 8 7/52

51
Overview UM2073

1.2 References
• LoRa Alliance specification protocol named LoRaWAN version V1.0.3 - 2018, March -
Final - Released
• IEEE Std 802.15.4TM - 2011. Low-Rate Wireless Personal Area Networks (LR-
WPANs)
• LoRaWAN version 1.1 Regional Parameters - RevB - 2018, January - Released

8/52 UM2073 Rev 8

UM2073 LoRa standard overview

2 LoRa standard overview

2.1 Overview
This section provides a general overview of the LoRa and LoRaWAN recommendations,
focusing in particular on the LoRa end-device which is the core subject of this user manual.
LoRa is a type of wireless telecommunication network designed to allow long range
communication at a very low bit-rate and enabling long-life battery operated sensors.
LoRaWAN defines the communication and security protocol ensuring the interoperability
with the LoRa network.
The LoRa Expansion Package is compliant with the LoRa Alliance specification protocol
named LoRaWAN.
Table 2 shows the LoRa classes usage definition. Refer to Section 2.2.2 for further details
on these classes.

Table 2. LoRa classes intended usage

Class name Intended usage

– Battery powered sensors or actuators with no latency

constraint.
A - All
– Most energy efficient communication class
– Must be supported by all devices.
– Battery powered actuators.
– Energy efficient communication class for latency controlled
B - Beacon downlink.
– Based on slotted communication synchronized with a
network beacon.
– Main powered actuators.
C - Continuous – Devices which can afford to listen continuously.
– No latency for downlink communication.

Note: While the physical layer of LoRa is proprietary, the rest of the protocol stack (LoRaWAN) is
kept open and its development is carried out by the LoRa Alliance.

2.2 Network architecture

LoRaWAN network is structured in a star of stars topology, where the end-devices are
connected via a single LoRa link to one gateway as shown in Figure 1.

UM2073 Rev 8 9/52

51
LoRa standard overview UM2073

Figure 1. Network diagram

/R5DHQGGHYLFH *DWHZD\ 1HWZRUNVHUYHU $SSOLFDWLRQVHUYHU

3HWWUDFNLQJ

6PRNH
DODUP
:DWHUPHWHU
7UDVK
FRQWDLQHU
9HQGLQJPDFKLQH
*DV
PRQLWRULQJ
06Y9

2.2.1 End-device architecture

The end-device is made of an RF transceiver (also known as radio) and a host STM32
MCU. The RF transceiver is composed of a modem and an RF up-converter. The MCU
implements the radio driver, the LoRaWan stack and optionally the sensor drivers.

2.2.2 End-device classes

The LoRaWAN has several different classes of end-point devices, addressing the different
needs reflected in the wide range of applications.

Bi-directional end-devices - class A - (all devices)

• Class A operation is the lowest-power end-device system
• Each end-device uplink transmission is followed by two short downlink receive
windows
• Downlink communication from the server shortly after the end-device has sent an
uplink transmission (see Figure 2)
• Transmission slot is based on own communication needs of the end-device (ALOHA-
type of protocol).

Figure 2. TX/Rx time diagram (class A)

7[ 5[ 5[

5['HOD\

5['HOD\

06Y9

10/52 UM2073 Rev 8

UM2073 LoRa standard overview

Bi-directional end-devices with scheduled receive slots - class B - (beacon)

• Mid power consumption
• Class B devices open extra receive windows at scheduled times (see Figure 3)
• In order for the end-device to open the receive window at the scheduled time, it
receives a time-synchronized beacon from the gateway.

Figure 3. Tx/Rx time diagram (class B)

%&1 31* 31* 7[ 5[ 5[ %&1

5['HOD\

3HULRG3LQJ
5['HOD\

%HDFRQ3HULRG

06Y9

Bi-directional end-devices with maximal receive slots - class C - (continuous)

• Large power consumption
• End-devices of class C have nearly continuously open receive windows, only closed
when transmitting (see Figure 4).

Figure 4. Tx/Rx time diagram (class C)

7[ 5[ 5[ 5[

5['HOD\
5['HOD\

([WHQGV5[XQWLOQH[W7[

06Y9

2.2.3 End-device activation (joining)

Over-the-air activation (OTAA)
The OTAA is a joining procedure for the LoRa end-device to participate in a LoRa network.
Both the LoRa end-device and the application server share the same secret key known as
AppKey. During a joining procedure, the LoRa end-device and the application server
exchange inputs to generate two session keys:
• a network session key (NwkSKey) for MAC commands encryption
• an application session key (AppSKey) for application data encryption

UM2073 Rev 8 11/52

51
LoRa standard overview UM2073

Activation by personalization (ABP)

In the case of ABP, the NwkSkey and AppSkey are already stored in the LoRa end-device
that sends the data directly to the LoRa network.

2.2.4 Regional spectrum allocation

The LoRaWAN specification varies slightly from region to region. The European, North
American and Asian markets have different spectrum allocations and regulatory
requirements. See Table 3 for more details.

Table 3. LoraWAN regional spectrum allocation

Region Supported Band [MHz] Duty cycle Output power

EU Y 868 <1 % +14 dBm

EU Y 433 <1 % +10 dBm
<2 % (BW<250 kHz) or
US Y 915 <4 % (BW>=250 kHz) +20 dBm
Transmission slot < 0.4 s
CN N 779 <0.1 % +10 dBm
AS Y 923 <1 % +16 dBm
IN Y 865 No +20 dBm
KR Y 920 No +10 dBm
RU Y 868 <1 % +16 dBm

2.3 Network layer

The LoRaWAN architecture is defined in terms of blocks, also called “layers”. Each layer is
responsible for one part of the standard and it offers services to higher layers.
The end-device is made at least of one physical layer (PHY), which embeds the radio
frequency transceiver, a MAC sublayer providing access to the physical channel, and an
Application layer (see Figure 5).

12/52 UM2073 Rev 8

UM2073 LoRa standard overview

Figure 5. LoRaWAN layers

8SSHUOD\HU

0$&

3+<

3K\VLFDOPHGLXP DLULQWHUIDFH

06Y9

2.3.1 Physical layer (PHY)

The physical layer provides two services:
• The PHY data service which enables the Tx/Rx of physical protocol data units (PPDUs)
• The PHY management service which enables the personal area network information
base (PIB) management.

2.3.2 MAC sublayer

The MAC sublayer provides two services:
• The MAC data service which enables the transmission and reception of MAC protocol
data units (MPDU) across the physical layer
• The MAC management service which enables the PIB management

2.4 Message flow

This section describes the information flow between the N-user and the N-layer. The
request to a service is done through a service primitive.

2.4.1 End-device activation details (joining)

Before communicating on the LoRaWAN network, the end-device must be associated or
activated following one of the two activation methods described in Section 2.2.3.
The message sequence chart (MSC) in Figure 6 shows the OTAA activation method.

UM2073 Rev 8 13/52

51
LoRa standard overview UM2073

Figure 6. Message sequence chart for joining (MLME primitives)

(QGGHYLFH (QGGHYLFH 1HWZRUN 1HWZRUN

$SSOD\HU 0$&OD\HU 0$&OD\HU $SSOD\HU

0/0(5HT
MRLQUHTXHVW
-RLQUHTXHVW 0/0(,QG
MRLQUHTXHVW

0$&:DLW7LPHU
0/0(5HVS
MRLQDFFHSW
-RLQUHVSRQVH DVN
0/0(&RQI
MRLQDFFHSW
0/0(,QG
MRLQDFFHSW

(QGGHYLFH $SSVHUYHU
06Y9

2.4.2 End-device data communication (class A)

The end-device transmits data by one of the following methods: through a confirmed-data
message method (see Figure 7) or through an unconfirmed-data message (see Figure 8).
In the first method, the end-device requires an ‘Ack’ (acknowledgment) to be done by the
receiver while in the second method, the ‘Ack’ is not required.
When an end-device sends data with an ‘Ackreq’ (acknowledgment request), the end-
device should wait during an acknowledgment duration (‘AckWaitDuration’) to receive the
acknowledgment frame (refer to Section 4.3.1: MCPS).
If the acknowledgment frame is received, then the transmission is successful, else the
transmission failed.

14/52 UM2073 Rev 8

UM2073 LoRa standard overview

Figure 7. Message sequence chart for confirmed-data (MCPS primitives)

(QGGHYLFH (QGGHYLFH 1HWZRUN 1HWZRUN$SS

$SSOD\HU 0$&OD\HU 0$&OD\HU OD\HU

0&365HT
GDWDUHTXHVW

'DWD $FNUHT 

$FN:DLW'XUDWLRQ

$FNQRZOHGJPHQWIUDPH

0&36,QG GDWD

0&36&RQI

(QGGHYLFH $SS6HUYHU
06Y9

Figure 8. Message sequence chart for unconfirmed-data (MCPS primitives)

(QGGHYLFH (QGGHYLFH 1HWZRUN 1HWZRUN

$SSOD\HU 0$&OD\HU 0$&OD\HU $SSOD\HU

0&365HT GDWDUHTXHVW 'DWD

$FNUHT 
0&36,QG GDWD

0&36&RQI

(QGGHYLFH $SSVHUYHU
06Y9

UM2073 Rev 8 15/52

51
LoRa standard overview UM2073

2.5 Data flow

The data integrity is ensured by the network session key (NwkSKey) and the application
session key (AppSKey). The NwkSKey is used to encrypt and decrypt the MAC payload
data and the AppSKey is used to encrypt and decrypt the application payload data. See
Figure 9 for the data flow representation.

Figure 9. Data flow

/R5D5) ,3LQIUD ,3LQIUD

(QGGHYLFH 1HWZRUN $SSOLFDWLRQ
*DWHZD\
VHQVRU±0&8±UDGLR VHUYHU VHUYHU

$SSOLFDWLRQGDWD
$SSOLFDWLRQGDWD

1ZN6.H\ SD\ORDGRI0$&GDWD

$SS6.H\ SD\ORDGRIDSSOLFDWLRQPHVVDJH

06Y9

The NwkSKey is shared between the end-device and the network server. The NwkSKey
provides message integrity for the communication and provides security for the end-device
towards the network server communication.
The AppSKey is shared between the end-device and the application server. The AppSKey
is used to encrypt/decrypt the application data. In other words, the AppSKey provides
security for the application’s payload. In this way, the application data sent by an end-device
can not be interpreted by the network server.

16/52 UM2073 Rev 8

UM2073 I-CUBE-LRWAN middleware description

3 I-CUBE-LRWAN middleware description

3.1 Overview
This I-CUBE-LRWAN package offers a LoRa stack middleware for STM32 microcontrollers.
This middleware is split into several modules:
• LoRaMac layer module
• LoRa utilities module
• LoRa crypto module
• LoRa core module
The LoRa core module implements a LoRa state machine coming on top of the LoRaMac
layer. The LoRa stack module interfaces with the BSP Semtech radio driver module.
This middleware is provided in source-code format and is compliant which the
STM32Cube™ HAL driver.
Refer to Figure 10 for the structure of the project files.

UM2073 Rev 8 17/52

51
I-CUBE-LRWAN middleware description UM2073

Figure 10. Project files structure

%63GULYHUV/R5D70IRU
'LVFRYHU\ERDUG

%63GULYHUVIRU
&0:;==$%=PRGXOH

%63GULYHUV,18&/(2
/5:$1PRGHPERDUG

%63GULYHUV671XFOHR
6HQVRUPRGHPERDUG

%63GULYHUV1XFOHRERDUGV

%63GULYHUVIRU6HPWHFK
5DGLRERDUGV

^WĚƌŝǀĞƌƐĨŽƌ^ĞŶƐŽƌďŽĂƌĚ

0LGGOHZDUH/R5D70FRUH

0LGGOHZDUH/R5D70FU\SWR
HQJLQH

0LGGOHZDUH/R5D700$&
OD\HU

0LGGOHZDUH/R5D705DGLR
LQWHUIDFH

/R5D70DSSOLFDWLRQV

06Y9

18/52 UM2073 Rev 8

UM2073 I-CUBE-LRWAN middleware description

The I-CUBE-LRWAN package includes:

• The LoRa stack middleware:
– LoRaWAN layer
– LoRa utilities such as power, queue, system time, time server, and trace
managements
– LoRa software crypto engine
– LoRa state machine
• Board support package:
– Radio Semtech drivers
– Sensor ST drivers
• STM32L0 HAL drivers
• LoRa main application example

3.2 Features
• Compliant with the specification for the LoRa Alliance protocol named LoRaWAN
• On-board LoRaWAN class A, class B and class C protocol stack
• EU 868MHz ISM band ETSI compliant
• EU 433MHz ISM band ETSI compliant
• US 915MHz ISM band FCC compliant
• KR 920Mhz ISM band defined by Korean Government
• RU 864Mhz ISM band defined by Russian regulation
• End-device activation either through over-the-air activation (OTAA) or through
activation-by-personalization (ABP)
• Adaptive data rate support
• LoRaWAN test application for certification tests included
• Low-power optimized

UM2073 Rev 8 19/52

51
I-CUBE-LRWAN middleware description UM2073

3.3 Architecture
Figure 11 describes the main design of the firmware for the I-CUBE-LRWAN application.

Figure 11. Main design of the firmware

$SSOLFDWLRQ XVHU

0$& 8SSHU/D\HU

0$& /RZHU/D\HU

/R5D0LGGOHZDUH
8WLOLWLHV
WH[W
7LPHUVHUYHU 6HQVRU
/RZ3RZHU GULYHU
5DQGJHQ

&U\SWR
6RIWZDUH
5DGLRGULYHU
6HFXUH
6;[[GULYHU
(OHPHQW

+$/

*3,2 63, 57& ,& $'&

676(07(&+ 3URYLGHGE\6(07(&+ 67
06Y9

The HAL uses Cube APIs to drive the MCU hardware required by the application. Only
specific hardware is included in the LoRa middleware as it is mandatory to run a LoRa
application.
The RTC provides a centralized time unit which continues to run even in Low-power mode
(Stop mode). The RTC alarm is used to wake up the system at specific timings managed by
the timer server.
The radio driver uses the SPI and the GPIO hardware to control the radio (see Figure 11).
The radio driver also provides a set of APIs to be used by higher level software.
The LoRa radio is provided by Semtech, though the APIs have been slightly modified to
interface with the STM32Cube™ HAL.
The radio driver is split in two parts:
• The sx1276.c, sx1272.c and sx126x.c contain all functions which are radio dependent
only.
• The sx1276mb1mas.c, sx1276mb1las, sx1272mb2das, sx1262dvk1das,
sx1262dvk1cas and sx1262dvk1bas contain all the radio board dependent functions.
The MAC controls the PHY using 802.15.4 model. The MAC interfaces with the PHY driver
and uses the timer server to add or remove timed tasks and to take care of the
'Tx time on air'. This action ensures that the duty-cycle limitation mandated by the ETSI is
respected and also carries out AES encryption/decryption algorithm to cypher the MAC
header and the payload.

20/52 UM2073 Rev 8

UM2073 I-CUBE-LRWAN middleware description

Since the state machine, that controls the LoRa class A, is sensitive, an intermediate level
of software has been inserted (lora.c) between the MAC and the application
(refer to MAC’s “upper layer” on Figure 11). With a set of APIs limited as of now, the user is
free to implement the class A state machine at application level.
The application, built around an infinite loop, manages the low-power, runs the interrupt
handlers (alarm or GPIO) and calls the LoRa class A if any task must be done. This
application also implements the sensor read access.

3.4 Hardware related components

3.4.1 Radio reset

One GPIO from the MCU is used to reset the radio.This action is done once at the
initialization of the hardware (refer to Table 40: LoRa radio expansion boards characteristics
and to Section 5.1: Single MCU end-device hardware description).

3.4.2 SPI
The sx127x or sx126x radio commands and registers are accessed through the SPI bus at
1 Mbit/s (refer to Table 40 and to Section 5.1).

3.4.3 RTC
The RTC calendar is used as a timer engine running in all power modes from the 32 kHz
external oscillator. By default, the RTC is programed to provide 1024 ticks (sub-seconds)
per second. The RTC is programed once at initialization of the hardware when the MCU
starts for the first time. The RTC output is limited to a 32-bit timer that is around a 48 days
period.
If the user needs to change the tick duration, note that the tick duration should remain below
1 ms.

UM2073 Rev 8 21/52

51
I-CUBE-LRWAN middleware description UM2073

3.4.4 Input lines

3.4.4.1 sx127x interrupt lines
Four sx127x interrupt lines are dedicated to receive the interrupts from the radio (refer to
Table 40 and to Section 5.1).
The DIO0 is used to signal that the LoRa radio has successfully completed a requested task
(TxDone or RxDone).
The DIO1 is used to signal that the radio has failed to complete a requested task
(RxTimeout).
In FSK mode, a FIFO-level interrupt signals that the FIFO-level has reached a predefined
threshold and needs to be flushed.
The DIO2 is used in FSK mode and signals that the radio has successfully detected a
preamble.
The DIO3 is reserved for future use.
Note: The FSK mode in LoRaWAN has the fastest data rate at 50 kbit/s.

3.4.4.2 sx126x input lines

sx126x interface is simplified compared to sx127x. One busy signal informs the MCU that
the radio is busy and can not treat any commands. The MCU must poll that thew ready
signal is deasserted before any new command can be sent.
DIO1 is used as a single line interrupt.

22/52 UM2073 Rev 8

UM2073 I-CUBE-LRWAN middleware programming guidelines

4 I-CUBE-LRWAN middleware programming guidelines

This section gives a description of the LoRaMac layer APIs. The PHY layer being
proprietary (see Section 2.1: Overview) is out of the scope of this user manual and must be
viewed as a black box.

4.1 Middleware initialization

The initialization of the LoRaMac layer is done through the ‘LoraMacinitialization’ function.
This function does the preamble run time initialization of the LoRaMac layer and initializes
the callback primitives of the MCPS and MLME services (see Table 4).

Table 4. Middleware initialization function

Function Description

LoRaMacStatus_t LoRaMacInitialization
Do initialization of the LoRaMac layer module
(LoRAMacPrimitives_t *primitives,
(see Section 4.3: Middleware MAC layer
LoRaMacCallback_t *callback,
callbacks)
LoRaMacRegion_t region)

4.2 Middleware MAC layer functions

The provided APIs follow the definition of “primitive” defined in IEEE802.15.4-2011 (see
Section 1.2: References).
The interfacing with the LoRaMac is made through the request-confirm and the indication-
response architecture. The application layer can perform a request, which the LoRaMAC
layer confirms with a confirm primitive. Conversely, the LoRaMAC layer notifies an
application layer with the indication primitive in case of any event.
The application layer may respond to an indication with the response primitive. Therefore all
the confirm/indication are implemented using callbacks.
The LoRaMAC layer provides MCPS services, MLME services and MIB services.

4.2.1 MCPS services

In general, the LoRaMAC layer uses the MCPS services for data transmissions and data
receptions (see Table 5).

Table 5. MCPS services function

Function Description

LoRaMacStatus_t LoRaMacMcpsRequest
Requests to send Tx data
(McpsReq_t *mcpsRequest)

UM2073 Rev 8 23/52

51
I-CUBE-LRWAN middleware programming guidelines UM2073

4.2.2 MLME services

The LoRaMAC layer uses the MLME services to manage the LoRaWAN network
(see Table 6).

Table 6. MLME services function

Function Description

LoRaMacStatus_t LoRaMacMlmeRequest Used to generate a join request or request for a

(MlmeReq_t *mlmeRequest) link check

4.2.3 MIB services

The MIB stores important runtime information (such as MIB_NETWORK_ACTIVATION,
MIB_NET_ID) and holds the configuration of the LoRaMAC layer (for example the
MIB_ADR, MIB_APP_KEY). The provided APIs are presented in Table 7.

Table 7. MIB services functions

Function Description

LoRaMacStatus_t LoRaMacMibSetRequestConfirm
To set attributes of the LoRaMac layer
(MibRequestConfirm_t *mibSet)
LoRaMacStatus_t LoRaMacMibGetRequestConfirm
To get attributes of the LoRaMac layer
(MibRequestConfirm_t *mibGet)

4.3 Middleware MAC layer callbacks

Refer to Section 4.1: Middleware initialization for the description of the LoRaMac user event
functions primitives and the callback functions.

4.3.1 MCPS
In general, the LoRaMAC layer uses the MCPS services for data transmission and data
reception (see Table 8).

Table 8. MCPS primitives

Function Description

Event function primitive for the called callback to be

void (*MacMcpsConfirm)
implemented by the application. Response to a
(McpsConfirm_t *McpsConfirm)
McpsRequest
Event function primitive for the called callback to be
Void (*MacMcpsIndication)
implemented by the application. Notifies application that a
(McpsIndication_t *McpsIndication)
received packet is available

24/52 UM2073 Rev 8

UM2073 I-CUBE-LRWAN middleware programming guidelines

4.3.2 MLME
The LoRaMAC layer uses the MLME services to manage the LoRaWAN network
(see Table 9).

Table 9. MLME primitive

Function Description

void (*MacMlmeConfirm) Event function primitive so called callback to be

(MlmeConfirm_t *MlmeConfirm) implemented by the application

4.3.3 MIB
N/A

4.3.4 Battery level

The LoRaMAC layer needs a battery-level measuring service (see Table 10).

Table 10. Battery level function

Function Description

uint8_t HW_GetBatteryLevel (void) Get the measured battery level

4.4 Middleware MAC layer timers

4.4.1 Delay Rx window

Refer to Section 2.2.2: End-device classes. See Table 11 for the delay Rx functions.

Table 11. Delay Rx functions

Function Description

Set the RxDelay1 (ReceiveDelayX -

void OnRxWindow1TimerEvent (void)
RADIO_WAKEUP_TIME)
void OnRxWindow2TimerEvent (void) Set the RxDelay2

4.4.2 Delay for Tx frame transmission

Table 12 presents the function for delay for the Tx frame transmission.

Table 12. Delay for Tx frame transmission function

Function Description

void OnTxDelayedTimerEvent (void) Set timer for Tx frame transmission

4.4.3 Delay for Rx frame

Table 13 presents the function for the delay for Rx frame.

UM2073 Rev 8 25/52

51
I-CUBE-LRWAN middleware programming guidelines UM2073

Table 13. Delay for Rx frame function

Function Description

void OnAckTimeoutTimerEvent (void) Set timeout for received frame acknowledgment

4.5 Middleware utilities functions

4.5.1 Timer server APIs description

A timer server is provided so that the user may request timed-tasks execution. As the
hardware timer is based on the RTC, the time is always counted, even in Low-power modes.
The timer server provides a reliable clock for the user and the LoRa stack. The user may
request as many timers as the application requires.
Four APIs are provided as shown in Table 14:

Table 14. Timer server functions

Function Description

void TimerInit Initialize the timer and associate a callback

(TimerEvent_t *obj, void (*callback) (void)) function when timer elapses
void TimerSetValue
Set the timer a timeout value on milliseconds
(TimerEvent_t *obj, uint32_t value)
void TimerStart (TimerEvent_t *obj) Start the timer
void TimerStop (TimerEvent_t *obj) Stop the timer

The timer server is located in Middlewares\Third_Party\Lora\Utilities.

4.5.2 Low-power functions

The APIs presented in Table 15 allow to manage the Low-power mode of the core MCU.

Table 15. Timer server functions

Function Description

void LPM_EnterLowPower (void) Allow to enter the system in Low-power mode

Allow application to implement dedicated code
void LPM_EnterSleepMode (void)
before entering Sleep mode
Allow application to implement dedicated code
void LPM_ExitSleepMode (void)
before getting out Sleep mode
void LPM_EnterStopMode (void) Enter Low-power Stop mode”
void LPM_ExitStopMode (void) Exit “Low-power Stop mode”
Allow application to implement dedicated code
void LPM_EnterOffMode (void)
before entering Off mode
Allow application to implement dedicated code
void LPM_ExitOffMode(void)
before getting out “Off mode”

26/52 UM2073 Rev 8

UM2073 I-CUBE-LRWAN middleware programming guidelines

Table 15. Timer server functions (continued)

Function Description

LPM_GetMode_t LPM_GetMode (void) Return the selected low-power mode

void LPM_SetStopMode Allow to Enable or Disable the Stop mode in
(LPM_Id_t id, LPM_SetMode_t mode) order to require "Sleep mode"
void LPM_SetOffMode Allow to enable or "Stop mode" or enable "Off
(LPM_Id_t id, LPM_SetMode_t mode) mode"

4.5.3 System time functions

MCU time is referenced to MCU reset. SysTime is able to record the Unix epoch time.
The APIs presented in Table 16 allow to manage the system time of the core MCU.

Table 16. System time functions

Function Description

Based on an input Unix epoch in seconds and

sub-seconds, the difference with the MCU time is
stored in the BACK_UP register (retained even in
void SysTimeSet (SysTime_t sysTime) standby mode).
System time reference is Unix epoch starting
Monday January 1st 1970.
Get the current system time.
SysTime_t SysTimeGet (void) System time reference is UNIX epoch starting
Monday January 1st 1970.
uint32_t SysTimeMkTime (const struct tm* Convert Local time into Epoch time cf.(below
localtime) note)
void SysTimeLocalTime (const uint32_t Convert Local time into Epoch time into local time
timestamp, struct tm *localtime) cf. (below note)

Note: SysTimeMkTime and SysTimeLocalTime are also provided in order to convert epoch into tm
structure as specified by time.h interface.
To convert UNIX time to your local time, time zone need to be added and leap seconds need
to be removed. In 2018, 18 leap seconds need to be removed. In Paris summer time, there
are two hours difference from Greenwich time, assuming time has been set, local time can
be printed on terminal:
{
SysTime_t UnixEpoch = SysTimeGet();

struct tm localtime;

UnixEpoch.Seconds-=18; /*removing leap seconds*/

UnixEpoch.Seconds+=3600*2; /*adding 2 hours*/

SysTimeLocalTime(UnixEpoch.Seconds, & localtime);

PRINTF ("it's %02dh%02dm%02ds on %02d/%02d/%04d\n\r",

UM2073 Rev 8 27/52

51
I-CUBE-LRWAN middleware programming guidelines UM2073

localtime.tm_hour, localtime.tm_min, localtime.tm_sec,

localtime.tm_mday, localtime.tm_mon+1, localtime.tm_year + 1900);
}

4.5.4 Trace functions

The trace module enables to print data on a com port using DMA.
The APIs presented in Table 17 allow to manage the Trace functions.

Table 17. Trace functions

Function Description

TraceInit must be called at the application

initialization. It initializes the com or vcom
void TraceInit (void)
hardware in DMA mode, registers the call back to
be processed at DMA transmission completion.
Convert string format into a buffer and buffer
length and records it into the circular queue if
int32_t TraceSend (const char *strFormat,...) sufficient space is left Returns 0 when queue if
sufficient space is left, Returns -1 when not
enough room is left.

Note: It can be used in polling mode when no real time constraints apply, typically during
application initialization:
#define PPRINTF(...) do{} while (0!= TraceSend (__VA_ARGS__)) //Polling Mode.

It can be used in real time mode. In this case, when there is not space left in the circular
queue, the string is not added and will not be printed out in com port
#define PRINTF(...) do {TraceSend (__VA_ARGS__);} while(0)

Buffer length can be increased in case it is saturated to often in utilities_conf.h

#define DBG_TRACE_MSG_QUEUE_SIZE 256

4.5.5 Queuing functions

The queue module provides a set of services managing a buffer as a circular queue.
The APIs presented in Table 18 allow to manage a circular queuing buffer.

Table 18. Middleware queuing functions

Function Description

int CircularQueue_Init (queue_t *q, uint8_t*

queueBuffer, uint32_t queueSize, uint16_t Do initialization of the circular buffer.
elementSize, uint8_t optionFlags)
uint8_t* CircularQueue_Add (queue_t *q, uint8_t*
Add an element to the circular buffer.
x, uint16_t elementSize, uint32_t nbElements)

28/52 UM2073 Rev 8

UM2073 I-CUBE-LRWAN middleware programming guidelines

Table 18. Middleware queuing functions (continued)

Function Description

uint8_t* CircularQueue_Remove (queue_t *q,

Remove an element from the circular buffer.
uint16_t* elementSize)
Sense if the circular buffer is not empty. If not
uint8_t* CircularQueue_Sense (queue_t *q,
empty, it returns the address of the buffer and its
uint16_t* elementSize)
length through element size.

Note: The queue is filled with elements. Each element is composed of buffer length field (2 bytes)
and the buffer. When an element is too large to fit at the end of the queue, it is fragmented
into two elements.

4.6 Emulated secure-element

By default the proposal hardware platforms doesn't integrate a Secure Element device.
Therefore this Secure-Element device is emulated by software.
Figure 12 describes the main design of LoRaMacCrypto module.

Figure 12. LoRaMacCrypto module design

06Y9

The APIs presented in Table 19 allow to manage the Emulated Secure-element.

UM2073 Rev 8 29/52

51
I-CUBE-LRWAN middleware programming guidelines UM2073

Table 19. Secure-Element functions

Function Description

Initialization of Secure Element driver.

SecureElementStatus_t SecureElementInit
The Callback function which is called when the
(EventNvmCtxChanged seNvmCtxChanged)
non-volatile context must be stored.
SecureElementStatus_t Restores the internal nvm context from passed
SecureElementRestoreNvmCtx (void* pointer to non-volatile module context to be
seNvmCtx) restored.
void* SecureElementGetNvmCtx (size_t* Request Address where the non volatile context
seNvmCtxSize) is stored.
SecureElementStatus_t SecureElementSetKey
Sets a key.
(KeyIdentifier_t keyID, uint8_t* key)
SecureElementStatus_t Computes a CMAC.
SecureElementComputeAesCmac (uint8_t*
The KeyID allows to determine the AES key to
buffer, uint16_t size, KeyIdentifier_t keyID,
use.
uint32_t* cmac)

SecureElementStatus_t Computes cmac and compare with expected

SecureElementVerifyAesCmac (uint8_t* buffer, cmac.
uint16_t size, uint32_t expectedCmac, The KeyID allows to determine the AES key to be
KeyIdentifier_t keyID) used.
SecureElementStatus_t
SecureElementAesEncrypt (uint8_t* buffer, Encrypt a buffer.
uint16_t size, KeyIdentifier_t keyID, uint8_t* The keyID to determine the AES key to be used.
encBuffer)
SecureElementStatus_t Derives and store a key. The key derivation
SecureElementDeriveAndStoreKey (Version_t depends of the LoRaWAN versionKeyID,
version, uint8_t* input, KeyIdentifier_t rootKeyID, rootKeyID allows to identify the root key to
KeyIdentifier_t targetKeyID) perform the derivation.

4.7 Middleware End_Node application function

The interface to the MAC is done through the MAC interface file ‘LoRaMac.h’.

Standard mode
In standard mode, an interface file (see MAC upper layer in Figure 11) is provided to let the
user start without worrying about the LoRa state machine. The interface file is located in
Middlewares\Third_Party\Lora\Core\lora.c.
The interface file implements:
• a set of APIs allowing to access to the LoRaMAC services
• the LoRa certification test cases that are not visible to the application layer

Advanced mode
In this mode, the user accesses directly the MAC layer by including the MAC in the user file.

30/52 UM2073 Rev 8

UM2073 I-CUBE-LRWAN middleware programming guidelines

Operation model
The operation model proposed for this LoRa End_Node (see Figure 13) is based on ‘event-
driven’ paradigms including ‘time-driven’. The behavior of the system LoRa is triggered
either by a timer event or by a radio event plus a guard transition.

UM2073 Rev 8 31/52

51
I-CUBE-LRWAN middleware programming guidelines UM2073

Figure 13. Operation model

ZĞƐĞƚ

+$/,QLWLDOL]DWLRQ
+:,QLWLDOL]DWLRQ
/R5DVWDFN,QLWLDOL]DWLRQ

/R5D-RLQ6WDUW

/R5D,QLW7[(YHQW

3URFHVV(YHQW ',6$%/(B,54

(1$%/(B,54 /RZ3RZHU0RGH

ĞǀĞŶƚ

WƌŽĐĞƐƐǀĞŶƚ
WƌŽĐĞƐƐǀĞŶƚ

zĞƐ EŽ
ZĂĚŝŽŽƌ
ůĂƐƐǀƚ

WƌŽĐĞƐƐddžŽƌZdž
ǀĞŶƚ
WƌŽĐĞƐƐdŝŵĞƌ
ǀĞŶƚ
WƌŽĐĞƐƐůĂƐƐ
ǀĞŶƚ

06Y9

32/52 UM2073 Rev 8

UM2073 I-CUBE-LRWAN middleware programming guidelines

LoRa system state behavior

Figure 14 describes the Lora End_Node System State Behavior.
On reset after system initialization done, the LoRa End_Node system goes into a Start state
defined as ‘Init’.
The LoRa End_Node system does a join network request when using the
“over_the_air_activation (OTAA)” method and goes into a state defined as ‘Sleep’.
When using the “activation by personalization (ABP)”, the network is already joined and
therefore the LoRa End_Node system jumps directly to a state defined as ‘Send’.
From the state defined as ‘Sleep’, if the end-device has joined the network when a
“TimerEvent” occurs, the LoRa End_Node system goes into a temporary state defined as
‘Joined’ before going into the state defined as ‘Send’.
From the state defined as ‘Sleep’, if the end-device has joined the network when an
“OnSendEvent” occurs, the LoRa End_Node system goes into the state defined as ‘Send’.
From the state defined as ‘Send’, the LoRa End_Node system goes back to the state
defined as ‘Sleep’ in order to wait the ‘onSendEvent’ corresponding to the next scheduled
packet to be send.

Figure 14. LoRa state behavior

6OHHS
1:.B-2,1('7LPHU(YHQW
5HVHW
1:.B-2,1('7LPHU(YHQW

-RLQHG ,QLW

7[1H[W7[1H[W3DFNHW 27$$-RLQ7LPHU

7UXHSULQWI 'XW\&\FOH(QDEOH
1:.B-2,1('2Q6HQG(YHQW

-RLQ

6HQG

$%39RLG

06Y9

LoRa Class B system state behavior

Figure 15 describes the LoRa Class B mode End-Node System State behavior.
1. Before doing a request to switch to Class B mode an End-device must be first in a Join
state cf.(Figure 13).
2. The decision to switch from Class A to Class B mode always comes from the
application layer of the End-Device. If the decision comes from the network side, the

UM2073 Rev 8 33/52

51
I-CUBE-LRWAN middleware programming guidelines UM2073

application server must use End-Device's Class A uplink to send back a downlink
frame to the application layer.
On MLME Beacon_Acquisition_req the End-Device LoRa Class B system state goes into a
BEACON_STATE_ACQUISITION.
The LoRa End-Device starts the beacon acquisition. When the MAC layer has received a
beacon in function RxBeacon successfully, the next state is BEACON_STATE_LOCKED.
The LoRa End-Device has received a beacon. Acquisition is no longer pending then the
MAC layer goes in BEACON_STATE_IDLE.
In BEACON_STATE_IDLE, the MAC layer compares the BeaconEventTime with the current
End-Device Time. If the beaconEventTime is less than current End-Device Time the MAC
layer goes in BEACON_STATE_REACQUISITION else it goes in
BEACON_STATE_GUARD. Then it performs a new Beacon Acquisition.
If the MAC layer does not find a beacon, the state machine stays in state
BEACON_STATE_ACQUISITION. This state detects that an acquisition was pending
previously and changes the next state to BEACON_STATE_LOST.
When the MAC layer receives a bad beacon format, it must go to
BEACON_STATE_TIMEOUT. It enlarges window timeouts to increase the chance to receive
the next beacon and goes in BEACON_STATE_REACQUISITION.

Figure 15. LoRa Class B system state behavior

%HDFRQ)RUPDW 2.
0/0(B%HDFRQB$FTXLVLWLRQBUHT

%HDFRQ
7LPH2XW

%HDFRQQRWUHFHLYHG (QODUJH:LQGRZ7PHRXW
%HDFRQ)RUPDW 2.
%HDFRQ
$FTXLVLWLRQ

0/0(B%HDFRQB$FTXLVLWLRQB,QG &XUUHQW7LPH!%HDFRQB/HVVB3HULRG
%HDFRQ
/RFNHG %HDFRQ$FT3HQGLQJ  %HDFRQ
5HDFTXLVLWLRQ

%HDFRQ
0/0(B%HDFRQB$FTXLVLWLRQBFQI /RVW

&XUUHQW7LPH%HDFRQB/HVVB3HULRG

%HDFRQ6HWXS
%HDFRQ
,GOH

%HDFRQ(YHQ7LPH&XUUHQW7LPH
%HDFRQ
*XDUG

%HDFRQ(YHQ7LPH!&XUUHQW7LPH

06Y9

34/52 UM2073 Rev 8

UM2073 I-CUBE-LRWAN middleware programming guidelines

4.7.1 LoRa End_Node initialization

Table 20. LoRa class A initialization function

Function Description

void lora_Init Initialization of the LoRa class A

(LoRaMainCallback_t *callbacks, LoRaParam_t* LoRaParamInit) finite state machine

4.7.2 LoRa End_Node Join request entry point

Table 21. LoRa End_Node Join request entry point

Function Description

Join request to a network either in OTAA mode or

void lora_Join (void) ABP mode (The Join mode should be defined at
compile time).

4.7.3 LoRa End-Node start Tx

Table 22. LoRa End-Node start Tx

Function Description

Start the OnTxTimerEvent occurence if

void loraStartTx (TxEventType_t EventType) EventType param is equal to TX_ON_TIMER.
User is free to implement its own code here.

4.7.4 Request End-Node Join Status

Table 23. End-Node Join Status

Function Description

Check the End-Node activation type

(ACTIVATION_TYPE_NONE,
LoraFlagStatus LORA_JoinStatus (void)
ACTIVATION_TYPE_ABP,
ACTIVATION_TYPE_OTAA).

4.7.5 Send an uplink frame

Table 24. Send an uplink frame

Function Description

Send an uplink frame. This frame can be

bool LORA_send (lora_AppData_t*
either an unconfirmed empty frame, or an
AppData,LoraConfirm_t IsTxConfirmed)
unconfirmed/confirmed payload frame.

UM2073 Rev 8 35/52

51
I-CUBE-LRWAN middleware programming guidelines UM2073

4.7.6 Request the current network time

Table 25. Current network time

Function Description

End-device requests from the network the

current network time (useful to accelerate
the beacon discovery in Class B mode)
LoraErrorStatus LORA_DeviceTimeReq (void)
Note: To be used in place of
BeaconTimeReq in LoRaWAN version >=
1.0.3

4.7.7 Request the next beacon timing

Table 26. Next beacon timing
Function Description

End-device requests from the network the

next beacon timing (useful to accelerate the
LoraErrorStatus LORA_BeaconTimeReq (void) beacon discovery in Class B mode)
Note: command deprecated in the
LoRaWAN V1.0.3

4.7.8 Switch Class Request

Table 27. Switch Class Request

Function Description

LoraErrorStatus LORA_RequestClass Requests the End-device to switch from

(DeviceClass_t newClass) current to new Class (A, B or C).

4.7.9 Get End-device current class

Table 28. Get End-Device current Class

Function Description

void LORA_GetCurrentClass (DeviceClass_t Requests the current running Class (A, B or

*currentClass) C).

4.7.10 Request Beacon Acquisition

Table 29. Request Beacon Acquisition

Function Description

LoraErrorStatus LORA_BeaconReq (void) Request the beacon slot acquisition.

36/52 UM2073 Rev 8

UM2073 I-CUBE-LRWAN middleware programming guidelines

4.7.11 Send unicast ping slot info periodicity

Table 30. Unicast ping slot periodicity

Function Description

Transmit to the server the unicast ping slot

LoraErrorStatus LORA_PingSlotReq (void)
info periodicity.

4.8 LIB End_Node application callbacks

4.8.1 Current battery level

Table 31 presents the current battery level function.

Table 31. Current battery level function

Function Description

uint8_t HW_GetBatteryLevel (void) Get the battery level.

4.8.2 Current temperature level

Table 32. Current Temperature function

Function Description

Get the current temperature (degree Celsius) of

uint16_t HW_GetTemperatureLevel (void)
the chipset in q7.8 format.

4.8.3 Board unique ID

Table 33 presents the board unique ID function.

Table 33. Board unique ID function

Function Description

void HW_GetUniqueId (uint8_t *id) Get a unique Identifier.

4.8.4 Board random seed

Table 34 presents the board random seed function.

Table 34. Board random seed function

Function Description

uint32_t HW_GetRandomSeed (void) Get a random seed value.

4.8.5 Make Rx frame

Table 35 presents the make Rx frame function.

UM2073 Rev 8 37/52

51
I-CUBE-LRWAN middleware programming guidelines UM2073

Table 35. Make Rx frame

Function Description

To process the incoming frame application.

void LoraRxData (lora_AppData_t *AppData)
The user is free to implement his own code here.

4.8.6 Request Class mode switching

Table 36. LoRa has Joined function

Function Description

Notifies the application that the end-node has

void LORA_HasJoined (void)
joined.

4.8.7 End_Node Class mode change confirmation

Table 37. End_Node Class mode change confirmation function

Function Description

Notifies the application that the end-node has

void LORA_ConfirmClass (DeviceClass_t Class)
changed device class.

4.8.8 Send a dummy uplink frame

Table 38. Send a dummy uplink frame

Function Description

void LORA_TxNeeded (void) Requests application to send a frame.

38/52 UM2073 Rev 8

UM2073 Example description

5 Example description

5.1 Single MCU end-device hardware description

The Application layer, the Mac Layer and the PHY driver are implemented on one MCU. The
End_Node application is implementing this hardware solution (see Section 5.4)
The I-CUBE-LRWAN runs on several platforms such as:
• STM32 Nucleo platform stacked with a LoRa radio expansion board
• B-L072Z-LRWAN1 Discovery board (no LoRa expansion board required)
Optionally a ST X-NUCLEO-IKS01A1 sensor expansion board can be added on Nucleo and
Discovery boards. The Nucleo-based supported hardware is presented in Table 39.

Table 39. Nucleo-based supported hardware

LoRa radio expansion
SX1276MB1MAS SX1276MB1LAS SX1272MB2DAS
board / Nucleo board

NUCLEO-L053R8 Supported Supported Supported

Supported
NUCLEO-L073RZ Supported Supported (P-NUCLEO-
LRWAN1(1))
NUCLEO-L152RE Supported Supported Supported
NUCLEO-L476RG Supported Supported Supported
1. This particular configuration is commercially available as a kit P-NUCLEO-LRWAN1.

The I-CUBE-LRWAN Expansion Package can easily be tailored to any other supported
device and development board.
The main characteristics of the LoRa radio expansion board are described in Table 40.

Table 40. LoRa radio expansion boards characteristics

Board Characteristics

SX1276MB1MAS 868 MHz (HF) at 14 dBm and 433 MHz (LF) at 14 dBm
SX1276MB1LAS 915 MHz (HF) at 20 dBm and 433 MHz (LF) at 14 dBm
SX1272MB2DAS 915 MHz and 868 MHz at 14 dBm
SX1261DVK1BAS E406V03A sx1261, 14 dBm, 868 MHz, XTAL
SX1262DVK1CAS E428V03A sx1262, 22 dBm, 915 MHz, XTAL
SX1262DVK1DAS E449V01A sx1262, 22 dBm, 860-930 MHz, TCXO

The radio interface is described below:

• The radio registers are accessed through the SPI.
• The DIO mapping is radio dependent, see Chapter 3.4.4.
• One GPIO from the MCU is used to reset the radio.
• One MCU pin is used to control the antenna switch to set it either in Rx mode or in Tx
mode.

UM2073 Rev 8 39/52

51
Example description UM2073

The hardware mapping is described in the hardware configuration files at

Projects\<platform>\Applications\LoRa\<App_Type>\Core\inc.
The <platform> can be STM32L053R8-Nucleo, STM32L073RZ-Nucleo, STM32L152RE-
Nucleo, STM32L476RG-Nucleo, B-L072Z-LRWAN1 (Murata modem device), the <Target>
can be STML0xx and the <App_Type> can be either AT_Master, End_Node, PingPong,
AT_Slave.

Interrupts
Table 41 shows the interrupt priorities level applicable for the Cortex system processor
exception and for the STM32L0 Series LoRa application-specific interrupt (IRQ).

Table 41. STM32L0xx IRQ priorities

Interrupt name Preempt priority Sub-priority

RTC 0 NA
EXTI2_3 0 NA
EXTI4_15 0 NA

5.2 Split end-device hardware description (two-MCUs solution)

The Application layer, the Mac Layer, and the PHY driver are separated. The LoRa
End_Node is composed of a LoRa modem and a host controller. The LoRa modem is
running the Lora stack (Mac Layer and the Phy Layer) and is controlled by a Lora host
implementing the application layer.
The AT_Master application implementing the Lora host on a NUCLEO board, is compatible
with the AT_Slave application (see Section 5.6). The AT_Slave application demonstrates a
modem on the CMWX1ZZABZ-091 LoRa module (Murata). The AT_Master application is
also compatible with the I-NUCLEO-LRWAN1 expansion board featuring the
WM-SG-SM-42 LPWAN module from USI and with the LRWAN_NS1 expansion board
featuring the RiSiNGHF® modem RHF0M003 available in P-NUCLEO-LRWAN3 (see
Section 5.7).
This split solution allows to design the application layer without any constraint linked to the
real time requirement of LoRaWAN stack.

Figure 16. Concept for split end-device solution

18&/(2/5 /RUDŠH[SDQVLRQERDUG
,18&/(2/5:$1

$7B0$67(5 /RUDŠ0RGHP
DSSOLFDWLRQ $7FRPPDQG
/RUD:DQ 6WDFN
70

LQFOXGHGLQ RYHU8$57
5DGLR
,&8%(/5:$1

06Y9

40/52 UM2073 Rev 8

UM2073 Example description

The interface between the LoRa modem and the LoRa host is a UART running AT
commands.

5.3 Package description

When the user unzips the I-CUBE-LRWAN, the package presents the structure shown in
Figure 17.

UM2073 Rev 8 41/52

51
Example description UM2073

Figure 17. I-CUBE-LRWAN structure

06Y9

The I-CUBE-LRWAN package contains four applications: End_Node, PingPong, AT_Slave

and AT_Master. For each application, three toolchains are available: MDK-ARM, IAR and
SW4STM32.

42/52 UM2073 Rev 8

UM2073 Example description

5.4 End_Node application

This application reads the temperature, humidity and atmospheric pressure from the
sensors through the I2C. The MCU measures the supplied voltage through VREFLNT in order
to calculate the battery level. These four data (temperature, humidity, atmospheric pressure
and battery level) are sent periodically to the LoRa network using the LoRa radio in class A
at 868 MHz.
In order to launch the LoRa End_Node project, the user should go to
\Projects\<target>\Applications\LoRa\End_Node and choose his favorite toolchain folder (in
the IDE environment). The user selects then the LoRa project from the proper target board.

5.4.1 Activation methods and keys

There are two ways to activate a device on the network, either by OTAA or by ABP.
The file
\Projects\<target>\Applications\LoRa\End_Node\LoRaWAN\App\inc\Commissioning.h
gathers all the data related to the device activation. The chosen method, along with the
commissioning data, are printed on the virtual port and visible on a terminal.

5.4.2 Debug switch

The user must go to \Projects\Multi\Applications\LoRa\End_Node\inc\hw_conf.h to enable
the debug mode or/and the trace mode by commenting out
#define DEBUG
The debug mode enables the DBG_GPIO_SET and the DBG_GPIO_RST macros as well
as the debugger mode even when the MCU goes in low-power.
For trace mode, three levels of trace are proposed, VERBOSE_LEVEL_0 (traces are
disabled), VERBOSE_LEVEL_1 (enabled for functional traces) and VERBOSE_LEVEL_2
(enabled for Debug traces).
The user must go to
\Projects\<platform>\Applications\LoRa\<App>\LoRaWAN\App\inc\utilities_conf.h to set the
select trace level.
Note: In order to enable a true low-power, “#define DEBUG” mentioned above must be
commented out.

5.4.3 Sensor switch

When no sensor expansion board is plugged on the set-up, the #define
SENSOR_ENBALED must be commented out on the
\Projects\<target>\Applications\LoRa\End_Node\LoRaWAN\App\inc.
Table 42 provides a summary of the main options for the application configuration.

UM2073 Rev 8 43/52

51
Example description UM2073

Table 42. Switch options for the application's configuration

Project Switch option Definition Location

Application uses over-the- air

OVER_THE_AIR_ACTIVATION Commissioning.h
activation procedure.
Static or dynamic end- device
STATIC_DEVICE_EUI Commissioning.h
identification
Compiles the relevant code for
LORAMAC_CLASSB_ENABLED Compiler option setting
Class B mode.
Includes either
USE_DEVICE_TIMING "LORA_DeviceTimeReq ()" or lora.c
"LORA_BeaconTimeReq (void)
Static or dynamic end- device
STATIC_DEVICE_ADDRESS Commissioning.h
address
LoRa
REGION_EU868
stack
REGION_EU433
REGION_US915
REGION_AS923
REGION_AU915
Enable the band selection Compiler option setting
REGION_CN470
REGION_CN779
REGION_IN865
REGION_RU864
REGION_KR920
DEBUG Enable ‘Led on/off’ hw_conf.h
Sensor VERBOSE_LEVEL Enable the trace level utilities_conf.h
SENSOR_ENABLED Enable the call to the sensor board hw_conf.h

Note: The maximum payload length allowed depends on both the region and the selected data
rate, so the payload format must be carefully designed according to these parameters.

5.5 PingPong application description

This application is a simple Rx/Tx RF link between two LoRa end-devices. By default, each
LoRa end-device starts as a master and transmits a ‘Ping’ message and wait for an answer.
The first LoRa end-device receiving a ‘Ping’ message becomes a slave and answers the
master with a ‘Pong’ message. The PingPong is then started.
In order to launch the PingPong project, the user must go to the
\Projects\<platform>\Applications\LoRa\PingPong folder and follow the same procedure as
for the LoRa End_Node project to launch the preferred toolchain.

44/52 UM2073 Rev 8

UM2073 Example description

Hardware and software set-up environment

To setup the STM32LXxx-NUCLEO, connect the NUCLEO (or the B-L072Z-LRWAN1)
board to the computer with a USB cable type A to mini B to the ST-LINK connector (CN1).
Ensure that the CN2 ST-LINK connector jumpers are fitted. See Figure 18 for a
representation of the PingPong setup.

Figure 18. PingPong setup

/R5DHQGGHYLFH /R5DHQGGHYLFH
 
&RP3RUW &RP3RUW
67018&/(25DGLR 67018&/(25DGLR
H[SDQVLRQERDUG H[SDQVLRQERDUG

06Y9

5.6 AT_Slave application description

The purpose of this example is to implement a LoRa modem controlled though AT
command interface over UART by an external host.
The external host can be a host-microcontroller embedding the application and the AT driver
or simply a computer executing a terminal.
This application is targeting the B-L072Z-LRWAN1 Discovery board embedding the
CMWX1ZZABZ-091 LoRa module. This application uses the Cube Low Layer drivers APIs
targeting the STM32L072CZ to optimize the code size.
The AT_Slave example implements the Lora stack driving the built-in LoRa radio. The stack
is controlled through AT command interface over UART. The modem is always in Stop mode
unless it processes an AT command from the external host.
In order to launch the AT_Slave project, the user must go to the
Projects\B-L072Z-LRWAN1\Applications\LoRa\AT_Slave folder and follow the same
procedure as for the LoRa End_Node project to launch the preferred toolchain.
For more details, refer to the application note AN4967 which gives the list of AT commands
and their description.

5.7 AT_Master application description

The purpose of this application is to read sensor data and to send them to a Lora Network
through an external Lora Modem. The AT_Master application implements a complete set of
AT commands to drive the LoRa stack which is embedded in the external LoRA modem.
External LoRA modem is targeting either the B-L072Z-LRWAN1 Discovery board or the I-
NUCLEO-LRWAN1 board (based on the WM-SG-SM-42 USI module) or the LRWAN-NS1
expansion board featuring the RiSiNGHF® modem available in P-NUCLEO-LRWAN3.
This application uses the STM32Cube™ HAL drivers APIs targeting the STM32L0 Series.

UM2073 Rev 8 45/52

51
Example description UM2073

For more details, refer to the application note AN4967 which gives the list of AT commands
and their description.

BSP programming guidelines

Table 43 gives a description of the BSP (board support package) driver APIs to interface
with the external LoRa module.
Table 43. BSP programming guidelines
Function Description

ATEerror_t Modem_IO_Init (void) Modem initialization

void Modem_IO_DeInit (void) Modem deinitialization
ATEerror_t Modem_AT_Cmd (ATGroup_t,
Modem IO commands
at_group, ATCmd_t Cmd, void *pdata)

Note: The NUCLEO board communicates with expansion board via UART (PA2,PA3). The
following modifications must be applied: (cf. chapter 5.8 of UM1724).
• SB62 and SB63 should be closed
• SB13 and SB14 should be opened to disconnect STM32 UART from STLINK

46/52 UM2073 Rev 8

UM2073 System performances

6 System performances

6.1 Memory footprints

The values in Table 44 have been measured for the following configuration of the Keil
compiler (ARM compiler 5.05):
• Optimization: optimized for size level 3
• Debug option: off
• Trace option: off
• Target: P-NUCLEO-LRWAN1 (STM32L073+ SX1272MB2DAS)

Table 44. Memory footprint values for End_Node application

Project Flash (bytes) RAM (bytes) Description

Application layer 4336 456 Includes all microlib.

LoRa stack 29926 3486 Includes MAC + RF driver.
Hardware abstraction level 10362 1536 -
Includes services like
Utilities 2474 464 system, timeserver, vcom
and queue.
Memory footprint for the
Total application 52468 6362
overall application

6.2 Real-time constraints

The LoRa RF asynchronous protocol implies to follow a strict TX/Rx timing recommendation
(see Figure 19 for a Tx/Rx diagram example). The SX1276MB1MAS expansion board has
been optimized for user-transparent low-lock time and fast auto-calibrating operation. The
LoRa Expansion Package design integrates the transmitter startup time and the receiver
startup time constraints.

UM2073 Rev 8 47/52

51
System performances UM2073

Figure 19. Rx/Tx time diagram

6WDUW7[ 7LPHU6WDUW 5[:LQGRZ7LPHU 6WDUW5[

0&8

5)$FWLYLW\ ',2 7[21 5[21

',2
7['RQH 5['RQH
06Y9

Rx window channel start

The Rx window opens the RECEIVE_DELAY1 for 1second (+/- 20 microseconds) or the
JOIN_ACCEPT_DELAY1 for 5 seconds (+/- 20 microseconds) after the end of the uplink
modulation.
The current scheduling interrupt-level priority must be respected. In other words, all the new
user-interrupts must have an interrupt priority > DI0#n interrupt (see Table 41) in order to
avoid stalling the received startup time.

6.3 Power consumption

The power-consumption measurement has been established for the Nucleo boards
associated to the SX1276MB1MAS shield.

Measurements setup:
• No DEBUG
• No TRACE
• No SENSOR_ENABLED

Measurements results:
• Typical consumption in stop mode: 1.3 µA
• Typical consumption in run mode: 8.0 mA

Measurements figures:
• Instantaneous consumption over 30 seconds
The Figure 20 shows an example of the current consumption against time on a
microcontroller of the STM32L0 Series.

48/52 UM2073 Rev 8

UM2073 System performances

Figure 20. STM32L0 current consumption against time

UM2073 Rev 8 49/52

51
Revision history UM2073

7 Revision history

Table 45. Document revision history

Date Revision Changes

27-Jun-2016 1 Initial release.

Updated:
– Introduction
– Section 2.1: Overview
10-Nov-2016 2
– Section 3.2: Features
– Section 5: Example description
– Section 6: System performances
Updated:
– Introduction with reference to the CMWX1ZZABZ-xxx
LoRa module (Murata).
– Section 5.1: Hardware description: 3rd hardware
4-Jan-2017 3 configuration file added.
– Section 5.2: Package description: AT_Slave
application added.
Added:
– Section 5.5: AT_Slave application description
Updated:
– Introduction with I-NUCLEO-LRWAN1 LoRa
expansion board.
– Figure 10: Project files structure
– Section 5.1: Single MCU end-device hardware
description
– Figure 15: I-CUBE-LRWAN structure
– Section 5.4: End_Node application
– Section Table 27.: Switch options for the application's
21-Feb-2017 4 configuration
– Section 5.5: PingPong application description
– Section 5.6: AT_Slave application description
– Table 29: Memory footprint values for End_Node
application
Added:
– Section 5.2: Split end-device hardware description
(two-MCUs solution)
– Section 5.7Section 5.7: AT_Master application
description.
Added:
– Note to Section 5.4: End_Node application on
maximum payload length allowed
18-Jul-2017 5
– Note to Section 5.7: AT_Master application
description on the NUCLEO board communication
with expansion board via UART

50/52 UM2073 Rev 8

UM2073 Revision history

Table 45. Document revision history (continued)

Date Revision Changes

Added:
– New modem reference: expansion board featuring the
RiSiNGHF® modem RHF0M003
14-Dec-2017 6 Updated:
– New architecture design (LoRa FSM removed)
– Figure 10: Project files structure
– Figure 13: Operation model
Added:
– New expansion boards
4-Jul-2018 7 – introduction of LoRaWAN Class B mode
Updated:
– Figure 10 to Figure 17, Table 4, Table 10 to Table 45
Removed:
13-Dec-2018 8 – Class B restriction regarding AT commands in
Section 5.6: AT_Slave application description

UM2073 Rev 8 51/52

51
 UM2073

IMPORTANT NOTICE – PLEASE READ CAREFULLY

STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and
improvements to ST products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on
ST products before placing orders. ST products are sold pursuant to ST’s terms and conditions of sale in place at the time of order
acknowledgement.

Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or
the design of Purchasers’ products.

No license, express or implied, to any intellectual property right is granted by ST herein.

Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.

ST and the ST logo are trademarks of ST. All other product or service names are the property of their respective owners.

Information in this document supersedes and replaces information previously supplied in any prior versions of this document.

© 2018 STMicroelectronics – All rights reserved

52/52 UM2073 Rev 8