Cellular X-CUBE-CELLULAR

Click here for Cellular overview

1. Introduction

This wiki article contains information to help the user navigate ST Cellular software.

2. General description

The X-CUBE-CELLULAR Expansion Package only provides software components running on the host STM32 MCU. Cellular modem firmware is not within the scope of this document. The following integrated development environments are supported:

• STMicroelectronics integrated development environment for STM32 products (STM32CubeIDE)
• IAR Systems® IAR Embedded Workbench® for Arm® (EWARM)
• Keil® Microcontroller Development Kit (MDK-ARM)

3. X-CUBE-CELLULAR versions

Since the initial version V1.0.0 in mid-2018, the software content and hardware support have increased continuously.
Versions 1.0.0 to 5.2.0 progressively encompassed new features, applications, and hardware. The cellular middleware however was part of X-CUBE, which is not sufficiently independent.
Therefore, V6.0.0 is reworked to provide standalone cellular middleware that is easier to integrate into existing applications. Therefore the boot menu has been removed but command line calls are still available. The cellular middleware API is also redesigned to ease/clarify its usage by application. Finally, V6.0.0 is the first delivery that introduces low power modem features for some modems (BG96 and Murata).
The version V7.0.0 introduces content and delivery changes. The version available on st.com is based on Azure RTOS / ThreadX. Users that need FreeRTOS support must use either the previous V6 delivery on st.com or download a patch package on Github. The method to create a FreeRTOS compliant firmware based on st.com Azure RTOS compliant firmware is described in details in the Cellular How To article.

For the complete description of deliveries (software and supported hardware), please refer to the release notes included in the X-CUBE package.

4. Which IP stack

User can choose to use either the IP stack embedded in the STM32 firmware or use the IP stack included into modem firmware.
Regarding the RTOS used the STM32 IP stack is different:

• LwIP with FreeRTOS
• NetXDuo with Azure RTOS

This option is selected in software through a #define used during the compilation process.
Note:Only IPV4 is supported.
If STM32 IP 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 IP stack to a serial interface.

5. What is X-CUBE-CELLULAR?

X-CUBE-CELLULAR (or XCC) allows applications to send and receive data on the cellular network using BSD API sockets.

Remember that the official web page on X-CUBE-CELLULAR on www.st.com provides access to multiple resources (software, documents, and so on).

X-CUBE-CELLULAR consists of a set of libraries and application examples for STM32L4 / STM32U5 Series MCUs acting as hosts for cellular connectivity applications.

SW Architecture diagram of XCC

The colors highlight the different parts, light green for applications, light blue for X-CUBE-CELLULAR specific components, dark blue for components from STM32Cube Firmware (aka HAL), dark green for ecosystem.

L4 and U5 families STM32 MCUs are currently supported, and more families are to be added in the future. However it is easy to port the cellular middleware to other STM32 MCU families thanks to STM32Cube Firmware HAL and using STM32CubeMX.

6. Software architecture

6.1. Detailed sotfware architecture

As the STM32_Cellular middleware is compliant with FreeRTOS and Azure RTOS (ThreadX) there are differences in the software architecture. Here are the 2 possibilities.

6.1.1. Azure RTOS / ThreadX software architecture

SW Architecture diagram of XCC in Azure RTOS / ThreadX

6.1.2. FreeRTOS software architecture

SW Architecture diagram of XCC in FreeRTOS

6.2. API description

The X-CUBE-CELLULAR API of the cellular middleware is defined by two components:

• Cellular management (Ctrl): Initialization/starting of cellular features. It also represents the control plane.
• Com: Data communication API based on the BSD API. It represents the data plane.

6.3. Component description

• PPPoSIF: Optional component. It is only present when STM32 IP is used, and is in charge of establishing the PPP link with the modem.

• 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 uses the cellular service OS library to send AT commands to the modem.
  • Cellular Service OS: A library that offers a collection of functions to the 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 function calls to perform transactions with a modem. Each function translates the transaction request to service requested and calls the service provided by the AT service in order to send the sequence of AT commands related to the service requested. The function returns only when all responses are received, or an error or timeout has expired from the AT service.

• AT: Provides a function to translate the cellular service requested into one or several transactions of AT commands to the modem. It sends the AT command either using a generic 3GPP command, or by using the modem-specific AT command. It is also in charge of processing AT command responses and URCs from the modem, and forwards them to the cellular service. AT is split into two parts, a generic part, "Core" (AT framework and manage standard AT commands) and a specific custom part (implements specific modem behavior and AT commands).

• IPC: Manages circular RX FIFO buffer to receive data from the modem using the physical interface. When a complete frame or character is received the IPC calls a callback function provided by the upper layer for processing. The upper layer can then call a function to read the data from the RX FIFO buffer. It supports two channels: character mode (used to send AT commands) and stream mode (used for data transfer (PPP)). It abstracts the physical interface for communication with the Modem, and provides a collection of functions that initialize, send, and receive data from a modem.

• Data_Cache: This component allows the sharing of data between components. A particular component can be notified via an event callback when an element of the Data_Cache has been modified by another component.

• RTOSAL: Provides the CMSIS OS V1/V2 abstraction. The software uses the RTOSAL API; according to a flag, CMSIS OS V1 or CMSIS OS V2 is used. Then the CMSIS OS adaptation layer calls FreeRTOS or ThreadX APIs. Note that CMSIS OS V1 and V2 are available for FreeRTOS and only CMSIS OS V2 is available for ThreadX.

7. Applications provided

7.1. Azure RTOS included applications

A single application, Echo TCP, is provided with all hardware supported with Azure RTOS.
It starts 2 identical threads. The thread sends n times a frame to an Echo server and waits for its reply, once all the frames are sent/received it displays the result (number for succeeded and number for failed, for both threads). The Echo server address can be changed, recompilation is needed.

7.2. FreeRTOS included applications

A single application, Cellular App, is provided with examples of all the supported hardware configurations. It allows the cellular middleware to be tested, and contains the following features:

• ECHO to provide an example of connection and data exchanges using the TCP or UDP (connected or not-connected mode) socket protocols. By default one instance of ECHO is started but a second one can be started to test multiple-socket configurations
• PING to test the access to a remote machine
• Performance to test throughput.

At boot, after hardware initialization, Cellular App is started and this then starts the cellular middleware.

The following hardware setup (B-L462E-CELL1) embeds more functionalities than the others. It also includes BSP for sensors and display, and a complete IoT application that: displays information on the screen, reads humidity, pressure, temperature sensors, and uses cellular middleware to exchange with the network (Echo, Ping).

7.3. For both RTOS

X-CUBE-CELLULAR also contains a command tool CLI (to interact with the firmware through a terminal on a connected PC)

8. Run-time configuration

During firmware execution, the command-line interface (CLI) is entered by pressing the [return] key. For example, the help command lists all available components.

Command	Object
help	Help command
trace	Trace management
csp	Power management
comlib	Com library commands
cst	Cellular service task management
atcmd	Send an AT command
modem	Modem configuration management

Command examples:

• cst info: provides information about the cellular network
• trace off : stops the trace
• echo off: stops the Echo application

The CLI and traces are displayed on the same terminal.

9. Board support package

The X-CUBE-CELLULAR targets 2 goals, the first is to demonstrate the cellular middleware based on multiple hardware setups. The second is to demonstrate the B-L462E-CELL1 board.
So in the X-CUBE-CELLULAR the BSP is available for B-L462E-CELL1 board.
For users who need to develop an application that uses sensors on supported hardware setups other than B-L462E-CELL1, please refer to the Cube firmware deliveries to copy/paste/adapt for cellular usage.
The B-L462E-CELL1 BSP is composed of 2 parts, the board part (Drivers/BSP/B-L462E-CELL1) and the component part (Drivers/Components/).
All the required component drivers are listed below:

• hts221 (capacitive digital sensor for relative humidity and temperature) from STMicroelectronics
• lps22hh (260-1260 hPa absolute digital output barometer) from STMicroelectronics
• lsm303agr (Ultra-low-power 3D accelerometer and 3D magnetometer) from STMicroelectronics
• ssd1315 (display driver for 0.96-inch 128 x 64 OLED / SPI Ref=9OL9935701000)
• M24128 (128-Kbit serial I²C bus EEPROM) from STMicroelectronics
• w25q80ew (8 Mbit-bit hence 1 MByte serial Flash memory) from Winbond
• mt25qu512 (MT25Q Serial NOR Flash, 512 Mbit hence 64 MByte) from Micron.

Notes:

• An EEPROM driver is not needed because the board BSP uses the HAL API directly
• The w25q80ew QSPI is internal Flash memory located in the Murata module
• The mt25qu512 QSPI is an external Flash memory soldered on the board outside the module
• The 2 QSPIs are exclusive and the default is the internal one. To use external QSPI soldering is needed, information about this is available in the board user manual.

QSPI drivers are to be provided into next delivery, X-CUBE-CELLULAR V6.1.0.

10. X-CUBE-CELLULAR dynamics

The following sequence diagram shows the cellular middleware setup from an application, more sequence diagrams are to be provided soon.

11. Folder structure

11.1. Azure RTOS based

• STM32CubeExpansion_CELLULAR_Vx.y.z
  • Drivers\
    • BSP\
      • B-L462E-CELL1\
      • Components\
        • Common\
        • hts221\
        • lps22hh\
        • ...
      • X_STMOD_PLUS_MODEMS\
        • BG96\
        • MONARCH\
        • TYPE1SC\
    • CMSIS\
    • STM32L4xx_HAL_Driver\
    • STM32U5xx_HAL_Driver\
  • Middlewares\ (Internal and external middleware)
    • ST\ (STMicroelectronics (internal) middleware)
      • STM32_Cellular\
      • cmsis_rtos_threadx (CMSIS OS V2 services that call ThreadX APIs)
      • netxduo (Azure IP Stack)
      • threadx (RTOS)
  • Projects\ (Projects, one directory per board supported)
    • 32L496GDISCOVERY\ (One of the supported board)
    • B-L462E-CELL1\ (One of the supported board)
    • B-U585I-IOT02A\ (One of the supported board)
      • • Nx_TCP_Echo_Client\
          • Core\
            • src\
            • inc\
          • EWARM\
          • MDK-ARM\
          • STM32CubeIDE\
          • STM32_Cellular\
    • B-L4S5I-IOT01A\ (One of the supported board)
    • Misc\
      • Cmd\
      • Samples\
        • NetXDuo\
          • Nx_TCP_Echo_Client\
  • Utilities\
    • Fonts\
    • LCD\
    • Modem_FW\ (material to allow modem FW update)

11.2. FreeRTOS based

• STM32CubeExpansion_CELLULAR_Vx.y.z
  • Drivers\
    • BSP\
      • B-L462E-CELL1\
      • Components\
        • Common\
        • hts221\
        • lps22hh\
        • ...
      • X_STMOD_PLUS_MODEMS\
        • BG96\
        • MONARCH\
        • TYPE1SC\
    • CMSIS\
    • STM32L4xx_HAL_Driver\
    • STM32U5xx_HAL_Driver\
  • Middlewares\ (Internal and external middleware)
    • ST\ (STMicroelectronics (internal) middleware)
      • STM32_Cellular\
    • Third_Party\ (Third-party (external middleware)
      • FreeRTOS\
      • LwIP\
  • Projects\ (Projects, one directory per board supported)
    • 32L496GDISCOVERY\ (One of the supported board)
    • B-L462E-CELL1\ (One of the supported board)
      • Demonstrations\
        • Cellular\
          • Binaries\
          • Core\
          • EWARM\
          • MDK-ARM\
          • STM32CubeIDE\
          • STM32_Cellular\
            • Config\
            • Target\
        • CellularIoT\
    • B-L4S5I-IOT01A\ (One of the supported board)
    • STWINKT1\ (One of the supported board)
    • Misc\
      • Cmd\
      • RTOS\
      • Samples\
        • Cellular\
        • CellularIoT\
  • Utilities\
    • Fonts\
    • LCD\
    • Modem_FW\ (material to allow modem FW update)

12. Real network or simulator

Users must ensure that network coverage with the target technology is available at their location since 2G, LTE Cat M and NB-IoT are not available worldwide. If the live network is not available for the target technology, the user can use a network simulator such as Amarisoft’s. To run the example, it is assumed that a network connection is possible with the device.

13. Miscellaneous information

To support low power, the application must close the socket before entering low power mode.