Cellular X-CUBE-CELLULAR How To

Revision as of 06:47, 30 September 2021 by Escoda Michael (talk | contribs)

Click here for Cellular overview

1 How To...

1.1 Introduction

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

1.2 How to start the delivered binary firmware

Binary firmware is provided for each supported board. For example to run the STM32L496 binary for the BG96 modem, follow the steps below:

  1. Insert an activated SIM into the BG96 modem STMod+ board
  2. Plug the BG96 modem board (module up, SIM down) into the STM32L496 board
  3. Plug an USB cable (the one near the blue quad-switch) on the STM32L496 board (-> a new volume (DIS_L496ZG) appears on your PC)
  4. Flash the firmware (drag and drop the .bin onto the newly appearing volume)
  5. Open a TeraTerm serial terminal and set the right parameters (see below: How to setup Teraterm parameters)
  6. If needed (by default it is empty), enter the right SIM APN using the command line

See the following list for details

1.3 How to find the needed delivered binary

All the binaries provided are available here: \Projects\<STM32 board name>\Demonstrations\Cellular\Binaries\
Example: \Projects\32L496GDISCOVERY\Demonstrations\Cellular\Binaries\
Name of the binaries indicate its purpose, <STM32 board>_<modem>_<IP stack>.bin

  • l496_bg96_lwip.bin is the binary for the L496 discovery board associated to the BG96 modem and the IP stack selected is the LwIP in the STM32
  • l496_bg96_socket.bin is the binary for the L496 discovery board associated to the BG96 modem, and the IP stack selected is in the modem.

1.4 How to set up the Teraterm parameters

  • Terminal
    • [New line]
      • [Receive]: Auto
      • [Transmit]: CR
    • [Local echo] selected
  • Serial
    • [Baud rate]: 115200
    • [Data]: 8 bit
    • [Parity]: none
    • [Stop]: 1 bit
    • [Flow control]: none
    • [Transmit delay]: 10 ms each

1.5 How to set up list available CLI commands

Hit "enter" then type "help" then hit "enter" the list of commands is displayed.
Example. List of commands:

  • help: help command
  • trace: trace management
  • comlib: com library commands
  • cst: cellular service task management
  • atcmd: send an at command
  • modem: modem configuration management
  • cellularapp: CellularApp commands
  • echoclient: EchoClient commands
  • ping: Ping commands


So to send an AT command to modem just enter: atcmd AT+QIRC

1.6 How to set up APN using command line

Example: The name of the APN is "em", there is no login or password.
Enter the following commands:

  • cst apnconf em
  • cst targetstate off
  • cst targetstate full

Note: to list all cst command parameter just enter "cst help"
The last 2 commands are used to restart modem to take into account the just defined APN.
If you want to avoid this step, it is easy to modify APN values in the source code and rebuild the firmware. See below for details.

1.7 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.8 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.9 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.10 How to to select components to include in the cellular firmware

The firmware can be customized by adding or removing components or applications.
The configuration files under Projects\<board>\Demonstrations\Cellular\STM32_Cellular\Config allows selection of the component to include in the cellular firmware by define/undefine environment variables (if using CellularApp overwrites configuration by changing the define in plf_cellular_app_config.h).
Refer to the user manual document (UM2426) how to customize the software.

1.11 How to change default behavior of the application

The delivered firmware starts Cellular_App application. The default behavior is that a single echo service is started. This service sends data to an Echo server which replies with the same data. Once an answer from Echo server is received, the echo client resends data to Echo server after a delay. A 2nd instance of the Echo client can be started to test multiple socket configurations. The address of the Echo server can be changed. It is also possible to send a ping command while the Echo client is running. It is also possible to start a perfomance test. To see all the possibilities, type the following in the Tera Term: cellularapp help

1.12 How to implement your own application

The easiest way to implement your application is to adapt the Cellular_App content to your needs.
Another method is to add a new entry task for this new application and start it from main (do not forget to remove entry task start for Cellular_App to avoid conflicts).
Your application is in charge of initializing and starting the Cellular middleware (for this, copy and paste the required lines from Cellular_App).

1.13 How to setup iSIM for GMS01Q

There are 2 STMod+ boards with Monarch Sequans modem, one with GM01Q (the default in the X-CUBE-CELLULAR delivery) and one with GMS01Q.
The GMS01Q is a GM01Q with an iSIM.
To use GMS01Q, a small modification must be made in the source code, .h file.
The file to update is Projects\<board>\Demonstrations\Cellular\STM32_Cellular\Config\plf_cellular_config.h
With <board> = B-L4S5I-IOT01A or 32L496GDISCOVERY or STWINKT1 or ... according the STM32 board with which you are working.
Patch the file as below and rebuild the binary.

  1. define PLF_CELLULAR_SIM_SLOT_NB (1U)
  2. define PLF_CELLULAR_SIM_INDEX_0 (2U) /*!< SIM SLOT 0 interface */
  3. define PLF_CELLULAR_SIM_INDEX_1 (99U) /*!< SIM SLOT 1 interface */
  4. define PLF_CELLULAR_SIM_INDEX_2 (99U) /*!< SIM SLOT 2 interface */
  5. define PLF_CELLULAR_SIM_INDEX_3 (99U) /*!< SIM SLOT 3 interface */


1.14 How to update APN name table

For B-L462E-CELL1 the SW embeds a APN name list. In the case of remote SIM provisioning, it is possible find the APN name automatically.
The user can modify the default APN name list and rebuild the firmware to have their own APN list.

1.15 How to enable Quectel software to change the BG96 modem firmware

To be completed.

1.16 How to manage EEprom on B-L462E-CELL1

The EEprom is filled at Factory process with some data, main information are extract from modem, however a PSK automatically generated is also added. So in case of needs to write the EEprom, backup the parameters to be able to restore them, specially the PSK before. Here is the EEprom first bytes structure (length is 274 bytes):

// Global parameters
uint8_t Board[20]; //={"B-L462-CELL1"};
uint8_t Version [20]; // Version FG displayed on sticker {"EBL462ECELL1$KU4"};
uint8_t Revision [20]; // Revision displayed on sticker {"MB1508-L462E-C01"};
uint8_t Serial[20]; // Serial number displayed on sticker {"K192700022"};
// Modem Related
uint8_t BaseBoard[20];//={"LBAD0XX1SE"};
uint8_t Brand[16]; //={"MURATA"};
uint8_t Model[16]; //={"ALT125X"}; // returned by AT+GMM
uint8_t ModemSoftRevNumber[30]; //={"RK_02_01_02_00_57"} // returned by AT+GMR
uint8_t IMEI[16]; // returned by AT+CGSN
uint8_t PSK[20]; // Pre shared Key - randomly generated
// eSim related
uint8_t eICCID[24]; // EMBEDDED SIM CHIP, returned by AT%CCID
uint8_t eIMSI[16]; // EMBEDDED SIM CHIP, returned by AT+CIMI
uint8_t EID [32];   ///262//270
uint32_t signature;  ///266//274

Note: it is easy to read and write (using HAL services HAL_I2C_Mem_Read / HAL_I2C_Mem_Write) the EEprom after calling the I2C initialization.

1.17 How to activate the eSIM with B-L462E-CELL1

Pre-requisite 1: Check that the country where the board is to run is covered by Truphone Network footprint. You can find the list of covered countries at Truphone Web[1].
Pre-requisite 2: Activate the Truphone eSIM as described in the board user manual. To enable the eSIM with Truphone connectivity, users can follow the instructions provided in the user manual of the B-L462E-CELL1[2] in the chapter eSIM.
This video[3] also shows the user experience available.

Depending on the version of the modem FW configuration, the network operator could be set to "DEFAULT". In some countries, the IMSI switch may not work as expected. To solve the issue, the modem firmware should be configured to use TRUPHONE as network operator. To do the, the end-user is asked to enter the at commands manually as follows:

Step 1: Download the latest version of the X-CUBE-CELLULAR 6.0.0[4].

Step 2: Connect the device to a PC using the STLINK USB Port and program the binary STM32CubeExpansion_CELLULAR_V6.0.0\Projects\B-L462E-CELL1\Demonstrations\CellularIoT\Binaries\L462_iot_t1sc_socket_v600.bin to the board. The procedure to program the binary is defined in this How To article.

Step 3: Start a terminal application on the PC in order to enter commands to configure the device and also to read logs and traces

Step 4: When the board boots up, check that the SIM card is successfully identified and CCID is automatically read and displayed on the terminal

 AT%CCID<CR>
   <CR><LF>
   %CCID: 8944477700000005819<CR><LF>
   <CR><LF>
   OK<CR><LF>



Step 5: Press the "return" key, user should see prompt on the terminal as shown below $>

Step 6: Enter the command "at at%nwoper?", the user should see the result below:

 $>at at%nwoper?
   ATParser:*** SEND (size=11) ***
   at%nwoper?<CR>
   <CR><LF>
   %NWOPER: "TRUPHONE"<CR><LF>
   <CR><LF>
   <CR><LF>
   OK<CR><LF>
 $>



Step 7: If DEFAULT is shown instead of TRUPHONE then enter the AT command at at%nwoper="TRUPHONE" to force the modem firmware to use TRUPHONE configuration. This setting is persistent as it is stored in modem Flash memory.

 $>at at%nwoper="TRUPHONE"
   ATParser:*** SEND (size=21) ***
   at%nwoper="TRUPHONE"<CR>
   <CR><LF>
   OK<CR><LF>



Step 8: Verify that TRUPHONE is correctly written into the Modem Flash Memory by reading the existing nwoper by entering again at at%nwoper. Verify that TRUPHONE is displayed.

Step 9: Now Truphone as NWOPERator is set, user can reboot the board by pressing the reset button (black button) or enter reset command at the prompt

Step 10: After the restart, let Modem starts normally. It automatically searches network and register to Truphone Network. It may take up to 10/15 minutes to find a network and register.

Step 11: If after this the registration is still not successful, record the trace from the terminal and share it with ST support team via ST community.

2 References