Cellular X-CUBE-CELLULAR

Click here for Cellular overview

1. Introduction

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

2. General description

The X-CUBE-CELLULAR Expansion Package only provides software components running on the host STM32 MCU. The 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. 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 the 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 www.st.com is based on Azure RTOS / ThreadX. En users who need FreeRTOS support must use either the previous V6 delivery available on www.st.com or download an additional FreeRTOS package on Github. The method to create a compliant FreeRTOS firmware is described in the article section "How To".

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

4. Which IP stack

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

• LwIP with FreeRTOS
• NetXDuo with Azure RTOS

The IP stack configuration is selected in the software through a #define used during the compilation process.
Note that only IPV4 is supported.
If STM32 IP stack is selected, the communication between the host and the 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 (such as, software and documents).

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

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, with more families to be added in the future. However it is easy to port the cellular middleware to other STM32 MCU families thanks to the STM32Cube firmware HAL and by using STM32CubeMX. Consequently, not moving to the new STM32 family might lead to changes of HAL API. This might require introducing adaptations in STM32_Cellular middleware.

6. Software architecture

6.1. Detailed software architecture

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

6.1.1. Azure RTOS / ThreadX software architecture

6.1.2. FreeRTOS software architecture

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. Components description

• 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 manages 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.

• PPPoSIF: optional component. It is only present when STM32 IP is used, and is in charge of establishing the PPP link with the modem. Each IP middleware has its own PPPoSIF, one version for NetX Duo and another one for LwIP.

• 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.
By default it starts two 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, number of sent frame, delay between two consecutive sends can be changed. In that case rebuild is required.

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 other hardware setups. It also includes BSP for sensors and display, as well as 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 CLI command tool, 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. L462 board support package

The X-CUBE-CELLULAR targets two goals, the first one is to demonstrate the cellular middleware based on multiple hardware setups. The second is to demonstrate the B-L462E-CELL1 board.
Therefore, in the X-CUBE-CELLULAR the BSP is available for B-L462E-CELL1 board.
For end users who need to develop an application that uses sensors on supported hardware setups other than B-L462E-CELL1, refer to the Cube firmware deliveries to copy/paste/adapt for cellular usage.
The B-L462E-CELL1 BSP is composed of two 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 an internal flash memory located in the Murata module
• The mt25qu512 QSPI is an external flash memory soldered on the board outside the module
• The two QSPIs are exclusive and the default is the internal one. To use external QSPI soldering is needed. information related to this is available in the board user manual.

10. X-CUBE-CELLULAR dynamics

As mentioned previously, the XCC, STM32_Cellular middleware supports Azure RTOS and FreeRTOS, dynamics are different regarding the RTOS used. Thus, there is one chapter per RTOS.

10.1. Azure RTOS dynamics

To be completed soon.

10.2. FreeRTOS dynamics

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

11. Folder structure

11.1. Azure RTOS based

• STM32CubeExpansion_CELLULAR_Vx.y.z
  • Drivers\
    • BSP\
      • 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\
    • B-L462E-CELL1\
    • B-U585I-IOT02A\
      • • Nx_TCP_Echo_Client\
          • Core\
            • src\
            • inc\
          • EWARM\
          • MDK-ARM\
          • STM32CubeIDE\
          • STM32_Cellular\
    • B-L4S5I-IOT01A\
    • Misc\
      • Cmd\
      • Samples\
        • NetXDuo\
          • Nx_TCP_Echo_Client\
  • Utilities\
    • 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\
    • B-L462E-CELL1\
      • Demonstrations\
        • Cellular\
          • Binaries\
          • Core\
          • EWARM\
          • MDK-ARM\
          • STM32CubeIDE\
          • STM32_Cellular\
            • Config\
            • Target\
        • CellularIoT\
    • B-L4S5I-IOT01A\
    • B-U585I-IOT02A\
    • Misc\
      • Cmd\
      • RTOS\
      • Samples\
        • Cellular\
        • CellularIoT\
  • Utilities\
    • Fonts\
    • LCD\
    • Modem_FW\ (material to allow modem FW update)

12. Real network or simulator

The end user must ensure that the 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 end 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.