Documentation

Mistake on this page? Email us

Command-line tutorial for Device Management Client with a UNISOC UIS8908A device

This tutorial covers an end-to-end process for the Device Management Client example application:

  1. Configuring Device Management Client.
  2. Compiling Device Management Client.
  3. Connecting to the Device Management service.
  4. Updating firmware to the device.

Versions

This tutorial uses Device Management Client version 4.0.0 or later and UNISOC SDK v8p2.1.

Prerequisites

To work with the Device Management Client example application, you need:

  • UIS8908A board with a network connection (requires SIM card with NB-IoT connectivity).

  • SXOS SDK and its build tools installed and set up.

    Note: For access to UIS8908A evaluation boards and the UNISOC SXOS SDK, contact Unisoc through their overseas.sales@unisoc.com mail address.

  • Serial connection to your device with open terminal connection (baud rate 115200, 8N1).

  • Mbed CLI 1.10.0 or later installed. See installation instructions.

    • All components must fit the requirements in the pip package requirements.txt list from Arm Mbed OS.
  • An API key (with Administrators group privileges) for your Device Management account.

Configuring Device Management Client

  1. Clone the Pelion Device Management Client Example application's GitHub repository to your local computer under the SXOS sdk/soft folder, and navigate to the new folder:

    mbed import https://github.com/ARMmbed/mbed-cloud-client-example
    cd mbed-cloud-client-example
    
  2. Configure Mbed CLI to use your Device Management account and board:

    mbed config -G CLOUD_SDK_API_KEY <API_KEY>
    
    
  3. Use Mbed CLI to download a developer certificate and to create the update-related configuration for your device:

    mbed device-management init -d arm.com --model-name example-app --force -q
    
  4. Configure the NB-IoT bands according to your local regulations.

Compiling Device Management Client

To compile the example application:

cd ../ (navigate back to the `sdk/soft` folder)
export PROJ_ROOT=<SDK root directory>
source /opt/CSDTK/cygenv.sh .
. env/launch.sh
  <select 4 as build target>
  <select defaults (press enter) for rest of the selections>
ctmake -C toolpool/blfota
ctmake dbmerge EXTERNAL_APP_FOLDER=mbed-cloud-client-example DISABLE_DEFAULT_PRINTF=1 MBEDTLS_USER_CONFIG=mbed-cloud-client-example/mbed-cloud-client/mbed-client-pal/Configs/mbedTLS/mbedTLSConfig_SXOS_SW_TRNG.h

Flashing the binary to the device

See SXOS SDK instructions to flash the binary to the device.

Connecting and performing a firmware update on your device

Checking the device connection and obtaining the Device ID

  1. Press the Reset button to restart the device.
  2. Obtain your device's Device ID from device console log.

The terminal gives the following information when the Client has successfully connected:

Client registered
Endpoint Name: <Endpoint name>
Device Id: <Device ID>

To check with Device Management Portal:

  1. Open Device Management Portal.
  2. Navigate to Device directory.
  3. When your devices are listed, they are connected and available.

Your device is now connected and ready for the firmware update.

Updating the firmware

SXOS supports delta updates by default. Create new firmware and obtain the delta package using the SXOS delta generator tool (follow the SXOS SDK instructions).

mbed device-management update device -D <Device ID> -p <delta package file name.lod>

When the update starts, you can see the following log in Client tracing:

Firmware download requested
Authorization granted
Downloading: [++++++++++++++++++++++++++++++++++++++++++++++++++] 100 %
Download completed
Firmware install requested
Authorization granted

After this, the device reboots automatically and registers to Device Management.

Setting LTE bands to SXOS NB-IoT

The SXOS build of the mbed-cloud-client-example application uses NB-IoT. Before using it, you must configure the module to use correct LTE bands according to your country regulations.

  • An example on reading the current band configuration from the NB-IoT module:

    #include <cs_types.h>
    
    extern void nbiot_nvGetSupportBand(u8 *pBandNum, u8 band[]);
    
    void get_sxos_band(void) {
    
        UINT8 band[7] = {0};
        UINT8 bandNum = 0;
    
        /* Get current band config */
        nbiot_nvGetSupportBand(&bandNum, band);
    }
    
  • An example on setting up the bands to the NB-IoT module:

    #include <cs_types.h>
    
    extern void nbiot_nvSetSupportBand(u8 bandNum, u8 band[]);
    extern void nbiot_nvSetSwitchBs(u8 switchBs);
    extern int nvmWriteStatic(void);
    
    void set_sxos_band(void) {
    
        // Set bands 3 and 20
        UINT8 band[7] = {3, 20, 0, 0, 0, 0, 0};
        UINT8 bandNum = 2;
        UINT8 switchBs = 1;
    
        // Enable LTE bands 3 and 20
        // AT+NVSETBAND=2,3,20
        nbiot_nvSetSupportBand(bandNum, band);
        nvmWriteStatic();
    
        // AT+NVSWITCHBS=1
        nbiot_nvSetSwitchBs(switchBs);
        nvmWriteStatic();
    }
    

Note: Restart the board after switching the band.