The SDK and Its Tools¶
Building ICI Applications¶
Please follow the RIIM SDK Quick Start Guide for creating your first ICI application.
The ICI user application is edited in your favorite text editor, and compiled by invoking a simple script. The compiler used underneath is GCC, a well known compiler. The user doesn’t need to be familiar with compiler tools and configurations, as everything is taken care of by the scripts provided from Radiocrafts.
Workflow using RIIM SDK¶
The development tools runs on both Linux-like systems and Windows. Radiocrafts provides a complete development environment with everything that’s needed that the user can download. Please see SDK Setup on how to install the development environment. In the following examples, Linux is used. For Windows, substitute the “dev/ttyUSB0” with your associated COM port (for example “COM3”).
Creating a new project¶
The simplest way to start a new project, is simply to duplicate the RIIM_SDK/ICI_Applications/My_App folder. This creates a new project with three almost empty C files. There is no need to modify any of the files.
Using CMake¶
The build system is using CMake and Ninja, but the user doesn’t need to know how they work. The user can simply use the Compile_And_Upload.bat or Compile_And_Upload.sh to build and upload all files in the SRC folder automatically. Alternatively, if using Visual Studio Code, building and uploading of a single file can be done by simply pressing CTRL-SHIFT-B as described Building and Uploading Using VSCode
However, if the user wants to change the behavior, it can be done by editing the CMakeLists.txt files. There is one in the project folder itself, and another one in RIIM_SDK/Framework/Tools .
Manual building is done by invoking these two commands:
cmake --fresh -G"Ninja" -S"./SRC" -B"./Output" -D"SOURCE_FILE=YOUR_FILE.c"
cmake --build ./Output
This will generate ./Output/YOUR_FILE.bin that the user can use to flash the module
Using tools¶
A set of tools that’s part of the SDK and the ARM compiler is available. You can just use the tools directly or in your own scripts. The tools are located at RIIM_SDK/Framework/Tools . Below is a couple of examples executed from the SDK path RIIM_SDK/ICI_Applications/My_App :
This loads the image App_Router.bin onto the module connected to serial port ttyUSB0
python ../../Framework/Tools/rc188x_bootloader_utility.pyz load-image -f Output/App_Router.bin -p /dev/ttyUSB0
This loads a new platform (the Border Router platform) onto the module connected to serial port ttyUSB0
python ../../Framework/Tools/rc188x_bootloader_utility.pyz load-image -f ../../Framework/Platform/Output/RIIM_Platform_BorderRouter_0x010000.bin -p /dev/ttyUSB0
For all the tools, it’s possible to specify the –help switch to get help, like this:
python ../../rc18xx_bootloader_utility.pyz --help
Usage: python -m rc18xx_bootloader_utility [OPTIONS] COMMAND [ARGS]...
Main function
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
info Print module info.
load-app-image-key Load ICI application key
load-image Load image onto module
load-network-key Load default network key
lock Lock the module
run-app Exit BSL and start ICI application and platform
For detailed help on any commands, specify the command before the –help like this
python rc18xx_bootloader_utility.pyz load-image --help
Usage: python -m rc18xx_bootloader_utility load-image [OPTIONS]
Load image onto module
Options:
-p, --port TEXT Serial port, e.g. COM12 or /dev/ttyUSB0
-t, --timeout INTEGER Timeout (in seconds) for trying to connect to
bootloader. Default is 10 seconds
-f, --file TEXT Image file
--help Show this message and exit.
Similarly, for the image generator:
../../Framework/Tools/rc188x_image_generator --help
RC188x Image Generator
usage: RC188X Image Generator [-h] [--app_version] [-p PLATFORM]
[-hw HARDWARE] [-r HARDWARE_REV]
[-t {app,platform}] [-v VERSION] [-erase_nv] -f
HEXFILE [-k KEYFILE] [-n NONCE]
optional arguments:
-h, --help show this help message and exit
--app_version show program's version number and exit
-p PLATFORM, --platform PLATFORM
Platform ID. Example: 00A1
-hw HARDWARE, --hardware HARDWARE
Hardware ID. Example: 00B0
-r HARDWARE_REV, --hardware_rev HARDWARE_REV
Hardware Revision. Example: 0001
-t {app,platform}, --image_type {app,platform}
Image type [app, platform]
-v VERSION, --version VERSION
Image version. Format is hexadecimal 0xMMmmPP.
MM=Major version, mm=minor version, PP=patch version.
Example 0x010A04
-erase_nv Erase NV memory
-f HEXFILE, --hexfile HEXFILE
Input hex file
-k KEYFILE, --keyfile KEYFILE
Key file. File must contain 16 byte hex string.
-n NONCE, --nonce NONCE
Nonce. Must be 11 byte hex string starting with 0x.
Example: 0x112233445566778899AABB
~/dev/RIIM_SDK/ICI_Applications/My_App$
Encrypting the ICI User Application¶
The ICI user application can be encrypted to protect the users Intellectual Property and secure the product from fraudulent software. To enable encryption of the ICI user application, two criteria must be met:
The encryption key must be programmed into the bootloader
The ICI user application image must be created with the same key
This is achieved using the image generator provided with the SDK from Radiocrafts. The example assumes that there exist a key file called Application.key in the same folder as the ICI application. The following sequence must be followed after building the project (see Building and Uploading Using VSCode and Building and Uploading Using Scripts):
python ../../Framework/Tools/rc18xx_bootloader_utility.pyz load-app-image-key -f Application.key -p /dev/ttyUSB0
<USER MUST RESET THE MODULE>
../../Framework/Tools/rc188x_image_generator -k Application.key -t app -p 2 -hw 2 -f "./Output/YOUR_FILE.hex"
python ../../Framework/Tools/rc18xx_bootloader_utility.pyz load-image -f "$(OUTPUT_FILENAME).bin" $(PORT_Param)
<USER MUST RESET THE MODULE>
The file Application.key must be a single file containing only the 16 character encryption key only.
Locking the module¶
Locking the module means that no one can upload unencrypted images to the module anymore. This feature helps protect the ICI application and isn’t reversible. It may be feasible to not lock the module if the user is actively developing on the module. Locking should be done before shipping the product to disable possible tampering.
python ../../Framework/Tools/rc18xx_bootloader_utility.pyz lock -p /dev/ttyUSB0
<USER MUST RESET THE MODULE>
Read out the module serial number¶
Each module has a unique serial number that can be read out. This is done by using the bootloader utility like this:
python ../../Framework/Tools/rc188x_bootloader_utility read-serial -p /dev/ttyUSB0
<USER MUST RESET THE MODULE>
Selecting and Updating the Platform¶
The SDK also contains the platforms as encrypted binaries. The platform images are located at RIIM_SDK/Framework/Platform/Output . 3 platform types exists:
RIIM_Platform_MeshRouter_0xXXXXXX-YYYY.bin - For Mesh Router
RIIM_Platform_BorderRouter_0xXXXXXX-YYYY.bin - For Border Routers
RIIM_Platform_Leaf_0xXXXXXX-YYYY.bin - For low power Leaf
Here, XXXXXX denotes the platform version (for example 010200 for version 1.2.0), and YYYY denotes the MAC type (SingleChannel or TSCH).
To configure a module with a particular platform, you may use the scripts already provided in $RIIM_SDK/Framework/Platform/ , or you can use the same tools and methods as you use for the ICI user application. Below is an example on how to transfer the TSCH BorderRouter platform to the module using the tools directly:
~/RIIM_SDK/ICI_Applications/My_App$ ../../Framework/Tools/rc188x_bootloader_utility load-image -f ../../Framework/Platform/Output/RIIM_Platform_BorderRouter_0x030203-TSCH.bin -p /dev/ttyUSB0
Cannot connect to Bootloader. Failed attempt 1.0 of 10.0 .
MODULE INFORMATION
EUI64: 00124B001CBCABD8
Hardware ID: 0x0002 (Unknown)
Hardware Rev: 0x0002
Platform ID: 0x0002 (Unknown)
Platform Version: v1.9.0
App Version: v255.255.255
Bootloader Version: v2.1.2
Bootloader Variant: 0x02 (IP Mesh)
Lock State: 0xFF (Unlocked)
Loading Image
Waiting for Bootloader to initiate transfer...
Start transfer:
................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................End transfer.................
file upload successful
Waiting for bootloader status..
Bootloader Status: Success