ST X-CUBE-CELLULAR Manual de usuario

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

Otros manuales para X-CUBE-CELLULAR

Tabla de contenidos

Otros manuales de Hardware de computadora de ST

ST STM32Cube Guía de configuración rápida

ST X-NUCLEO-IDW01M1 Manual de usuario

ST STEVAL-DPSG474 Manual de usuario

ST X-NUCLEO-53L1A1 Manual de usuario

ST X-NUCLEO-IDB04A1 Manual de usuario

ST STM32L562E-DK Manual de usuario

ST X-NUCLEO-OUT09A1 Manual de usuario

ST Nomadik NHK-15 Manual de usuario

ST X-CUBE-CELLULAR Manual de usuario

ST AN1235 Instrucciones de instalación y funcionamiento

ST STEVAL-IFP042V1 Manual de usuario

ST L6470H Manual de usuario

ST STM32 ODE Manual de usuario

ST STM32G071B-DISCO Manual de usuario

ST X-NUCLEO-GNSS1A1 Manual de usuario

ST X-NUCLEO-OUT13A1 Manual de usuario

ST STM32 Nucleo Manual de usuario

ST STM32U5G9J-DK2 Manual de usuario

ST STM32F101 series Manual de usuario

ST B-U585I-IOT02A Manual de usuario

ST X-NUCLEO-IHM09M1 Manual de usuario

ST METERS AND MORE UM2241 Manual de usuario

ST STR9 Manual de usuario

ST ST32M103 Series Manual de usuario

Manuales populares de Hardware de computadora de otras marcas

EMC2

EMC2 VNX Series Manual del propietario

Panasonic

Panasonic DV0PM20105 Manual de usuario

Mitsubishi Electric

Mitsubishi Electric Q81BD-J61BT11 Manual de usuario

Gigabyte

Gigabyte B660M DS3H AX DDR4 Manual de usuario

Raidon

Raidon iT2300 Manual de usuario

National Instruments

National Instruments PXI-8186 Manual de usuario

Hauppauge

Hauppauge WinTV-HVR-2250 Manual de usuario

Kontron

Kontron CP6002 Manual de usuario

Manhattan

Manhattan 702843 Manual de usuario

Aphex

Aphex 230 Manual de usuario

AMD

AMD Phenom II Manual operacional

Intel

Intel NUC 12 Pro Manual de usuario

dbx

dbx Zone Pro 1260 Manual de usuario

Galaxy

Galaxy GHDX2-2430S-24F4D Manual de usuario

Intel

Intel AXXRMFBU4 Manual de usuario

Kontron

Kontron DIMM-PC/MD Manual de usuario

STEINWAY LYNGDORF

STEINWAY LYNGDORF SP-1 Manual de usuario

Advantech

Advantech ASMB-935 Series Manual de usuario