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.
06Y9
3/*&(//
3/*&(//
H1RGH%
%76
%6&
*33
FRUH
QHWZRUN
1$7
931 ,QWHUQHW
*URYH6WUHDPV
+773
VHUYHU
$FFHVVQHWZRUNLQWHUIDFH ,QWHUQHWLQWHUIDFH
&XVWRPHUSUHPLVHV
HTXLSPHQW 2SHUDWRUHTXLSPHQW
,QWHUQHW
GRPDLQ
VHUYHUV
6HUYLFHSURYLGHU
HTXLSPHQW
&ORXGSURYLGHU
LQWHUIDFH

UM2426 Rev 5 11/56
UM2426 Package description
4 Package description
This chapter details the content and use of the X-CUBE-CELLULAR Expansion Package.
4.1 General description
The X-CUBE-CELLULAR Expansion Package only provides software components running
on the host STM32 MCU. Cellular modem firmware is not in the scope of this document.
The following integrated development environments are supported:
•STMicroelectronics integrated development environment for STM32 products
(STM32CubeIDE)
•IAR Embedded Workbench®for Arm® (EWARM)
•Keil®Microcontroller Development Kit (MDK-ARM)
Note: Refer to the release note available in the root folder of the delivery package for information
about the IDE versions supported.
IAR™ binaries are provided in the package.
4.2 Modem socket versus LwIP
Either modem socket or LwIP can be used for the IP stack:
•Modem socket: the IP stack runs in modem FW
•LwIP: the LwIP stack runs on the STM32 side
This option is selected in software through a #define used during the compilation process.
The generated FW is either for modem socket or for LwIP use. It is not possible to further
change this setting through the boot menu.
Note: If the modem socket is used, the software described in this user manual limits data plane
support to TCP or UDP IPv4 Client application only. TCP or UDP server modes and IPv6
are not supported.
If LwIP is used, TCP and UDP (both server and client) are fully supported.
If LwIP is selected, the communication between host and modem is done through the PPP
layer. There is a PPP client on the host side, and a PPP server on the modem side.
PPPoSIF adapts the LwIP stack to a serial IF, while LwIP usually uses Ethernet interfacing.
Note: The LwIP mode is not supported for the “Discovery IoT node cellular” set.
4.3 Architecture
X-CUBE-CELLULAR runs on STM32 boards and allows sending or receiving IP packets to
or from the Internet via an add-on cellular module.
Note: Some parts of X-CUBE-CELLULAR can be used in a bare OS environment. The complete
stack only runs with FreeRTOS™.

Package description UM2426
12/56 UM2426 Rev 5
The package is split into the following components:
•STM32L4 Series HAL
•CMSIS/FreeRTOS™
•Network
•LwIP
•AT Service
•Cellular Service
•Cellular_Mngt
•Com
•Data_Cache
•IPC
•NIFMAN
•Common
4.3.1 Architecture concept
This section provides a high-level view of the software architecture supporting cellular
connectivity, which is illustrated in Figure 2.
Figure 2. Architecture concept
06Y9
,3&IUDPHZRUN
'DWDSODQHLQWHUIDFH &RQWUROSODQHLQWHUIDFH
$7&RUHWDVN
26&HOOXODUOLEUDU\&HOOXODU6HUYLFH$7IUDPHZRUN
&HOOXODU6HUYLFHWDVN333R6,)WDVN
/Z,3WDVN
&RPOLEUDU\
$SSOLFDWLRQ
1,)0$1
WDVN
&HOOXODUB0QJWOLEUDU\ 'DWDB&DFKHOLEUDU\
1HWZRUNOLEUDU\

UM2426 Rev 5 13/56
UM2426 Package description
The cellular connectivity stack exposes two main interfaces to the application:
•The control plane interface: there are two interfaces for control. The Cellular_Mngt
library provides an API to initialize SW components and starts the Cellular Service. The
Data Cache interface is used to read information related to cellular network like Signal
Strength (RSSI), and to get event notification like network registration state changes
and network interface readiness.
•The data plane interface: also referred to as the Com interface, it is used to send and
receive TCP or UDP segments to and from a remote client or server. The interface is
based on standard BSD socket API in order to ease the integration of the application.
The IPC layer abstracts the actual HW bus interface used with the modem. The IPC
supports two logical channels, each composed of one Tx (to the IPC) and one Rx (from the
IPC). One is used for exchanging AT commands with the modem while the other one is
used to carry PPP frames when LwIP is used. The selection of the active channel is
controlled by Cellular Service.

Package description UM2426
14/56 UM2426 Rev 5
4.3.2 Static architecture view
X-CUBE-CELLULAR static architecture is presented in Figure 3.
Figure 3. Static architecture view
API description
The application has access to two different API levels:
•X-CUBE-CELLULAR API
•Network library API
06Y9
'HYHORSPHQWERDUGV
'ULYHUV +DUGZDUHDEVWUDFWLRQOD\HU
0LGGOHZDUH
,3&IUDPHZRUN
$7FXVWRP
$7&RUH 0RGHP
V\VWHP
FRQWURO
26OLEUDU\&HOOXODU6HUYLFHOLEUDU\
&HOOXODU6HUYLFHWDVN
333R6L)
333FOLHQWWDVN
/Z,3
1HW,)333
)UHH5726
'DWDB&DFKH &RP &HOOXODUB0QJW
1,)0$1
WDVN
$SSOLFDWLRQV +773FOLHQW 3,1*FOLHQW
&RQQHFWLYLW\6HUYLFHOD\HU
;&8%(&(//8/$5$3,
3&
VRIWZDUH
&06,6
8WLOLWLHV
&HOOXODU
6HUYLFH
&6//$3,
&6+/$3,
(&+2FOLHQW
$7
6HUYLFH
1HWZRUNOLEUDU\
1HWZRUNOLEUDU\$3,

UM2426 Rev 5 15/56
UM2426 Package description
X-CUBE-CELLULAR API
The X-CUBE-CELLULAR API of the cellular package is defined by three components.
•Cellular management (Cellular_Mngt): initialization/starting of cellular features
•Com: data communication API based on the BSD API
•Data_Cache: this component allows the sharing of data and information between
components. Particularly it allows application to be notified of each Data_Cache update
and to get network information and status
Network library API
Another level of API is supplied by the Network library component. This API is above the
X-CUBE-CELLULAR API.
The goal of this component is to standardize network API between Wi-Fi®, Ethernet and
cellular media.
This component supplies:
•The management of the network initialization
•The data communication API based on the BSD API
•Network notifications, done by a callback recorded by the application at initialization
Component description
•HTTP client: implements an HTTP client, which sends requests to the
www.grovestreams.com cloud in the application. The HTTP client uses the Data Cache
to monitor the network interface state changes (from NIFMAN), and the COM socket
interface to send or receive HTTP packets over TCP. The HTTP client also implements
recovery as defined by GSMA TS 34 when a remote HTTP server is not reachable.
•ECHO client: implements a client application, which sends data to a remote server and
waits in return the same packet. It is used to provide a simple example using the TCP
or UDP protocol socket.
•PING client: implements a ping application that tests the access to a remote machine.
•Connectivity Service layer:
–Data_Cache: framework that decouples the management of producer and
consumer data (resource). Any resource state updated by a producer is pushed to
the Data Cache (in RAM), which in turn informs the final consumer(s) to process
the updated resource state via the callback provided by the consumer application.
Data Cache is used by Cellular Service tasks to publish the Cellular network
information like RSSI. It is also used by NIFMAN to publish the network interface
readiness.
–Com: a library that provides a collection of BSD-like socket functions to open,
configure, and send or receive application PDU to remote TCP or UDP
applications. A high-level ping service is also provided.
–Cellular_Mngt: a library that exposes a basic function to initialize and start
Cellular Service components.
•PPP client task / PPPoSIF: optional component. It is only present when LwIP is used.
It is in charge of establishing the PPP link with the modem.
•LwIP / Net IF: the LwIP component and its adaptation to PPP.

Package description UM2426
16/56 UM2426 Rev 5
•Cellular Service:
–Cellular Service task controls modem power-on and initialization, instructs the
modem to perform network registration, activates the PDN (PDP context), and
enters data transfer mode. It informs NIFMAN to setup the network interface (PPP
link). It uses AT service to send AT commands to the modem.
It implements a generic finite state machine to maintain consistent service state
based on modem internal state change events (such as FOTA or reset), network
registration state change events, and events related to the and PDP context
status. It implements the network friendly features (NFMC) as defined in [4]. For
example, when PDP activation fails because of a wrong APN, the Cellular Service
task performs a new attempt after expiration of a back-off timer.
The Cellular Service task stores the cellular configuration and network access
parameters into the Flash memory, and configure the modem as per need. The
configuration for example encompasses APN and CID settings, enabling and
disabling NFMC, and setting the back-off timers.
For system robustness, the Cellular Service task ensures that the modem is
always operational by regularly polling the modem RSSI.
–Cellular Service OS: is a library that offers a collection of functions to low-level
Cellular Service. The library serializes the access to the single AT channel
interface that is used to communicate with the modem. The functions are called by
the COM service and the Cellular Service task.
–Cellular Service library: offers a collection of blocking function calls to interact
with a modem. Cellular Service is in charge of translating the request from the
Cellular Service task or COM service to a sequence of AT commands that must be
sent to the modem. It finally calls a callback function (from the Cellular Service
task or COM service) when an asynchronous event (URC) is received from the
modem.
–AT Service: provides a framework to send or receive AT commands to or from the
modem over IPC. The AT Core task is in charge of processing the Cellular Service
requests and translate them into AT commands. It is also in charge of processing
AT commands response and URCs from the modem and forward them to Cellular
Service. AT is split into two parts:
1. a generic part, "Core" (AT framework and manage standard AT commands)
2. a specific part, "custom" (implements specific modem behavior and AT
commands)
–Modem system control: support modem HW system control signaling (power
on/off, reset). It is split into a generic and a specific part. The generic part exposes
the generic API to the application (Cellular Service) while the specific part controls
the GPIO dedicated to the modem.
•NIFMAN: the network interface manager task controls the network interface activation.
When LwIP is used, NIFMAN monitors the PPP server status (on the modem side), and
starts or stops the PPP client accordingly. The application can then monitor the network
interface status before opening a socket for data transfer.

UM2426 Rev 5 17/56
UM2426 Package description
•IPC: abstracts the actual physical interface (UART) to the upper layer. Supports the
logical channel handler (FIFO) that is mapped to a physical channel. Supports two
channels: character mode and stream mode:
– Stream mode is used for data transfer (PPP).
– Character mode is used to send AT commands.
•Common: provides tools such as debug and trace. Also provides the setup menu (over
any terminal through a serial interface) to change the default configuration, which is
hard coded during compilation and image creation.
•FreeRTOS™ (and CMSIS): provides RTOS services to create the resources and
scheduler needed by the software to run, such as threads and tasks, dynamic memory
allocation, mutexes, and semaphores. A default task (freertos.c) is in charge of system
initialization, creation of all application tasks. It finally initializes and starts the Cellular
Service components by calling cellular_init() and cellular_start().
4.3.3 Dynamic architecture view
The X-CUBE-CELLULAR dynamic architecture is further illustrated with sequence charts
that illustrate the interactions between components from initialization to socket:
•X-CUBE-CELLULAR API
–Figure 4: Dynamic architecture - X-CUBE-CELLULAR API - Platform initialization
and start
–Figure 5: Dynamic architecture - X-CUBE-CELLULAR API - Up to PDN creation
–Figure 6: Dynamic architecture - X-CUBE-CELLULAR API - Socket
•Network library API
–Figure 7: Dynamic architecture - Network library API - Initialization
–Figure 8: Dynamic architecture - Network library API - Connection
–Figure 9: Dynamic architecture - Network library API - Disconnection
–Figure 10: Dynamic architecture - Network library API - Socket service

Package description UM2426
18/56 UM2426 Rev 5
Figure 4. Dynamic architecture - X-CUBE-CELLULAR API - Platform initialization and start
DSS!
WDVN &RP 'DWDB&DFKH &HOOXODUB6HUYLFH
WDVN
&HOOXODUB0QJW
FHOOXODUBLQLW
'HIDXOW
WDVN
,QLWLDOL]HVWKH&RPVRFNHWGHVFULSWRUWDEOHV
,QLWLDOL]HVWKH&HOOXODU6:UHVRXUFHV
VXFKDVPXWH[GHIDXOWVHWWLQJVYDOXHVDQGRWKHUV
,QLWLDOL]HVWKHFHOOXODUGDWDFDFKHVFRQWHQW
,QLWLDOL]HVWKHQHWZRUNLQWHUIDFHPDQDJHU
DSS!BLQLW
FHOOXODUBVWDUW
&RQILJXUHVWKH&HOOXODU6HUYLFHVHWWLQJV
6,0FDUGVORW566,SROOLQJSHULRG1HWZRUNUHJLVWUDWLRQ
WLPHU3'1DFWLYDWLRQUHWU\WLPHUV1)0&
0RGHP')27$PRQLWRULQJWLPHU
6WDUWVWKH&HOOXODU6HUYLFHWDVN
6WDUWVWKHUDGLRLQWHUIDFHDQGWDVNVFUHDWLRQ
DSS!BVWDUW
GFBFRPBUHJLVWHUBJHQBHYHQWBFEDSSBFDOOEDFN
5HJLVWHUDSSOLFDWLRQFDOOEDFNIXQFWLRQ
/HJHQG )XQFWLRQFDOO
)XQFWLRQUHWXUQ

UM2426 Package description
UM2426 Rev 5 19/56
Figure 5. Dynamic architecture - X-CUBE-CELLULAR API - Up to PDN creation
DSS!
WDVN &RP 'DWDB&DFKH &HOOXODUB6HUYLFH
WDVN
&HOOXODUB0QJW
'HIDXOW
WDVN
2QFHVWDUWHGWKH&HOOXODU6HUYLFHWDVNSHUIRUPVDFWLRQVWRSRZHUWKHPRGHPDQGDQ\
DFWLRQWRUHJLVWHUWR1HWZRUNDQGDFWLYDWH3'1
GFBFRPBZULWH5$',2B/7(B,1)221
DSSBFDOOEDFNHYHQWBLG '&B&20B1,)0$1
/HJHQG )XQFWLRQFDOO
)XQFWLRQUHWXUQ
DSSBFDOOEDFNHYHQWBLG '&B&20B5$',2B/7(B,1)2
&KHFNVWKH6,03,1FRGHUHDGV,06,DQGRWKHUVLQIRUPDWLRQ
GFBFRPBZULWH6,0B,1)2,06,
DSSBFDOOEDFNHYHQWBLG '&B&20B6,0B,1)2
2QFHWKHPRGHPLVLQLWLDOL]HG&67IRUFHVWKHPRGHPWRSHUIRUP³DXWRPDWLF´1HWZRUN
VHDUFKDQGPRQLWRUWKHVLJQDOVWUHQJWK,IWKHVLJQDOTXDOLW\LVJRRGHQRXJKLWSHUIRUPV
QHWZRUNUHJLVWUDWLRQIRU&6DQG36GRPDLQVDQGILQDOO\DFWLYDWHVWKH3'1
GFBFRPBZULWH&(//8/$5B,1)2566,
DSSBFDOOEDFNHYHQWBLG '&B&20B&(//8/$5
GFBFRPBUHDG'&B&20B1,)0$1B,1)2
:KHQ3'1LVUHDG\,3DGGDYDLODEOH&67LQIRUPV1,)0$1YLD'DWDB&DFKH
1,)0$1LQWXUQXSGDWHVWKH1HWZRUN,QWHUIDFH6WDWHWR21

Package description UM2426
20/56 UM2426 Rev 5
Figure 6. Dynamic architecture - X-CUBE-CELLULAR API - Socket
DSS!
WDVN &RP 'DWDB&DFKH &HOOXODUB6HUYLFH
WDVN
&HOOXODUB0QJW
'HIDXOW
WDVN
/HJHQG )XQFWLRQFDOO
)XQFWLRQUHWXUQ
FRPBVRFNHW
2SWLRQDO
FRPBELQG
FRPBVHWVRFNRSW
FRPBFRQQHFW
2SWLRQDO
'HSHQGVRQWKHSURWRFROXVHGFRQQHFWHGRUQRW
6HQGGDWD
FRPBVHQG
5HFHLYHGDWD
FRPBUHFY
FRPBFORVH
2SWLRQDO
Other manuals for X-CUBE-CELLULAR
1
Table of contents
Other ST Computer Hardware manuals

ST
ST X-NUCLEO-NFC02A1 User manual

ST
ST UM2033 User manual

ST
ST UPSD3212A User manual

ST
ST X-NUCLEO-IHM17M1 User manual

ST
ST X-NUCLEO-53L4A2 User manual

ST
ST L6470H User manual

ST
ST TDA911 Series Installation and operating instructions

ST
ST STEVAL-IFP046V1 User manual

ST
ST X-NUCLEO-SNK1M1 User manual

ST
ST X-NUCLEO-IHM02A1 User manual

ST
ST X-NUCLEO-IDB04A1 User manual

ST
ST UM2082 User manual

ST
ST X-NUCLEO-S2868A2 User manual

ST
ST HTSSOP38 User manual

ST
ST STEVAL-CCH002V1 User manual

ST
ST EVSPIN958 User manual

ST
ST X-NUCLEO-53L8A1 User manual

ST
ST X-NUCLEO-OUT19A1 User manual

ST
ST STM32H5 User manual

ST
ST STEVAL-IDB013V1 Administrator Guide