|
Coming soon |
Click here for Cellular overview
1 Introduction
This wiki page contains the information to ease the user's trip in ST Cellular software. When the information is already present in a databrief or a user manual, this wiki only redirects on those reference documents. So this wiki does not contain all the information but help you to find it.
2 What is X-CUBE-CELLULAR
What is X-CUBE-CELLULAR used for ? It is used to allow applications to send and receive data on the cellular network using BSD API sockets.
Do not forget the official web page on X-CUBE-CELLULAR on st.com. You will have access to multiple resources (software, documents, ...). The current version is the V5.1.0.
The X-CUBE-CELLULAR consists of a set of libraries and application examples for STM32L4 Series MCUs acting as hosts for cellular connectivity applications.
The colors help to understand the different parts, Green for applications, light Blue for Middlewares, dark Blue for HAL, Purple for hardware.
Note that above the Cellular Middleware there is the Network_Library Middleware, it abstracts the cellular, Wifi, Ethernet ... So an application using Network_Library APIs, running on a bearer can be easily ported on another technology. Also note it is not mandatory to use Network_Library APIs, an application only using cellular can directly use X-CUBE-CELLULAR APIs.
3 Provided applications
Several applications are provided as examples:
- The PING client application to test the access to a remote machine
- The ECHO client application to provide an example of connection and data exchanges using the TCP or UDP (connected or not-connected mode) socket protocols
- The HTTP client application to exchange data between the device and the cloud using the HTTP protocol
- The MQTT client application to exchange data between the device and the cloud using the MQTT protocol (it uses TCP)
- The COM client application to test the access to COM library services such as read information from ICC
- The CUSTOM client application, an empty application already pre-integrated in X-CUBE-CELLULAR. It is provided to ease customers development.
By default, only one application is started at boot: ECHO client.
Indeed PING client is more a command than an application so it starts when the command is entered.
It is the same for COM client, it is a command.
HTTP client is by default stopped, to start it just enters the following command: http on (http off to stop it).
CUSTOM client must be activated with the compilation switch, once activated by default this application only displays a message in which the user may add his own content.
MQTT client is more complicated to activate because it uses Network_Library and MbedTLS Middlewares but it is easy following the README.txt. See below more details about MQTT client.
The X-CUBE-CELLULAR also contains modular tools like Command (to interact with the firmware through the terminal) and setup menu (to set parameters in the firmware to avoid a new compilation).
4 What is the Getting started user manual
This user manual is a simple and short document to read first. It explains the basis: to connect the hardware, to activate the eSIM, to program the firmware on the board and to run it; all this information in less than 10 pages.
5 How To ...
5.1 Introduction
This part is a guideline to describe How To make main activities with X-CUBE-CELLULAR.
5.2 ... start delivered binary firmwares
A binary firmware is provided for each supported board. To run the STM32L496 binary for the BG96 modem, follow the next steps (Refer to UM2567 Getting started with the X-CUBE-CELLULAR cellular connectivity document for details):
- insert an activated SIM in the BG96 modem
- plug the BG96 modem on a STM32L496 board
- plug an USB cable on the STM32L496 board (-> a new DIS_L496ZG volume appears on your PC)
- flash the 32L496GDISCOVERY firmware
- open a Tera Term serial terminal and set the right parameters
- enter the right SIM APN using the cellular setup menu
- start the firmware
The setup menu allows to update parameters of the firmware component and mainly the cellular configuration (Refer to UM2567 Getting started with the X-CUBE-CELLULAR cellular connectivity document for details):
- to load a cellular firmware in the board Flash memory
- to open a Tera Term serial terminal and set the right parameters
- to reset the board and
- to select Cellular Service in Setup configuration menu
- to select the component configuration to update.
The detail of menus and parameters are described in the Help option of the menus.
Each operator owns its APN. According to the SIM used, the right APN must be set in the cellular configuration:
- start the setup menu (see above)
- select Cellular Service in Setup configuration menu
- type c to update the configuration then the version number displayed
- for each parameter (except APN), type enter to keep the default value (until the last parameter)
- for the APN parameter, type the right APN value (refer to SIM card)
- start the firmware
5.5 ... set the SIM APN by updating the plf_cellular_config.h file
According to the SIM/operator used, the cellular parameters can be updated in the plf_cellular_config.h file that contains all the configurable cellular service parameters.
5.6 ... know if the modem is correctly configured after the firmware start
- open a Tera Term serial terminal and set the right parameters
- start the firmware
- wait for the trace AUTOM TASK: MODEM_DATA_READY_STATE - NO_EVENT
- The delay depends on the Network attachment duration (from 30 seconds to several minutes).
5.7 ... to use console commands to get the modem and cellular network information
- open a Tera Term serial terminal and set the right parameters.
- remove the trace display by typing the commands:
- trace off
- cst poll off
- type the Cellular Service commands:
- cst
- cst state
- cst info
- cst config
5.8 ... to configure the modem radio band
- open a Tera Term serial terminal and set the right parameters.
- start the firmware and select Modem power on option in the boot menu
- type modem command to get help of the modem configuration.
5.9 ... to select components or application to include in the cellular firmware
The firmware can be customized by adding or removing some components or applications.
The configuration file plf_custom_config.h allows to select the component to include in the cellular firmware by define/undefine environment variables.
Refer to the user manual document (UM2426) how to customize the software.
5.10 ... to select the application to run
By default the delivered firmware contains several applications: HTTP client, ECHO client, ...
Only the ECHO client application is activated by default at run time.
To activate/desactivate an application you can use the setup menu of the application.
- go to the setup menu of application to activate/desactivate
- modify parameter: <application> enabled (or not) after boot
5.11 ... to add a personal application
Refer to the user manual document (UM2426) How to customize the software for details. The sample applications are present in Middlewares\ST\STM32_Cellular\Samples\ directory. All these applications can be used as example. Custom sample is a template of application. All basic features are pre-configured (thread, Data Cache notification, commands, ...). You can develop your own application from this one.
5.12 ... to use the MQTT client application
See the detailed description below in this Wiki.
6 Setup for MQTT Client application
6.1 Introduction
As this application involves also the cloud, so two parts must be updated accordingly, the device (Firmware) part and the cloud (server and dashboard) part.
6.2 Device side
First, on the device side, either your firmware has already the MQTT application activated or not.
- In case your firmware has the MQTT application activated, you only have to setup your personal parameter into the firmware (using the boot menu).
- If your firmware is not yet MQTT enabled you must setup some parts in the source and rebuild (see details below).
During this setup you can choose to keep the default values or decide to already provide your personal values (URL, login, password). If you know your personal values and decide to add them into the source file, avoid to setup them manually at boot thanks to the boot menu.
6.3 Cloud side
On the cloud side, you have at least two possibilities: a manual setup from scratch or the use of services that pre-install some configurations.
You can open this link and copy/paste the content (CtrlA/CtrlC/CtrlV) to be used as .json template (import) for your NodeRED dashboard. It is Copyright (c) 2020 STMicroelectronics, BSD 3-Clause link on license here.
First solution: a manual setup from scratch which lasts anywhere from half an hour to one hour for advanced users:
- setup a server instance on Internet
- install the MQTT server
- install the NodeRED server
- configure NodeRED with the json file provided by STMicroelectronics.
Second solution: which lasts less than 10 mn, using the pre-installed services from stackhero.io:
- connect to https://www.stackhero.io
- create an account
- create a new stack, give it a name
- select Node-RED by clicking on Start Node-RED
- select an instance, Hobby is enough for this demo, click on Start now
- in your stack you can see the Node-RED instance just created, select it
- there are 2 URLs displayed to use first, Node-RED admin console and Node-RED dashboard (logins and passwords are in Configure item)
- in one tab of your browser connect to Node-RED admin console, used to setup the Node-RED flow
- in another tab connect to Node-RED dashboard, used to display the dashboard
- in admin console import the json file provided by STMicroelectronics
- optionally delete the empty flow Flow 1
- in flow MQTT authentication set your MQTT login and password (into node Users).
- Deploy the Node-RED, you can see the dashboard in the Dashboard tab of your browser
- note your server address, example mqtts://yayer0.stackhero-network.com:8883/
In case you do not receive an email from stackhero to validate your account the reason could be that your email server blocks it. To solve this, just whitelist stackhero.io
Note a delay could occurs between server creation and IP@ available in your DNS, so you have to wait or URL usage could be temporarily replaced by the IP@.
6.4 Both sides
Whatever the solution chosen, you now need to provide the server parameters to the STM32 firmware. Those parameters are URL (something like yayer0.stackhero-network.com for stackhero solution or another url), user name and user password (just set into Users node). To update the firmware with thoses values, just use the boot menu.
Note with L496 + BG96 configuration, it is not possible to drive the LEDs from the dashboard.
6.5 How to modify the src files to add the MQTT application in the Firmware
All the needed information for this can be found in the Readme file located in the zip file. The exact location is: \Middlewares\ST\STM32_Cellular\Samples\MQTT\README.txt
Indeed, the MQTT example is not embedded in the default firmware. However it is quick and simple to do this.
7 FAQ
| Questions | Answers |
|---|---|
| How to start | Read UM2567: Getting started and UM2426 for detailed explanations. |
| Where to find the blueprint file for creating a Grovestreams organization? | In \Middlewares\ST\STM32_Cellular\Samples\HTTP\Setup\Grovestreams_Blueprint.txt. |
| Where to find the text file for updating Grovestreams parameters? | In \Middlewares\ST\STM32_Cellular\Samples\HTTP\Setup\Grovestreams_Setup.txt. |
| How to know if the cellular application is up and running? | With the trace on Tera Term. |
| Nothing is displayed in Tera Term. | Ensure that Tera Term options (such as Baud rate) are correctly set. |
| Wrong echo in Tera Term during setup. | Ensure that Tera Term options (such as New-line and Transmit delay) are correctly set. |
| It boots but there is an issue with the network. | Check that the correct SIM is selected (Plastic SIM or soldered UICC; Plastic SIM by default). |
| How to check that the EMnify profile on UICC is correctly activated? | Connect to the EMnify account and check the status. |
| EMnify is correctly activated but it does not work. | Check in the EMnify account if the correct tariff is selected. |
| The log indicates it is properly up and running but nothing change on Grovestreams dashboard. | Check that the correct API keys are used (the ones associated with the organization used for the demonstration). |
| The voucher cannot be read because the initial image was overwritten (only for CELL01 and CELL02 kits). | Browse to www.stm32-c2c.com, then download Restore factory firmware and flash it. |
| With the out-of-the-box FW, there is no information on the console. | Set the correct parameter in Tera Term (Baud rate as 9600 to obtain the voucher) and make sure that the modem is not connected upside-down to the host board through the STMod+ connector. |
| Why cellular does is not operational after boot? | There are multiple possibilities: the selected firmware does not correspond to the modem used, the SIM card used is not valid on the available network, the modem firmware version release note, too many bands selected and parsed by the modem (see UM2567). |
| How to know if the cellular data service is operational | Cellular operational after Trace displays -----> State : CST_MODEM_DATA_READY_STATE <----- |
| How to activate a 2nd C2C kit | Once registered on www.stm32-c2c.com note the BIC and connect directly on your EMnify account and add the SIM with the BIC. |
| What is the BIC | It is not a bank number but only a Batch Identifier Code used at the SIM creation. |
| Which modem FW version | In case you use a different modem FW than the one used in tests you can have discrepancies. Read carefully the modems Release Note for detailed information. |