|
Coming soon |
Click here for Cellular overview
1. Introduction
This wiki page contains information to ease user's trip in ST Cellular SW. When information are already present in Data Brief or User Manual, this wiki only redirect on those reference documents. So this wiki does not contains all the information but help you to find it.
2. What is X-CUBE-CELLULAR
What does X-CUBE-CELLULAR is used for ? It is used to allow applications to send & receive data on 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 ressources (SW, doucments, ...)
X-CUBE-CELLULAR consists of a set of libraries and application examples for STM32L4 Series MCUs acting as hosts for cellular connectivity applications.
3. Provided applications
Several applications are provided as examples:
- PING Client application to test the access to a remote machine
- ECHO Client application to provide an example of connection and data exchanges using the TCP or UDP (connected or not-connected mode) socket protocols
- HTTP Client application to exchange data between the device and the cloud using HTTP protocol
- MQTT Client application to exchange data between the device and the cloud. On the cloud side, a dashboard is the interface with the end user
- COM Client application to test the access to other services than sockets provided by the COM library (such as read information from ICC)
- 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 activated; ECHO Client. For the others applications:
- To activate PING XXX dfsdfsdsgsdg sdgsd gs
- To activate HTTP http on (http off to stop it)
- To activate MQTT, see dedictaed chapter
- To activate COM XXX
- To activate CUSTOM XXX
4. What is the Getting started User Manual
This User Manual is an easy and quick document to read first. It explains the basis, Connect the HW, Activate the eSIM, Program the FW on the board and run it; all this in less than 10 pages.
5. How To ...
5.1. Introduction
This part is a guide to describe How To make main activities with x-cube-cellular
5.2. ... start delivered Firmware binaries
A Firmware binaries is provided for each supported board. Summary to run the STM32L496 binary for BG96 modem follow the next steps: (Refer to "Getting started with the X-CUBE-CELLULAR cellular connectivity" (UM2567) 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_L498ZG volume appears on your PC)
- flash the 32L496GDISCOVERY firmware
- open a teraterm serial terminal and set the right parameters
- enter right SIM APN using cellular setup menu
- start the Firmware
The setup menu allows to update parameters of Firmware component and mainlycellular configuration (Refer to "Getting started with the X-CUBE-CELLULAR cellular connectivity" (UM2567) document for details)
- flash a cellular firmware in a Board.
- open a open a teraterm serial terminal and set the right parameters.
- reset the board and press '2' on keyboard to enter in setup menu
- select the component configuration to update
- the detail of menus and parameters is described in the Help option of the menus
Each operator own 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 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)
- launch 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 have to be updated plf_cellular_config.h file contains all the configurable cellular service parameters
5.6. ... know if the modem correctly configured after Firmware start
- open a open a teraterm serial terminal and set the right parameters.
- start the firmware
- wait for the trace "AUTOM TASK: MODEM_DATA_READY_STATE - NO_EVENT"
- The delay depend on Network attachment duration (from 30s to several minutes)
5.7. ... to use console command commands to get modem and cellular network information
- open a open a teraterm serial terminal and set the right parameters.
- remove trace display by typing commands
trace off cst poll off
- type the Cellular Service commands
cst cst state cst info cst config
5.8. ... to configure modem radio band
- open a open a teraterm serial terminal and set the right parameters.
- star firmware and select "Modem power on" option in the boot menu
- type 'modem' command to get help of modem configuration
5.9. ... to select components or application to include in cellular Firmware
The firmware can be customized by adding or removing some compoenets or application. The configuration file plf_custom.h allows to select the component to include 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: httpclient, echoclient,... Only echoclient application is activated by default at run time. To activate/desactivate an application you can use the setup menu of the application.
- go to 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 Sample application are present in Middlewares\ST\STM32_Cellular\Samples\ directory All these application can be used as example. Custom is a template of application. All basic feature are pre-configured (thread, Data Cache notification, commands, ...) You can develop your own application from this one.
5.12. ... to use MQTT client application
see description in the next part
6. Setup for MQTT Client application
6.1. Introduction
As this application involves also the cloud, so 2 parts must be updated accordingly, the device (FW) and the cloud (Server & Dashboard)
6.2. Device side
First, device side, either your FW already have the MQTT application activated or not. In case your FW have MQTT activated, you will only have to setup your personal parameter to the FW (thanks boot menu). If your FW is not yet MQTT enabled you must setup some parts in the source and rebuild (details below). During this setup you can choose to keep 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 you will avoid to setup them manually at boot thanks the boot menu.
6.3. Cloud side
Cloud side, you have at least 2 possibilities, manual setup from scratch or use services that pre-install some configurations.
First solution, manually from scratch, 1/2 to 1h, for more advanced users:
- setup a server instance on Internet
- install MQTT server
- install NodeRED server
- configure NodeRED with json file provided by STMicroelectronics
2nd solution, 5mn, use 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 you 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 json file provided by STMicroelectronics (located into Utilities/MQTT/)
- delete the 2 existing Flows ("MQTT Auntentication" & "Flow 1")
- 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/
Note that flows.json file is located here: Utilities/MQTT/flows.json in the X-CUBE-CELLULAR zip file. In this .json file we setup for user a default user & password, it is "user1" and "123abc", advice is to change it.
In case you don't receive email from stackhero to validate you account the reason could be that your server email blocks it. To solve this juts whitelist "stackhero.io"
Some video that illustrates the previous cloud steps with stackhero solution:
How to create Node RED instance with Stackhero.io
How to import json file in Node RED
How to deploy and use the dashboard
Where are MQTT login and password in Node RED
6.4. both sides
Whatever the solution you choose, you now need to provide server parameters to the STM32 FW. Those parameters are URL (something like yayer0.stackhero-network.com for stackhero solution or another url) user name (default is "user1") and user password (default is "123abc") To update FW with thoses values, use the boot menu.
6.5. How to modify the src files to add MQTT application in the FW
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 by default MQTT application is not embedded in the default FW. However it is quick and simple to do this.
7. FAQ
| Questions | Answers |
|---|---|
| How to start | Read UM 2567: 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 Teraterm. |
| Nothing is displayed in Teraterm. | Ensure that Teraterm options (such as Baud rate) are correctly set. |
| Wrong echo in Teraterm during setup. | Ensure that Teraterm 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 Teraterm (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, SIM card used is not valid on the available network, the modem firmware version see release note, too many bands selected and parsed by 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 register on www.stm32-c2c.com note the BIC and connect directly on your EMnify account and ad the SIM with the BIC |
| What is the BIC | It is not a bank number but only a Batch Identifier Code use at SIM creation |