ST X-CUBE-CELLULAR Manuel utilisateur

October 2019 UM2426 Rev 5 1/56

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

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

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

Autres manuels pour X-CUBE-CELLULAR

Table des matières

Autres manuels ST Matériel informatique

ST SPC58NH-DISP Manuel utilisateur

ST I-CUBE-LRWAN Manuel utilisateur

ST STA309A Manuel utilisateur

ST STM32WL Series Manuel utilisateur

ST 32F412GDISCOVERY Manuel utilisateur

ST STM32 Nucleo Manuel utilisateur

ST STM32U5 Manuel utilisateur

ST STDES-65ACFADP Fiche technique

ST X-NUCLEO-IDB04A1 Manuel utilisateur

ST X-NUCLEO-AMICAM1 Manuel utilisateur

ST STM32F3 Series Manuel du propriétaire

ST TDA911 Series Instructions d'installation et d'utilisation

ST STSW-L9961BMS Manuel utilisateur

ST UPSD3212A Manuel utilisateur

ST X-NUCLEO-SAFEA1B Mode d'emploi

ST X-NUCLEO-IHM03A1 Manuel utilisateur

ST STM8SVLDISCOVERY Instructions d'installation et d'utilisation

ST STM32G071B-DISCO Manuel utilisateur

ST ST92163 Manuel utilisateur

ST X-NUCLEO-IHM12A1 Manuel utilisateur

ST X-CUBE-OUT3 Manuel utilisateur

ST STM32F10 Series Instructions d'installation et d'utilisation

ST FP-ATR-BLE1 Manuel utilisateur

ST UM3019 Manuel utilisateur

Manuels Matériel informatique populaires d'autres marques

EMC2

EMC2 VNX Series Manuel du propriétaire

Panasonic

Panasonic DV0PM20105 Manuel utilisateur

Mitsubishi Electric

Mitsubishi Electric Q81BD-J61BT11 Manuel utilisateur

Gigabyte

Gigabyte B660M DS3H AX DDR4 Manuel utilisateur

Raidon

Raidon iT2300 Manuel utilisateur

National Instruments

National Instruments PXI-8186 Manuel utilisateur

Hauppauge

Hauppauge WinTV-HVR-2250 Manuel utilisateur

Kontron

Kontron CP6002 Manuel utilisateur

Manhattan

Manhattan 702843 Manuel utilisateur

Aphex

Aphex 230 Manuel utilisateur

AMD

AMD Phenom II Manuel d'exploitation

Intel

Intel NUC 12 Pro Manuel utilisateur

dbx

dbx Zone Pro 1260 Manuel utilisateur

Galaxy

Galaxy GHDX2-2430S-24F4D Manuel utilisateur

Intel

Intel AXXRMFBU4 Manuel utilisateur

Kontron

Kontron DIMM-PC/MD Manuel utilisateur

STEINWAY LYNGDORF

STEINWAY LYNGDORF SP-1 Manuel utilisateur

Advantech

Advantech ASMB-935 Series Manuel utilisateur