Cellular X-CUBE-CELLULAR

This message will disappear after all relevant tasks have been resolved.

Semantic MediaWiki

There are 1 incomplete or pending task to finish installation of Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.

Coming soon

Click here for Cellular overview

1. What is X-CUBE-CELLULAR

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

SW Architecture diagram of Cellular stack

2. 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
To activate HTTP http on (http off to stop it)
To activate MQTT, see dedictaed chapter
To activate COM XXX
To activate CUSTOM XXX

3. Setup for MQTT Client application

3.1. Introduction

As this application involves also the cloud, so 2 parts must be updated accordingly, the device (FW) and the cloud (Server & Dashboard)

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

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

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

3.5. How to modify the src files to add MQTT application in the FW

Indeed by default MQTT application is embedded in the default FW. However it is quick and simple to do this.

3.5.1. Remove "Exclude from build" option for the following components of the IAR project

Application/MQTT
Middleware/NetworkLibrary
Middleware/Modules/MbedTLS_Wrapper
Middleware/Third_Party/LiamBindle_mqtt-c
Middleware/Third_Party/LMbedTLS

3.5.2. Define following Constants in mqttclient_conf.h

Replace:

#define MQTTCLIENT_DEFAULT_SERVER_NAME ((uint8_t *)"<TO_BE_DEFINED>") /* mqtt server URL */
#define MQTTCLIENT_DEFAULT_USERNAME ((uint8_t *)"<TO_BE_DEFINED>") /* mqtt server user name */
#define MQTTCLIENT_DEFAULT_PASSWORD ((uint8_t *)"<TO_BE_DEFINED>") /* mqtt server password */

By:

#define MQTTCLIENT_DEFAULT_SERVER_NAME ((uint8_t*)"yayer0.stackhero-network.com") /* mqtt server URL */
#define MQTTCLIENT_DEFAULT_USERNAME ((uint8_t *)"user1") /* mqtt server user name */
#define MQTTCLIENT_DEFAULT_PASSWORD ((uint8_t *)"123abc") /* mqtt server password */

3.5.3. Root CA

ROOT CA for MQTTS Server authentication must be updated it is in mqttclient_conf.h

#define MQTTCLIENT_ROOT_CA = {...}

Note that in the FW, embedded CA certificate is the one that allows to verify stackhero.io certificate. By accessing another MQTT server with TLS an error is displayed but does not prevent to use the MQTT application. To retrieve this error message only update the source file with the correct CA certificate and rebuild the FW.

3.5.4. define to setup

Set following variables in plt_features.h:

#define USE_MQTT_CLIENT (1)
#define USE_COM_PING (1)
#define USE_CMD_CONSOLE (1)
# define USE_RTC (1)
#define USE_DC_GENERIC (1)

Following components must be unset:

#define USE_ECHO_CLIENT (0)
#define USE_HTTP_CLIENT (0)
#define USE_COM_CLIENT (0)
#define USE_CELPERF (0)
#define USE_PING_CLIENT (0)
#define USE_DEFAULT_SETUP (0)

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