ST X-CUBE-CELLULAR User manual

October 2019 UM2426 Rev 5 1/56
1
UM2426
User manual
X-CUBE-CELLULAR cellular connectivity Expansion Package for
STM32Cube
Introduction
This user manual describes the content and use of the X-CUBE-CELLULAR cellular
connectivity Expansion Package for STM32Cube.
The X-CUBE-CELLULAR Expansion Package enables connectivity over cellular networks.
The network access technology depends on the cellular modem used: 2G, 3G, LTE Cat M1,
or NB-IoT (also known as NB1). The cellular connectivity framework exposes standard APIs
for easy integration of any application interacting with a remote host using the TCP- or
UDP-over-IP protocol.
The X-CUBE-CELLULAR Expansion Package for STM32Cube provides an application
example that connects and subscribes to cloud services using the HTTP protocol in order to
report data from the device to the server, as well as to receive commands from the remote
server. Two additional applications are provided as examples: ECHO (exchanges data with
a remote server using TCP or UDP), and PING (tests the access to a remote machine).
X-CUBE-CELLULAR is available for the following hardware (refer to Chapter 1 for details):
•P-L496G-CELL01 cellular-to-cloud pack with an STM32L496AG-based Discovery host
board and an add-on board based on Quectel UG96 modem (2G / 3G)
•P-L496G-CELL02 cellular-to-cloud pack with an STM32L496AG-based Discovery host
board and an add-on board based on Quectel BG96 modem (LTE Cat M / NB-IoT / 2G
fallback)
•B-L475E-IOT01A IoT Discovery board and add-on board with Quectel BG96 modem
•B-L475E-IOT01A IoT Discovery board and add-on board with Sequans®GM01Q modem
•32L496GDISCOVERY Discovery board and modem board based on Sequans®GM01Q,
or Quectel UG96 or BG96 modem
The main features of the X-CUBE-CELLULAR Expansion Package are:
•Ready-to-run firmware examples using the 2G, 3G, LTE Cat M1, or NB-IoT protocols
•Configuration of the HTTP connection to the IoT platform and cellular connectivity
•Cellular connection
•Reporting of such values as temperature, humidity, and pressure
•Network radio level reporting
•Testing of access to a remote machine
•Connection and data exchange using the TCP or UDP socket protocols
www.st.com

Contents UM2426
2/56 UM2426 Rev 5
Contents
1 General information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1 Terms and definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2 Important note regarding the security . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3 Service connectivity description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4 Package description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1 General description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
4.2 Modem socket versus LwIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
4.3 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
4.3.1 Architecture concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.3.2 Static architecture view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.3.3 Dynamic architecture view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.4 X-CUBE-CELLULAR Expansion Package description . . . . . . . . . . . . . . . 25
4.5 Folder structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.6 Reset push-button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.7 Real-time clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5 Cellular connectivity examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.1 Real network or simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.2 Connection overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.3 PING example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.4 ECHO example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.5 GroveStreams (HTTP) access example . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6 Hardware and software environment setup . . . . . . . . . . . . . . . . . . . . . 33
7 Interacting with the host board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.1 Debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.2 Boot menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.3 Console command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

UM2426 Rev 5 3/56
UM2426 Contents
3
8 How to customize the software? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
8.1 First customization level: user customization . . . . . . . . . . . . . . . . . . . . . . 40
8.2 Second customization level: advanced user customization . . . . . . . . . . . 40
8.2.1 Adding/removing an application in firmware . . . . . . . . . . . . . . . . . . . . . 40
8.2.2 IP stack on MCU side or on modem side . . . . . . . . . . . . . . . . . . . . . . . 41
8.2.3 Different kinds of available traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
8.2.4 How to configure traces? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
8.3 Third customization level: developer customization . . . . . . . . . . . . . . . . . 43
8.3.1 Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
8.3.2 Initialization of software components . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
8.3.3 Software customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
8.3.4 Firmware adaptation to a new HW configuration . . . . . . . . . . . . . . . . . . 44
8.3.5 Adding a new component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
8.4 Data cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
8.4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
8.4.2 Data Cache API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
8.4.3 Main Data Cache entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
8.5 Thread stack consumption monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Appendix A Support material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
A.1 How to configure a GroveStreams account?. . . . . . . . . . . . . . . . . . . . . . . 50
A.2 How to activate the soldered SIM card? . . . . . . . . . . . . . . . . . . . . . . . . . . 52
A.3 How to select Quectel BG96 modem configuration bands? . . . . . . . . . . . 53
A.4 How to configure the Network library API? . . . . . . . . . . . . . . . . . . . . . . . . 53
Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

List of tables UM2426
4/56 UM2426 Rev 5
List of tables
Table 1. List of acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Table 2. Compilation variables for applications in firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Table 3. Compilation variable for IP stack selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Table 4. New thread registration example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Table 5. Number of project threads setting example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Table 6. Code for thread stack consumption monitoring example . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Table 7. Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

UM2426 Rev 5 5/56
UM2426 List of figures
5
List of figures
Figure 1. Cellular IoT connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Figure 2. Architecture concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Figure 3. Static architecture view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Figure 4. Dynamic architecture - X-CUBE-CELLULAR API - Platform initialization and start . . . . . . 18
Figure 5. Dynamic architecture - X-CUBE-CELLULAR API - Up to PDN creation. . . . . . . . . . . . . . . 19
Figure 6. Dynamic architecture - X-CUBE-CELLULAR API - Socket. . . . . . . . . . . . . . . . . . . . . . . . . 20
Figure 7. Dynamic architecture - Network library API - Initialization . . . . . . . . . . . . . . . . . . . . . . . . . 21
Figure 8. Dynamic architecture - Network library API - Connection. . . . . . . . . . . . . . . . . . . . . . . . . . 22
Figure 9. Dynamic architecture - Network library API - Disconnection . . . . . . . . . . . . . . . . . . . . . . . 23
Figure 10. Dynamic architecture - Network library API - Socket service . . . . . . . . . . . . . . . . . . . . . . . 24
Figure 11. X-CUBE-CELLULAR folder structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Figure 12. GroveStreams connection overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Figure 13. GroveStreams web interface, component view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Figure 14. GroveStreams web interface, dashboard view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Figure 15. Hardware setup (P-L496G-CELL02 example) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Figure 16. Hardware view (P-L496G-CELL02 example) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Figure 17. Hardware view (“Discovery IoT node cellular with BG96” set example) . . . . . . . . . . . . . . . 36
Figure 18. Serial port settings to interact with the host board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Figure 19. Serial port settings to interact with the host board (new-line) . . . . . . . . . . . . . . . . . . . . . . . 38
Figure 20. GroveStreams organization creation acceptance screen . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Figure 21. GroveStreams organization creation screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Figure 22. GroveStreams organization access screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Figure 23. GroveStreams organization administration menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Figure 24. GroveStreams API key selection screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Figure 25. GroveStreams API key display screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

General information UM2426
6/56 UM2426 Rev 5
1 General information
This user manual describes the X-CUBE-CELLULAR Expansion Package and its use. It
explains neither the cellular networks nor the cellular protocol stacks, the descriptions of
which being available on the Internet.
The main features of the X-CUBE-CELLULAR Expansion Package are:
•Ready-to-run firmware examples using the 2G, 3G, LTE Cat M1, or NB-IoT protocols to
support quick evaluation and development of IoT cloud applications
•Menu and command line through Virtual COM UART over USB ST-LINK to configure
the cellular connectivity parameters (technology selection, bands, APN, and others),
and connection to the GroveStreams cloud IoT platform (HTTP)
•Cellular connection
•Reporting of such values as temperature, humidity, and pressure. The values are real if
the MEMS add-on board (X-NUCLEO-IKS01A2) is connected, otherwise they are
simulated. The sensors in the “Discovery IoT node cellular” set are always used
•Network radio level reporting
•PING application to test the access to a remote machine
•ECHO application to provide an example of connection and data exchanges using the
TCP or UDP (connected or not-connected mode) socket protocols
X-CUBE-CELLULAR is available for the following hardware:
•both the P-L496G-CELL01 and P-L496G-CELL02 cellular-to-cloud packs. Each pack is
composed of an STM32L496AG-based Discovery host board connected to an add-on
cellular modem through the STMod+ connector:
– The add-on board of P-L496G-CELL01 is equipped with the UG96 modem
(2G / 3G) from Quectel
– The add-on board of P-L496G-CELL02 is equipped with the BG96 modem (LTE
Cat M / NB-IoT / 2G fallback) from Quectel
•the “Discovery IoT node cellular” set, which is a combination of the B-L475E-IOT01A
IoT Discovery board, X-NUCLEO-STMODA1 ARDUINO®/ STMod+ adapter, and:
– either STMicroelectronics MB1329 modem board with Quectel BG96 modem
– or Sequans®GM01Q-STMOD modem board with the GM01Q modem (referenced
as B-CELL-GM01Q in STMicroelectronics)
•32L496GDISCOVERY Discovery board connected to one of these modem boards:
– Sequans®GM01Q-STMOD with the GM01Q modem
– Add-on board with the Quectel UG96 or BG96 modem
Refer to the X-CUBE-CELLULAR cellular connectivity Expansion Package porting on other
hardware application note (AN5249) for adaptation to other hardware such as the
“Discovery IoT node cellular” set.
1.1 Terms and definitions
Table 1 presents the definition of acronyms that are relevant for a better understanding of
this document.

UM2426 Rev 5 7/56
UM2426 General information
Table 1. List of acronyms
Term Definition
API Application programming interface
APN Access point name
BSD Berkeley software distribution
BSP Board support package
C2C Cellular to cloud
CID Context ID (context identifier of a cellular connection)
COM Cellular communication
DC Data Cache
eUICC Embedded UICC (UICC with remote profile feature)
eSIM Embedded SIM
FEEPROM Represents the embedded Flash memory of the STM32 MCU
HAL Hardware abstraction layer
HTTP Hypertext transfer protocol
ICMP Internet control message protocol
IDE Integrated development environment
IF Interface
IoT Internet of things (refer to [4])
IPC Inter-processor channel
ITM Instruction trace module
LED Light-emitting diode
M2M Machine to machine
NAT Network address translation
NFMC Network-friendly management configuration (refer to [4])
NIFMAN Network IF manager
MNO Mobile network operator
MVNO Mobile virtual network operator
PDN Packet data network
PDU Protocol data unit
PLMN Public land mobile network
PPP Point-to-point protocol
PPPoSIF PPP over serial IF
PS Packet switching
RAM Random-access memory
ROM Read-only memory
RSSI Received-signal strength indication

General information UM2426
8/56 UM2426 Rev 5
The X-CUBE-CELLULAR Expansion Package runs on STM32L4 32-bit microcontrollers
based on the Arm®(a) Cortex®-M4 processor.
1.2 References
1. Development guidelines for STM32Cube Expansion Packages user manual (UM2285)
2. Development checklist for STM32Cube Expansion Packages user manual (UM2312)
3. Getting started with STM32CubeL4 for STM32L4 Series and STM32L4+ Series user
manual (UM1860)
4. IoT Device Connection Efficiency Guidelines (TSG.34/TS.34) from the GSM
Association
5. X-CUBE-CELLULAR cellular connectivity Expansion Package porting on other
hardware application note (AN5249)
RTC Real-time clock
SMS Short-message service
TCP Transmission control protocol
UDP User datagram protocol
UICC Universal integrated circuit card (also referred to as SIM card)
URC Unsolicited result code
a. Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.
Table 1. List of acronyms (continued)
Term Definition

UM2426 Rev 5 9/56
UM2426 Important note regarding the security
2 Important note regarding the security
Caution: Application developers must take care of security aspects, and put mechanisms in place to
protect the tokens and secrets used for the connections.
The application example provided in the X-CUBE-CELLULAR Expansion Package does not
implement such protection mechanisms. It only presents a basic implementation for an easy
understanding of the stack interface.
Warning: Use the HW only with the antenna connected. With no
antenna connected, there is a risk of damage to the modem
because of the power reflected from the antenna connector
to the modem RF output.

Service connectivity description UM2426
10/56 UM2426 Rev 5
3 Service connectivity description
The X-CUBE-CELLULAR Expansion Package offers out-of-the-box connectivity for
communication to the Internet. It implements a complete middleware- and application-level
stack in C language, which allows the connection of the C2C kit to a web site.
The first connectivity example provided connects to the GroveStreams web site. In this
example, the board reports notifications to the GroveStreams web browser.
The second example provided implements the ping network-testing feature.
The third example provided is the ECHO application. The application connects or not to the
remote server (according to the socket protocol used), sends a buffer, and expects in return
the same buffer as the response.
Figure 1 presents the cellular IoT connectivity handled by the X-CUBE-CELLULAR
Expansion Package.
Figure 1. Cellular IoT connectivity
The P-L496G-CELL01 and P-L496G-CELL02 are used to represent all the compliant hardware.
The cellular-to-cloud kit comprises an STM32-based main board, a cellular add-on modem
board, and a prepaid SIM, which enables the registration to a cellular PLMN. The global
roaming provided by the SIM provider allows device attachment from any country. The SIM
only offers IP connectivity (meaning that SMS is not supported). The volume of data
available in the prepaid offer depends on where it is used.
A private IP address is allocated to the device by the MNO or MVNO. Any client application
running on device using TCP transaction request/response can reach a server located in
the Internet by means of IP address translation (NAT) on the MNO/MVNO router.
06Y9
3/*&(//
3/*&(//
H1RGH%
%76
%6&
*33
FRUH
QHWZRUN
1$7
931 ,QWHUQHW
*URYH6WUHDPV
+773
VHUYHU
$FFHVVQHWZRUNLQWHUIDFH ,QWHUQHWLQWHUIDFH
&XVWRPHUSUHPLVHV
HTXLSPHQW 2SHUDWRUHTXLSPHQW
,QWHUQHW
GRPDLQ
VHUYHUV
6HUYLFHSURYLGHU
HTXLSPHQW
&ORXGSURYLGHU
LQWHUIDFH