The SDK and Its Tools

Building ICI Applications

Please follow the RIIM SDK Quick Start Guide on 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

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 RIIM SDK Quick Start Guide on how to install the development environment. In the following examples, Linux is used. For windows, substitute the “.sh” file ending with “.bat” and “dev/ttyUSB0” with your associated COM port (for example “COM3”).

Using makefiles

The build system is using makefiles, but the user doesn’t need to know how they work. If you aren’t familiar with makefiles, the SDK provides a fully working and easy-to-edit makefile. You can copy it and use it in any new ICI user application project. it’s located here: RIIM_SDK/ICI_Applications/My_App/Makefile Several default values in the makefile can be overridden or edited, shown in the table below:

Makefile variables

Value

Description

SOURCE_FILE

The source file that’s to be compiled

OUTPUT_FILENAME

The output filename for your created ICI application. A «.bin» will be appended to the filename

PORT

Which serial port to use. In windows, this will be COM1, COM2, etc. In Linux it will be /dev/ttyUSB0, /dev/ttyUSB1, etc

AKEY

Filename for the ICI application encryption key

NKEY

Filename for the network encryption key

Framework_Path

The relative path to the framework

The variables can be overridden as in these examples

$ make uploadImage PORT=COM3
$ make encrypted AKEY=MyKey.key

Not Using Makefiles

The makefiles uses a set of tools that’s part of the SDK and the ARM compiler. You don’t need to use makefiles, you can just use the tools directly or in your own script. 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

$ ../../Framework/Tools/rc188x_bootloader_utility 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

$ ../../Framework/Tools/rc188x_bootloader_utility load-image -f ../../Framework/Platform/Output/RIIM_Platform_BorderRouter_0x010000.bin -p /dev/ttyUSB0

For all the tools, it’s possible to specify the «-h» switch to get help, like this:

$ ../../Framework/Tools/rc188x_bootloader_utility -h
usage: bootloader_util [-h] [--version] [-f FILE] [-p PORT] [-t TIMEOUT]
                   command

positional arguments:
command               info, load-image, load-app-image-key, load-network-
                        key, lock, run-app, autoconfig, autodetect

optional arguments:
-h, --help            show this help message and exit
--version             show program's version number and exit
-f FILE, --file FILE  image or key file
-p PORT, --port PORT  Serial port, for example COM12. If unspecified, then the
                        default in the config file is used
-t TIMEOUT, --timeout TIMEOUT
                        Timeout (in seconds) for trying to connect to
                        bootloader. Default is 10 seconds

And:

$ ../../Framework/Tools/rc188x_image_generator -h
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$

Open the Makefile located at RIIM_SDK/Framework/Tools/RIIM.mk in a text editor for more examples.

Creating and Uploading the ICI User Application

The following example shows how to create (compile) an unencrypted ICI user application image and upload it to the node using the bootloader over USB.

$ make
$ make uploadImage
<USER MUST RESET THE MODULE>

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 scripts provided with the development environment 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:

$ make encrypted
$ make uploadAppKey
<USER MUST RESET THE MODULE>
$ make uploadImage

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.

$ make lock
<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:

$ ../../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 use the same tools and methods as you use for the ICI user application. Below is an example on how to transfer the Router Mesh platform to the module:

~/RIIM_SDK/ICI_Applications/My_App$ ../../Framework/Tools/rc188x_bootloader_utility load-image -f ../../Framework/Platform/Output/RIIM_Platform_MeshRouter_0x010000.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