Difference between revisions of "Cellular:Cellular X-CUBE-CELLULAR"

[quality revision] [quality revision]
m
m
 

Click here for Cellular overview

1 Introduction[edit]

This wiki page contains article provides information to help the end user navigate the ST Cellular software. When the information is already present in a data brief or a user manual, this wiki redirects to those reference documents. While the information in this wiki article is not exhaustive, it is an aid to finding further information.

2

2 General description[edit]

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[edit]

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 cellular middleware however was part of X-CUBE, which is not sufficiently independent.
Therefore, V6.0.0 is reworked to provide standalone Cellular cellular middleware that is easier to integrate into existing applications. Therefore the The boot menu has been removed but command line calls are still available. The Cellular 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 current version , V6V7.0.0, supports the following hardware configurations:

  • P-L496G-CELL02 (pack with a screenless 32L496GDISCOVERY associated with an STMod+ BG96 Quectel modem)
  • STEVAL-STWINKT1B (STWIN SensorTile Wireless Industrial Node development kit and reference design for industrial IoT applications)
  • B-L462E-CELL1 (Discovery board with T1SE Murata module (STM32 L462, ST4SIM, ALT1250 modem))
  • STEVAL-STMODLTE (LTE connectivity expansion board for STMod+ connector compatible evaluation boards, based on the Quectel BG96 modem, the same modem board in the P-L496G-CELL02 pack described above)
  • GM01Q-STMOD or GMS01Q-STMOD (Monarch from Sequans, GMS01Q is a GM01Q that also contains an internal SIM with a prepaid data plan).

P-L496G-CELL02 and B-L462E-CELL1 are standalone setups. For other STM32 boards (B-L4S5I-IOT01A, 32L496GDISCOVERY, STEVAL-STWINKT1B), just plug in the STEVAL-STMODLTE or GM01Q-STMOD modem boards. Note: for B-L4S5I-IOT01A, an X-NUCLEO-STMODA1 (ARDUINO® / STMod+ adapter) must be used. 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), please refer to the release notes included in the X-CUBE package.

3 4 Which IP stack[edit]

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?[edit]

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[1] on www.st.com provides access to multiple resources (such as, software , and 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.



The colors highlight the different parts, Light Green light green for applications, light Blue for Middlewaresblue for X-CUBE-CELLULAR specific components, dark Blue for HAL, Purple for hardwareblue for components from STM32Cube Firmware (aka HAL), dark green for ecosystem.

L4 family and U5 families STM32 MCUs are currently scopedsupported, and with more families are to be added in the future. However it is easy to port the Cellular cellular middleware on to other STM32 MCU families thanks to the STM32Cube firmware HAL and by using STM32CubeMX.

4

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[edit]

6.1 Detailed software architecture[edit]

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[edit]

SW Architecture diagram of XCC in Azure RTOS / ThreadX

6.1.2 FreeRTOS software architecture[edit]

SW Architecture diagram of XCC in FreeRTOS

6.2 API description[edit]

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[edit]

  • 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[edit]

7.1 Azure RTOS included applications[edit]

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[edit]

A single application, Cellular App, is provided with examples of all the supported hardware configurations. It allows the Cellular 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 cellular middleware. X-CUBE-CELLULAR also contains a command tool (to interact with the firmware through a terminal on a connected PC)

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

5 Board

7.3 For both RTOS[edit]

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[edit]

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[edit]

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

10 X-CUBE-CELLULAR

V6.1.0.

6 X-CUBE-CELLULAR dynamics[edit]

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[edit]

To be completed soon.

10.2 FreeRTOS dynamics[edit]

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

Application setups the middleware

7 11 Folder structure[edit]

11.1 Azure RTOS based[edit]

  • 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[edit]

  • 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[edit]

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[edit]

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

14 References[edit]



Click [[Cellular LTE CatM / NBIoT overview|here]] for Cellular overview<br>

==Introduction==
This wiki page containsarticle provides information to help the end user navigate the ST Cellular software.When the information is already present in a data brief or a user manual, this wiki redirects to those reference documents. While the information in this wiki article is not exhaustive, it is an aid to finding further information.


==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)
==X-CUBE-CELLULAR versions==
Since the initial version '''V1.0.0''' in mid-2018, the software content and hardware support have increased continuously.<br>

Versions 1.0.0 to 5.2.0 progressively encompassed new features, applications, and hardware. The Cellularcellular middleware however was part of X-CUBE, which is not sufficiently independent.<br>Therefore,  '''V6.0.0''' is reworked to provide standalone Cellularcellular middleware that is easier to integrate into existing applications. Therefore the The boot menu has been removed but command line calls are still available. The Cellularcellular 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).<br> The current version, '''V6.0.0''', supports the following '''hardware configurations''':<br>

*[https://www.st.com/en/evaluation-tools/p-l496g-cell02.html P-L496G-CELL02] (pack with a screenless 32L496GDISCOVERY associated with an STMod+ BG96 Quectel modem)

*[https://www.st.com/en/evaluation-tools/b-l4s5i-iot01a.html B-L4S5I-IOT01A] (STM32L4+ Discovery kit IoT node)

*[https://www.st.com/en/evaluation-tools/32l496gdiscovery.html 32L496GDISCOVERY] (Discovery kit with STM32L496AG MCU)

*[https://www.st.com/en/evaluation-tools/steval-stwinkt1b.html STEVAL-STWINKT1B] (STWIN SensorTile Wireless Industrial Node development kit and reference design for industrial IoT applications)

*[https://www.st.com/en/evaluation-tools/b-l462e-cell1.html B-L462E-CELL1] (Discovery board with T1SE Murata module (STM32 L462, ST4SIM, ALT1250 modem))

*[https://www.st.com/en/ecosystems/x-nucleo-stmoda1.html X-NUCLEO-STMODA1] (STMod+ connector expansion board for ARDUINO<sup>®</sup> connectors)

*[https://www.st.com/content/st_com/en/products/evaluation-tools/solution-evaluation-tools/communication-and-connectivity-solution-eval-boards/steval-stmodlte.html STEVAL-STMODLTE] (LTE connectivity expansion board for STMod+ connector compatible evaluation boards, based on the Quectel BG96 modem, the same modem board in the P-L496G-CELL02 pack described above)

*[http://www.sequans.com/gm01q-stmod/ GM01Q-STMOD] or [http://www.sequans.com/gms01q-stmod/ GMS01Q-STMOD] (Monarch from Sequans, GMS01Q is a GM01Q that also contains an internal SIM with a prepaid data plan).<br>

P-L496G-CELL02 and B-L462E-CELL1 are standalone setups.
For other STM32 boards (B-L4S5I-IOT01A, 32L496GDISCOVERY, STEVAL-STWINKT1B), just plug in the STEVAL-STMODLTE or GM01Q-STMOD modem boards.
Note: for B-L4S5I-IOT01A, an X-NUCLEO-STMODA1 (ARDUINO<sup>®</sup> / STMod+ adapter) must be used.<br>

For the complete description of deliveries (software and supported hardware), please refer to the release notes included in the X-CUBE package '''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.

==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.<br> 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.<br>Note that only IPV4 is supported.<br>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.

==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<ref>[https://www.st.com/en/embedded-software/x-cube-cellular.html X-CUBE-CELLULAR]</ref> on www.st.com provides access to multiple resources (software, documents, and so onsuch 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.
<br>[[File: Cellular_SW_Archi_V6.x.pngarchi_RTOS.jpg |400px|center| SW Architecture diagram of Cellular stackXCC]]<br>


The colors highlight the different parts, '''Light Greenlight green''' for applications, '''light Blueblue''' for Middlewares, '''dark Blue''' for HAL, '''Purple''' for hardware.

L4 family 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 scoped, andsupported, with more families are to be added in the future. However it is easy to port the Cellularcellular middleware onto other STM32 MCU families.

==Applications provided==
A single application,  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.

==Software architecture==
=== 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.

==== Azure RTOS / ThreadX software architecture ====

[[File: Cellular_SW_archi_ThreadX.jpg |400px|center| SW Architecture diagram of XCC in Azure RTOS / ThreadX]]

==== FreeRTOS software architecture ====

[[File: Cellular_SW_archi_FreeRTOS.jpg |400px|center| SW Architecture diagram of XCC in FreeRTOS]]

=== 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.

===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.

==Applications provided==
=== Azure RTOS included applications ===
A single application, Echo TCP, is provided with all hardware supported with Azure RTOS.<br> 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.

=== FreeRTOS included applications ===

A single application, Cellular App, is provided with examples of  all the supported hardware configurations. It allows the Cellularcellular 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 Cellularcellular middleware.<br>

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

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

==Board = For both RTOS===
X-CUBE-CELLULAR also contains a CLI command tool, to interact with the firmware through a terminal on a connected PC.

==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
|}<br>

Command examples:
* cst info: provides information about the cellular network
* trace off: stops the trace
* echo off: stops the Echo application<br>

The CLI and traces are displayed on the same terminal.

==L462 board support package ==
The X-CUBE-CELLULAR targets 2two goals, the first one is to demonstrate the Cellularcellular middleware based on multiple hardware setups. The second is to demonstrate the B-L462E-CELL1 board.<br>In Therefore, in the X-CUBE-CELLULAR the BSP is only available for B-L462E-CELL1 boardsboard.<br>For end users who need to develop an application that uses sensors on supported hardware setups other than B-L462E-CELL1, please refer to the Cube FWfirmware deliveries to copy/paste/adapt for cellular usage.<br> The B-L462E-CELL1 BSP is composed of 2two parts, the board part (Drivers/BSP/B-L462E-CELL1) and the component part (Drivers/Components/).<br> 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 Serialserial Flash Memorymemory) 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 Flashflash memory located in the Murata module
* The mt25qu512 QSPI is an external Flashflash memory soldered on the board outside the module
* The 2two QSPIs are exclusive and the default is the internal one. To use external QSPI soldering is needed,. information about related to this is available in the board user manual.<br> QSPI drivers are to be provided into next delivery, X-CUBE-CELLULAR V6.1.0.

==X-CUBE-CELLULAR dynamics ==

==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.

=== Azure RTOS dynamics ===
To be completed soon.

=== FreeRTOS dynamics ===

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

[[File: Cellular_XCC_SD_001.png |600px|center| Application setups the middleware]]<br>


==Folder structure==
=== 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)'''

=== 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)'''

==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.

==Miscellaneous information==
To support low power, the application must close the socket before entering low -power mode.


{{PublicationRequestId | 19450| 2021-03-29==References==<references />


{{PublicationRequestId | 22513| 2022-02-10 | Ronan Gabou}}

{{ArticleBasedOnModel | Example tech domain article}}
<noinclude>

[[Category:Using modelsCellular|20]]
[[Category:Cellular|20Using models]]</noinclude>
(46 intermediate revisions by 4 users not shown)
Line 3: Line 3:
 
<br>
 
<br>
 
==Introduction==
 
==Introduction==
This wiki page contains information to help the user navigate ST Cellular software. When the information is already present in a data brief or a user manual, this wiki redirects to those reference documents. While the information in this wiki article is not exhaustive, it is an aid to finding further information.
+
This wiki article provides information to help the end user navigate the ST Cellular software.
  +
 
  +
==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)
   
 
==X-CUBE-CELLULAR versions==
 
==X-CUBE-CELLULAR versions==
 
Since the initial version '''V1.0.0''' in mid-2018, the software content and hardware support have increased continuously.
 
Since the initial version '''V1.0.0''' in mid-2018, the software content and hardware support have increased continuously.
 
<br>
 
<br>
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.
+
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.
<br>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).
+
<br>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).
<br>
+
<br> 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".
The current version, '''V6.0.0''', supports the following '''hardware configurations''':
+
 
<br>
+
For the complete description of deliveries (software and supported hardware), refer to the release notes included in the X-CUBE package.
*[https://www.st.com/en/evaluation-tools/p-l496g-cell02.html P-L496G-CELL02] (pack with a screenless 32L496GDISCOVERY associated with an STMod+ BG96 Quectel modem)
+
 
  +
==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.
  +
<br> 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.
  +
<br>Note that only IPV4 is supported.
  +
<br>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.
  +
 
  +
==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<ref>[https://www.st.com/en/embedded-software/x-cube-cellular.html X-CUBE-CELLULAR]</ref> 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.
  +
 
  +
<br>[[File: Cellular_SW_archi_RTOS.jpg |400px|center| SW Architecture diagram of XCC]]<br>
  +
 
  +
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.
   
*[https://www.st.com/en/evaluation-tools/b-l4s5i-iot01a.html B-L4S5I-IOT01A] (STM32L4+ Discovery kit IoT node)
+
==Software architecture==
  +
=== Detailed software architecture ===
   
*[https://www.st.com/en/evaluation-tools/32l496gdiscovery.html 32L496GDISCOVERY] (Discovery kit with STM32L496AG MCU)
+
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.
   
*[https://www.st.com/en/evaluation-tools/steval-stwinkt1b.html STEVAL-STWINKT1B] (STWIN SensorTile Wireless Industrial Node development kit and reference design for industrial IoT applications)
+
==== Azure RTOS / ThreadX software architecture ====
   
*[https://www.st.com/en/evaluation-tools/b-l462e-cell1.html B-L462E-CELL1] (Discovery board with T1SE Murata module (STM32 L462, ST4SIM, ALT1250 modem))
+
[[File: Cellular_SW_archi_ThreadX.jpg |400px|center| SW Architecture diagram of XCC in Azure RTOS / ThreadX]]
   
*[https://www.st.com/en/ecosystems/x-nucleo-stmoda1.html X-NUCLEO-STMODA1] (STMod+ connector expansion board for ARDUINO<sup>®</sup> connectors)
+
==== FreeRTOS software architecture ====
   
*[https://www.st.com/content/st_com/en/products/evaluation-tools/solution-evaluation-tools/communication-and-connectivity-solution-eval-boards/steval-stmodlte.html STEVAL-STMODLTE] (LTE connectivity expansion board for STMod+ connector compatible evaluation boards, based on the Quectel BG96 modem, the same modem board in the P-L496G-CELL02 pack described above)
+
[[File: Cellular_SW_archi_FreeRTOS.jpg |400px|center| SW Architecture diagram of XCC in FreeRTOS]]
   
*[http://www.sequans.com/gm01q-stmod/ GM01Q-STMOD] or [http://www.sequans.com/gms01q-stmod/ GMS01Q-STMOD] (Monarch from Sequans, GMS01Q is a GM01Q that also contains an internal SIM with a prepaid data plan).
+
=== API description===
<br>
+
The X-CUBE-CELLULAR API of the cellular middleware is defined by two components:
P-L496G-CELL02 and B-L462E-CELL1 are standalone setups.
+
* '''Cellular management (Ctrl):''' initialization/starting of cellular features. It also represents the control plane.
For other STM32 boards (B-L4S5I-IOT01A, 32L496GDISCOVERY, STEVAL-STWINKT1B), just plug in the STEVAL-STMODLTE or GM01Q-STMOD modem boards.
+
* '''Com:''' data communication API based on the BSD API. It represents the data plane.
Note: for B-L4S5I-IOT01A, an X-NUCLEO-STMODA1 (ARDUINO<sup>®</sup> / STMod+ adapter) must be used.
 
<br>
 
For the complete description of deliveries (software and supported hardware), please refer to the release notes included in the X-CUBE package.
 
   
==What is X-CUBE-CELLULAR?==
+
===Components description===
X-CUBE-CELLULAR (or XCC) allows applications to send and receive data on the cellular network using BSD API sockets.
+
* '''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.
   
Remember that the official web page on [https://www.st.com/en/embedded-software/x-cube-cellular.html X-CUBE-CELLULAR] on www.st.com provides access to multiple resources (software, documents, and so on).
+
* '''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).
   
X-CUBE-CELLULAR consists of a set of libraries and application examples for STM32L4 Series MCUs acting as hosts for cellular connectivity applications.
+
* '''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.
   
<br>[[File: Cellular_SW_Archi_V6.x.png |400px|center| SW Architecture diagram of Cellular stack]]<br>
+
* '''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.
   
The colors highlight the different parts, '''Light Green''' for applications, '''light Blue''' for Middlewares, '''dark Blue''' for HAL, '''Purple''' for hardware.
+
* '''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.
   
L4 family STM32 MCUs are currently scoped, and more families are to be added in the future. However it is easy to port the Cellular middleware on other STM32 MCU families.
+
* '''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.
   
 
==Applications provided==
 
==Applications provided==
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:
+
=== Azure RTOS included applications ===
* 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
+
A single application, Echo TCP, is provided with all hardware supported with Azure RTOS.
* PING to test the access to a remote machine
+
<br> 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.
  +
 
  +
=== 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.
 
* Performance to test throughput.
   
At boot, after hardware initialization, Cellular App is started and this then starts the Cellular middleware.
+
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).
  +
 
  +
=== For both RTOS===
  +
X-CUBE-CELLULAR also contains a CLI command tool, to interact with the firmware through a terminal on a connected PC.
  +
  +
==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
  +
|}
  +
<br>
  +
Command examples:
  +
* cst info: provides information about the cellular network
  +
* trace off: stops the trace
  +
* echo off: stops the Echo application
 
<br>
 
<br>
X-CUBE-CELLULAR also contains a command tool (to interact with the firmware through a terminal on a connected PC)
+
The CLI and traces are displayed on the same terminal.
 
The following hardware setup (B-L462E-CELL1) embeds more than the others. It also brings BSP for sensors and display, and a complete IoT application: displays information on the screen, reads humidity, pressure, temperature sensors, and uses Cellular middleware to exchange with the network (Echo, Ping).
 
   
==Board support package ==
+
==L462 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.
+
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.
<br>In the X-CUBE-CELLULAR the BSP is only available for B-L462E-CELL1 boards.
+
<br>Therefore, in the X-CUBE-CELLULAR the BSP is available for B-L462E-CELL1 board.
<br>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 FW deliveries to copy/paste/adapt for cellular usage.
+
<br>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.
<br> The B-L462E-CELL1 BSP is composed of 2 parts, the board part (Drivers/BSP/B-L462E-CELL1) and the component part (Drivers/Components/).
+
<br> The B-L462E-CELL1 BSP is composed of two parts, the board part (Drivers/BSP/B-L462E-CELL1) and the component part (Drivers/Components/).
 
<br> All the required component drivers are listed below:
 
<br> All the required component drivers are listed below:
 
* hts221 (capacitive digital sensor for relative humidity and temperature) from STMicroelectronics
 
* hts221 (capacitive digital sensor for relative humidity and temperature) from STMicroelectronics
Line 71: Line 137:
 
* ssd1315 (display driver for 0.96-inch 128 x 64 OLED / SPI Ref=9OL9935701000)
 
* ssd1315 (display driver for 0.96-inch 128 x 64 OLED / SPI Ref=9OL9935701000)
 
* M24128 (128-Kbit serial I²C bus EEPROM) from STMicroelectronics
 
* M24128 (128-Kbit serial I²C bus EEPROM) from STMicroelectronics
* w25q80ew (8 Mbit-bit hence 1 MByte Serial Flash Memory) from Winbond
+
* w25q80ew (8 Mbit-bit hence 1 MByte serial Flash memory) from Winbond
 
* mt25qu512 (MT25Q Serial NOR Flash, 512 Mbit hence 64 MByte) from Micron.
 
* mt25qu512 (MT25Q Serial NOR Flash, 512 Mbit hence 64 MByte) from Micron.
   
 
Notes:
 
Notes:
 
* An EEPROM driver is not needed because the board BSP uses the HAL API directly
 
* 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 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 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.
+
* 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.
<br> QSPI drivers are to be provided into next delivery, X-CUBE-CELLULAR V6.1.0.
 
   
 
==X-CUBE-CELLULAR dynamics ==
 
==X-CUBE-CELLULAR dynamics ==
The following sequence diagram shows the Cellular middleware setup from an application, more sequence diagrams are to be provided soon.
+
 
  +
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.
  +
 
  +
=== Azure RTOS dynamics ===
  +
To be completed soon.
  +
 
  +
=== FreeRTOS dynamics ===
  +
The following sequence diagram shows the cellular middleware setup from an application, more sequence diagrams to be provided soon.
   
 
[[File: Cellular_XCC_SD_001.png |600px|center| Application setups the middleware]]<br>
 
[[File: Cellular_XCC_SD_001.png |600px|center| Application setups the middleware]]<br>
  +
  +
==Folder structure==
  +
=== 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)'''
  +
  +
=== 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)'''
  +
  +
==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.
   
 
==Miscellaneous information==
 
==Miscellaneous information==
To support low power, the application must close the socket before entering low power mode.
+
To support low power, the application must close the socket before entering low-power mode.
   
  +
==References==
  +
<references />
   
{{PublicationRequestId | 19450| 2021-03-29 | Ronan Gabou}}
+
{{PublicationRequestId | 22513| 2022-02-10 | Ronan Gabou}}
   
 
{{ArticleBasedOnModel | Example tech domain article}}
 
{{ArticleBasedOnModel | Example tech domain article}}
   
 
<noinclude>
 
<noinclude>
  +
[[Category:Cellular|20]]
 
[[Category:Using models]]
 
[[Category:Using models]]
[[Category:Cellular|20]]
 
 
</noinclude>
 
</noinclude>