.. _target_The_SDK_and_Its_Tools: The SDK and Its Tools ===================== Building ICI Applications ------------------------- Please follow the :ref:`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. .. figure:: ../gfx/riim_workflow.png :align: center :alt: 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 :ref:`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. .. _target_Using_CMake: 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 :ref:`target_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 :ref:`target_Building_and_Uploading_Using_VSCode` and :ref:`target_Building_and_Uploading_Using_Scripts`): :: python ../../Framework/Tools/rc18xx_bootloader_utility.pyz load-app-image-key -f Application.key -p /dev/ttyUSB0 ../../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) 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 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 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