Documentation

Mistake on this page? Email us

Command-line tutorial for Renesas SDK with Pelion Device Management

This tutorial shows how to securely connect and update a Renesas EK-RA6M3 device to Device Management built with Renesas SDK over an IP connection.

This tutorial uses Linux PC (64-bit Ubuntu/XUbuntu OS desktop environment) for compilation and Windows 10 for programming the target board.

Prerequisites

To use this tutorial, you need:

  • Segger J-Flash LITE tool recommended for erasing and programming.

  • Secure boot example v1.1.0 from Renesas.

    • The Secure boot example contains its own Python requirements file in ./r01an5347eu0110-ra-arm-secure-boot-solution-ra6m3/SecureBoot_Package/scripts/dependency/requirements.txt.
  • Configure MACRO for the compiler, for example:

    export ARMGCC_DIR=/usr/local/gcc-arm-none-eabi-9-2019-q4-major
    
  • An API key with Administrators group privileges for your Device Management account.

    Note The tooling does not yet support the application access key that replaces the API key.

For all other requirements, see the tools and account section. See also the Mbed CLI instructions.

Configuring Device Management Client

  1. Open a terminal, and import the example repository to a convenient location in your development environment:

    mbed import https://github.com/ARMmbed/mbed-cloud-client-example
    
  2. Download the developer certificate:

    1. Log in to Device Management Portal.
    2. Navigate to Device identity > Certificates.
    3. Click Actions > Create a developer certificate.
    4. Add a name and optional description to the certificate, and click Create certificate.
    5. Click Download Developer C file to download the file mbed_cloud_dev_credentials.c.
  3. Copy the mbed_cloud_dev_credentials.c file to the root folder of the example.

  4. Initialize the firmware-update-specific resources:

    manifest-tool init -a <api_key> -d arm.com -m example-app --force -q
    

    Replace the <api_key> with your own API key.

  5. Deploy the remaining dependencies and configuration:

    python pal-platform/pal-platform.py deploy --target Renesas_EK_RA6M3 generate
    

    Note: There is a known issue in the deployment of CMSIS_5 package. If pal-platform fails with returned non-zero exit status 128 error, try disabling Git-LFS smudge filter by defining the environmental variable GIT_LFS_SKIP_SMUDGE=1.

Compiling and programming Device Management Client

  1. Run CMake and Make to compile the application:

    cd __Renesas_EK_RA6M3
    cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=./../pal-platform/SDK/Renesas_EK_RA6M3/ARMGCC.cmake -DEXTERNAL_DEFINE_FILE=./../define_Renesas_EK_RA6M3_update.txt -DUPDATE_LINKING=1
    make mbedCloudClientExample.elf
    cd ..
    
  2. Combine the image with Renesas SecureBoot:

    1. Obtain the Secure boot example from Renesas, and unpack the program package. Your work area should look like:
    my_apps/mbed-cloud-client-example
    my_apps/r01an5347eu0110-ra-arm-secure-boot-solution-ra6m3
    
    1. Go to the mbed-cloud-client-example folder for execution of the imgtool.py.
    • imgtool.py and flash_layout.h are part of the Secure boot example.
    • imgtool.py has been tested with cryptography==2.8.0.
    python ../r01an5347eu0110-ra-arm-secure-boot-solution-ra6m3/SecureBoot_Package/scripts/image_creation/imgtool.py sign --layout ../flash_layout/flash_layout.h  --align 8 --header-size 0x400 __Renesas_EK_RA6M3/Release/mbedCloudClientExample.bin mbedCloudClientExample_signed.bin -k ../r01an5347eu0110-ra-arm-secure-boot-solution-ra6m3/SecureBoot_Package/scripts/image_creation/Signing_Key/signingkey.pem
    
    • __Renesas_EK_RA6M3/Release/mbedCloudClientExample.bin is the output image from make.
    • mbedCloudClientExample_signed.bin is the output created by imgtool.py.
  3. Collect the images needed for programming:

    The secure bootloader binary is in ./SecureBoot_Package/scripts/downloader/BL2_download/Secureboot_EK_RA6M3.bin in the r01an5347eu0110-ra-arm-secure-boot-solution-ra6m3 folder.

    You need these two files for programming:

    Secureboot_EK_RA6M3.bin
    mbedCloudClientExample_signed.bin
    

We recommend you use Segger J-Flash Lite application for erasing and flashing.

  1. Program with the J-Flash Lite GUI application:

    In the Segger J-Flash Lite:

    1. Target device should be auto-detected to be R7FA6M3AH.
    2. Click the Erase Chip button to erase the flash.
    3. Program the Secureboot_EK_RA6M3.bin.
    4. Program the mbedCloudClientExample_signed.bin at address 0x10000.
  2. Flash with J-Link command-line tools:

    Note: Perform the flashing operations with Windows GUI tools as the command-line tools in both Windows and Linux are not reliable with this target.

    1. Open in one terminal window:

      JLink -device R7FA6M3AH -AutoConnect 1 -if SWD -speed auto
      
    2. Execute in JlinkExe command-line window:

      Note the address for the application image.

      erase
      loadfile Secureboot_EK_RA6M3.bin
      loadfile mbedCloudClientExample_signed.bin 0x10000
      

Starting the application and viewing the console logs

  1. Open the JLink debugger in one terminal window:

    JLink -device R7FA6M3AH -AutoConnect 1 -if SWD -speed auto
    
  2. Start JLinkRTTViewer in a another terminal window to access device logs:

    JLinkRTTViewer -d R7FA6M3AH -ct sess -a
    

When the client has successfully connected, the terminal shows:

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

To verify the connection with Device Management Portal:

  1. Log in to Device Management Portal.
  2. Select Device directory from the menu on the left.
  3. When your device is listed on the Devices page, it is connected and available.

Your device is now connected and ready for firmware update. For development devices, the Endpoint name and Device ID are identical.

Updating the firmware

To update the firmware on your device, run:

manifest-tool update device -p mbedCloudClientExample_signed.bin -D <Device ID>

Note: The update image also must be signed the same way as the original programmed image.

When the update starts, the client tracing log shows:

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.

Debugging

If you encounter this issue with J-Link commands:

****** Error: SC32 (connect): Failed to authenticate debugger via IDCODE. Incorrect IDCODE?

Power down the device for a few minutes.