Table of Contents
Advertisement
Quick Links
X-CUBE-CELLULAR cellular connectivity Expansion Package for
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
• 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
• 32L496GDISCOVERY Discovery board and modem board based on Sequans
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
October 2019
UM2426 Rev 5
UM2426
User manual
STM32Cube
Chapter 1
for details):
®
GM01Q modem
®
GM01Q,
www.st.com
1/56
1
Advertisement
Table of Contents
Related Manuals for ST X-CUBE-CELLULAR
Summary of Contents for ST X-CUBE-CELLULAR
- Page 1 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).
-
Page 2: Table Of Contents
Dynamic architecture view ........17 X-CUBE-CELLULAR Expansion Package description ....25 Folder structure . - Page 3 UM2426 Contents How to customize the software? ......40 First customization level: user customization ..... . 40 Second customization level: advanced user customization .
- Page 4 List of tables UM2426 List of tables Table 1. List of acronyms ............7 Table 2.
- Page 5 X-CUBE-CELLULAR folder structure ........
-
Page 6: General Information
General information UM2426 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: •... -
Page 7: Table 1. List Of Acronyms
UM2426 General information Table 1. List of acronyms Term Definition Application programming interface Access point name Berkeley software distribution Board support package Cellular to cloud Context ID (context identifier of a cellular connection) Cellular communication Data Cache eUICC Embedded UICC (UICC with remote profile feature) eSIM Embedded SIM FEEPROM... -
Page 8: References
Short-message service Transmission control protocol User datagram protocol UICC Universal integrated circuit card (also referred to as SIM card) Unsolicited result code The X-CUBE-CELLULAR Expansion Package runs on STM32L4 32-bit microcontrollers ®(a) ® based on the Arm Cortex -M4 processor. -
Page 9: Important Note Regarding The Security
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. -
Page 10: Service Connectivity Description
(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. -
Page 11: Package Description
X-CUBE-CELLULAR runs on STM32 boards and allows sending or receiving IP packets to or from the Internet via an add-on cellular module. Note: Some parts of X-CUBE-CELLULAR can be used in a bare OS environment. The complete stack only runs with FreeRTOS™. UM2426 Rev 5... -
Page 12: Architecture Concept
Package description UM2426 The package is split into the following components: • STM32L4 Series HAL • CMSIS/FreeRTOS™ • Network • LwIP • AT Service • Cellular Service • Cellular_Mngt • • Data_Cache • • NIFMAN • Common 4.3.1 Architecture concept This section provides a high-level view of the software architecture supporting cellular connectivity, which is illustrated in Figure... - Page 13 UM2426 Package description The cellular connectivity stack exposes two main interfaces to the application: • The control plane interface: there are two interfaces for control. The Cellular_Mngt library provides an API to initialize SW components and starts the Cellular Service. The Data Cache interface is used to read information related to cellular network like Signal Strength (RSSI), and to get event notification like network registration state changes and network interface readiness.
-
Page 14: Static Architecture View
Package description UM2426 4.3.2 Static architecture view X-CUBE-CELLULAR static architecture is presented in Figure Figure 3. Static architecture view API description The application has access to two different API levels: • X-CUBE-CELLULAR API • Network library API 14/56 UM2426 Rev 5... - Page 15 UM2426 Package description X-CUBE-CELLULAR API The X-CUBE-CELLULAR API of the cellular package is defined by three components. • Cellular management (Cellular_Mngt): initialization/starting of cellular features • Com: data communication API based on the BSD API • Data_Cache: this component allows the sharing of data and information between components.
- Page 16 Package description UM2426 • 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 informs NIFMAN to setup the network interface (PPP link).
-
Page 17: Dynamic Architecture View
– Figure 4: Dynamic architecture - X-CUBE-CELLULAR API - Platform initialization and start – Figure 5: Dynamic architecture - X-CUBE-CELLULAR API - Up to PDN creation – Figure 6: Dynamic architecture - X-CUBE-CELLULAR API - Socket • Network library API –... - Page 18 Figure 4. Dynamic architecture - X-CUBE-CELLULAR API - Platform initialization and start...
- Page 19 Figure 5. Dynamic architecture - X-CUBE-CELLULAR API - Up to PDN creation...
- Page 20 Figure 6. Dynamic architecture - X-CUBE-CELLULAR API - Socket...
- Page 21 Figure 7. Dynamic architecture - Network library API - Initialization...
- Page 22 Figure 8. Dynamic architecture - Network library API - Connection...
- Page 23 Figure 9. Dynamic architecture - Network library API - Disconnection...
- Page 24 Figure 10. Dynamic architecture - Network library API - Socket service...
-
Page 25: X-Cube-Cellular Expansion Package Description
UM2426 Package description X-CUBE-CELLULAR Expansion Package description This section describes the software components of the X-CUBE-CELLULAR package. X-CUBE-CELLULAR is an Expansion Package for STM32Cube. Its main features are: • Fully compliant with STM32Cube architecture • Expands STM32Cube in order to enable the development of applications accessing and using various cloud platforms •... -
Page 26: Folder Structure
Package description UM2426 Folder structure Figure 11 presents the folder structure of the X-CUBE-CELLULAR Expansion Package with middleware folder break down. 26/56 UM2426 Rev 5... -
Page 27: Figure 11. X-Cube-Cellular Folder Structure
UM2426 Package description Figure 11. X-CUBE-CELLULAR folder structure UM2426 Rev 5 27/56... -
Page 28: Reset Push-Button
Package description UM2426 Reset push-button The reset push-button (black) is used to reset the board at any time. This action forces the reboot of the platform. Real-time clock System date and time are managed by the RTC. At boot time, it is possible to update the system date manually at boot setup (if available). If no such update is performed, the system date is updated by the ECHO or HTTP client using the information sent by the remote host. -
Page 29: Cellular Connectivity Examples
UM2426 Cellular connectivity examples Cellular connectivity examples This chapter describes the cellular connectivity available examples. Several examples that can run in parallel are provided, such as PING, ECHO, and HTTP clients. Real network or simulator The worldwide coverage of 2G and 3G networks makes it possible to systematically run the examples for these technologies on real networks. -
Page 30: Ping Example
Cellular connectivity examples UM2426 PING example The console command allows the generation of ping requests (refer to Section 7.3: Console command on page 39). The simple ping command generates 10 ping requests using default IP address 8.8.8.8. To specify another IP address, use the ping <ddd.ddd.ddd.ddd>... -
Page 31: Echo Example
UM2426 Cellular connectivity examples ECHO example The ECHO application is a client that exchanges data with a remote server using the TCP or UDP (connected or not-connected mode) socket. ECHO is the only example activated by default in the generated binaries (meaning that data exchange with the pre-configured remote server starts automatically when software finishes to boot): •... -
Page 32: Figure 13. Grovestreams Web Interface, Component View
Cellular connectivity examples UM2426 For temperature, humidity, and pressure, if the X-NUCLEO-IKS01A2 board with sensors is plugged, real values are sent to the cloud server. Otherwise, simulated data are reported. With the “Discovery IoT node cellular” set, real values are always sent. Figure 13 Figure 14 present the related GroveStreams interfaces. -
Page 33: Hardware And Software Environment Setup
UM2426 Hardware and software environment setup Hardware and software environment setup STM32 MCU firmware must always be programmed. Modem firmware can be upgraded too if needed. Note: For P-L496G-CELL01 and P-L496G-CELL02, before programming with new firmware, connect the system to a PC with Tera Term and note the voucher number; this number is needed to activate the eSIM on the modem board. -
Page 34: Figure 15. Hardware Setup (P-L496G-Cell02 Example)
Hardware and software environment setup UM2426 Figure 15 depicts the hardware setup. Figure 15. Hardware setup (P-L496G-CELL02 example) 34/56 UM2426 Rev 5... -
Page 35: Figure 16. Hardware View (P-L496G-Cell02 Example)
UM2426 Hardware and software environment setup Figure 16 shows the P-L496G-CELL02 with the USB cable in place for power supply and optional trace / boot menu. Figure 16. Hardware view (P-L496G-CELL02 example) UM2426 Rev 5 35/56... -
Page 36: Figure 17. Hardware View ("Discovery Iot Node Cellular With Bg96" Set Example)
Hardware and software environment setup UM2426 Figure 17 shows the “Discovery IoT node cellular with BG96” set with the B-L475E-IOT01A host, X-NUCLEO-STMODA1 adapter and MB1329 modem boards connected together. Figure 17. Hardware view (“Discovery IoT node cellular with BG96” set example) Summary of environment steps to setup the GroveStreams demonstration: •... - Page 37 UM2426 Hardware and software environment setup • Reboot the board (the trace is displayed in the terminal) • Connect to the GroveStreams account, select the dashboard, double click on sensor, observe the data displayed and the toggling of the LED induced by the GroveStreams dashboard.
-
Page 38: Interacting With The Host Board
Interacting with the host board UM2426 Interacting with the host board To interact with the Host board a serial console is used (Virtual COM port over USB). With ® the Windows operating system, the use of the Tera Term software is recommended. Serial port settings for communicating with the host board are illustrated in Figure 18. -
Page 39: Debug
UM2426 Interacting with the host board Once all terminal and serial port parameters are properly set, press the board reset button (black). The HTTP service is active as soon as STM32 SW is running, sending data to the GroveStreams cloud. The GroveStreams dashboard displays the data values and switches the device LED ON / OFF. -
Page 40: How To Customize The Software
How to customize the software? UM2426 How to customize the software? There are three possible software customization levels applicable to X-CUBE-CELLULAR, which are presented in this chapter: user customization, advanced user customization, and developer customization. This chapter also presents how to monitor thread stack consumption. -
Page 41: Ip Stack On Mcu Side Or On Modem Side
Table 2. Compilation variables for applications in firmware (continued) Compilation variable Description Includes the simulation of sensors (no physical sensor available) Middlewares\ST\STM32_Cellular\Utilities\Tests_Utilities\ #define USE_SIMU_MEMS Src\dc_mems.c. This option can be used also with USE_DC_MEMS defined. It is useful if no sensor shield is plugged. -
Page 42: Different Kinds Of Available Traces
Activate all stimulus ports Press start to display the traces Note: ST-LINK Utility must be connected to the board. It is therefore not possible to debug via the IDE and visualize the ITM trace at the same time. 42/56 UM2426 Rev 5... -
Page 43: How To Configure Traces
How to customize the software? Standard printf traces It is possible to select standard printf traces instead of enhanced UART traces. It uses also the UART connected to the ST-LINK but offer less options and buffers are not displayed. 8.2.4... -
Page 44: Software Customization
How to customize the software? UM2426 8.3.3 Software customization Firmware configuration parameters are included in files: • FreeRTOSConfig.h: includes FreeRTOS™ parameters • lwipopts.h: includes LwIP parameters • plf_hw_config.h: includes HW parameters (such as UART configuration, GPIO used, and others). A change is usually needed to adapt the software to a new board. -
Page 45: Data Cache
UM2426 How to customize the software? Data cache 8.4.1 Introduction The Data Cache allows the sharing of data and events by software components. A software component (producer) creates a data entry and writes data in it. Each data entry is associated to an identifier. The other components (consumers) can read the data by means of the identifier. -
Page 46: Main Data Cache Entries
How to customize the software? UM2426 Register a callback: dc_com_register_gen_event_cb dc_com_reg_id_t dc_com_register_gen_event_cb (dc_com_db_t *dc_db, dc_com_gen_event_callback_t notif_cb, cont void *private_gui_data) • Input: – dc_db: reference to the Data Cache used. Must be set to &dc_com_db – notif_cb: address of callback. This callback is called when a Data Cache entry has been updated. -
Page 47: Thread Stack Consumption Monitoring
UM2426 How to customize the software? Modem target state command Allows the request of a new modem target state. Identifier: DC_CELLULAR_TARGET_STATE_CMD Setting of a new APN configuration Allows setting a new APN configuration. Identifier: DC_CELLULAR_APN_CONFIG Thread stack consumption monitoring The Stack Analysis module enables the monitoring of the thread stack consumption. Each time a thread is created, its registration must be added to Stack Analysis to provide its stack size allocation (this is already done for all the threads declared in the project). -
Page 48: Table 5. Number Of Project Threads Setting Example
How to customize the software? UM2426 Table 5. Number of project threads setting example #define TOTAL_THREAD_STACK_SIZE USED_TCPIP_THREAD_STACK_SIZE +USED_DEFAULT_THREAD_STACK_SIZE +USED_PPPOSIF_CLIENT_THREAD_STACK_SIZE +USED_DC_CTRL_THREAD_STACK_SIZE +USED_ATCORE_THREAD_STACK_SIZE +USED_NIFMAN_THREAD_STACK_SIZE +USED_DC_TEST_THREAD_STACK_SIZE +USED_DC_MEMS_THREAD_STACK_SIZE +USED_DC_EMUL_THREAD_STACK_SIZE +USED_ECHOCLIENT_THREAD_STACK_SIZE +USED_HTTPCLIENT_THREAD_STACK_SIZE +USED_PINGCLIENT_THREAD_STACK_SIZE +USED_FREERTOS_TIMER_THREAD_STACK_SIZE +USED_FREERTOS_IDLE_THREAD_STACK_SIZE +USED_CMD_THREAD_STACK_SIZE +USED_CELLULAR_SERVICE_THREAD_STACK_SIZE To monitor the consumption of the thread stacks during software execution, the lines shown Table 6 are added to StartDefaultTask, at the end of initialization. - Page 49 UM2426 How to customize the software? The monitoring default configuration results in a print of all thread stack size maximum occupation every 5 seconds. For more options regarding the configuration monitoring refer to file stack_analysis.h. UM2426 Rev 5 49/56...
-
Page 50: Appendix A Support Material
Support material UM2426 Appendix A Support material How to configure a GroveStreams account? The different steps are: Create an email account if needed (a valid email account is needed to create a GroveStreams account) Create a GroveStreams account (free sign up) Setup the GroveStreams account (create the organization with the blueprint) Get the needed API keys (used in STM32 MCU FW) The series of figures from... -
Page 51: Figure 22. Grovestreams Organization Access Screen
UM2426 Support material Get access to the organization as shown in Figure Figure 22. GroveStreams organization access screen Prepare to copy the API keys by selecting Admin > API Keys as shown in Figure Figure 23. GroveStreams organization administration menu UM2426 Rev 5 51/56... -
Page 52: How To Activate The Soldered Sim Card
Support material UM2426 Select Feed Put API Key as shown in Figure Figure 24. GroveStreams API key selection screen Select View Secret Key to display the key as illustrated in Figure Figure 25. GroveStreams API key display screen The API key can be copied and pasted as per need. Proceed similarly for the dashboard API key, by un-selecting Feed Put API Key before selecting Dashboard API Key. -
Page 53: How To Select Quectel Bg96 Modem Configuration Bands
Network library API. In case of the X-CUBE-CELLULAR API, each application can register to Data Cache to receive network notifications, and then can be used at the same time as the other applications. -
Page 54: Revision History
UM2426 Revision history Table 7. Document revision history Date Revision Changes 28-Jun-2018 Initial release. X-CUBE-CELLULAR support extended to the “Discovery IoT node cellular” set: – Updated Introduction, Chapter 1: General information, Section 4.2: Modem socket versus LwIP, Chapter 6: Hardware and software environment setup, Section 5.4: Grovestreams (HTTP) access... - Page 55 – Removed Section 4.7:Application LED – Simplified the description of Data Cache in Section 8.4.3: Main Data Cache entries – Removed A.3 Frequently asked questions – Removed A.4 X-CUBE-CELLULAR API descriptions Updated Introduction Chapter 1: General information. Updated Section 4.3.1: Architecture concept, Section 4.3.2: Static architecture...
- Page 56 ST products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgement.
Need help?
Do you have a question about the X-CUBE-CELLULAR and is the answer not in the manual?
Questions and answers