Cellular X-CUBE-CELLULAR How To

Revision as of 09:00, 24 November 2020 by Registered User

Click here for Cellular overview

1 How To...

1.1 Introduction

This part is a guideline describing how to perform the main activities with X-CUBE-CELLULAR.

1.2 How to start delivered binary firmware

Binary firmware is provided for each supported board. To run the STM32L496 binary for the BG96 modem, follow the steps below: (Refer to UM2567 Getting started with the X-CUBE-CELLULAR cellular connectivity document for details):

  1. Insert an activated SIM in the BG96 modem
  2. Plug the BG96 modem on a STM32L496 board
  3. Plug an USB cable on the STM32L496 board (-> a new DIS_L496ZG volume appears on your PC)
  4. Flash the 32L496GDISCOVERY firmware
  5. Open a Tera Term serial terminal and set the right parameters
  6. Enter the right SIM APN using the cellular setup menu
  7. Start the firmware.

1.3 How to access the setup menu

The setup menu allows update of the firmware-component parameters - mainly the cellular configuration - as follows: (Refer to UM2567 Getting started with the X-CUBE-CELLULAR cellular connectivity document for details):

  1. Load a cellular firmware into the board Flash memory
  2. Open a Tera Term serial terminal and set the right parameters
  3. Reset the board and
  4. Select Cellular Service in Setup configuration menu
  5. Select the component configuration to update.

Details of menus and parameters are described in the menu Help option.

1.4 How to set the SIM APN using the setup menu

Each operator owns its APN. According to the SIM used, the right APN must be set in the cellular configuration as follows:

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

1.5 How to 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.

1.6 How to know if the modem is correctly configured after the firmware start

  1. Open a Tera Term serial terminal and set the right parameters
  2. Start the firmware
  3. Wait for the trace AUTOM TASK: MODEM_DATA_READY_STATE - NO_EVENT, Network is up is also displayed
  4. The delay depends on the Network attachment duration (from 30 seconds to several minutes).

1.7 How to use console commands to get the modem and cellular network information

  1. Open a Tera Term serial terminal and set the right parameters.
  2. Remove the trace display by typing the commands:
  • trace off
  • cst poll off

Then type the Cellular Service commands:

  • cst
  • cst state
  • cst info
  • cst config

1.8 How to configure the modem radio band

  1. Open a Tera Term serial terminal and set the right parameters
  2. Start the firmware and select Modem power on option in the boot menu
  3. Type the modem command to get help of the modem configuration.

1.9 How to to select components or application to include in the cellular firmware

The firmware can be customized by adding or removing components or applications.
The configuration file plf_custom_config.h allows selection of 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.

1.10 How to select the application to run

By default the delivered firmware contains several applications: HTTP client, ECHO client, and so on.
Only the ECHO client application is activated by default at run time.
To activate/desactivate an application you can use the application's setup menu:

  1. go to the setup menu of application to activate/desactivate
  2. modify parameter: <application> enabled (or not) after boot

1.11 How 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 the Middlewares\ST\STM32_Cellular\Samples\ directory. All these applications can be used as examples. Custom sample is an application template. All basic features are pre-configured (thread, Data Cache notification, commands, and so on). You can develop your own application from this one.

1.12 How to use the MQTT client application

See the detailed description below in this Wiki article.

2 Setup for an MQTT Client application

2.1 Introduction

As this application also involves the cloud, two parts must be updated accordingly: the device (Firmware) part, and the cloud (server and dashboard) part.

2.2 Device side

First, on the device side:

  • If your firmware already has the MQTT application activated, you only have to set up your personal parameter in the firmware (using the boot menu).
  • If your firmware does not yet have MQTT enabled, you must setup some parts in the source and rebuild (see the details below).

During this setup you can choose to keep the default values, or decide to provide your personal values (URL, login, password). If you know your personal values and decide to add them in the source file, you do not have to set them up manually via the boot menu.

2.3 Cloud side

On the cloud side, you have at least two possibilities: a manual setup from scratch, or by using 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: manual setup from scratch, which lasts anywhere from half-an-hour to one hour for advanced users:

  1. setup a server instance on Internet
  2. install the MQTT server
  3. install the NodeRED server
  4. configure NodeRED with the json file provided by STMicroelectronics.

Second solution: this lasts less than 10 minutes, using the pre-installed services from stackhero.io:

  1. connect to https://www.stackhero.io
  2. create an account
  3. create a new stack, give it a name
  4. select Node-RED by clicking on Start Node-RED
  5. select an instance, Hobby is enough for this demo, click on Start now
  6. in your stack you can see the Node-RED instance just created, select it
  7. there are 2 URLs displayed to use first, Node-RED admin console and Node-RED dashboard (logins and passwords are in Configure item)
  8. in one tab of your browser connect to Node-RED admin console, which is used to setup the Node-RED flow
  9. in another tab connect to Node-RED dashboard, which is used to display the dashboard
  10. in the admin console, import the json file provided by STMicroelectronics
  11. optionally delete the empty flow Flow 1
  12. in flow MQTT authentication set your MQTT login and password (into node Users).
  13. Deploy the Node-RED, you can see the dashboard in the Dashboard tab of your browser
  14. note your server address, example mqtts://yayer0.stackhero-network.com:8883/

If 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 authorize stackhero.io as sender.

Note that a delay could occur between server creation and the IP@ becoming available in your DNS. You can either wait, or temporarily replace the URL usage by the IP@.

2.4 Both sides

Whatever the solution chosen, you now need to provide the server parameters to the STM32 firmware. These 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 those values, just use the boot menu.

Note with L496 + BG96 configuration, it is not possible to drive the LEDs from the dashboard.

2.5 How to modify the src files to add the MQTT application in the Firmware

All the information needed 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

The MQTT example is not embedded in the default firmware. However it is quick and simple to do this.