OTAP Builder Tool
- Thomas Watteyne
- Jonathan Simon
The OTAP Builder tool is used to convert a binary image into a file that can be used for Over-The-Air-Programming (OTAP). OTAP files are used to update application images on motes in a network, remotely.
Refer to the OTAP pages for an overview of how to use OTAP with a sample application of the On-Chip Software Development Kit.
The OTAP Builder tool is located at ocfdk_X_X_X/tools/otap_builder/OtapFile.py, and is provided as source code.
To run it, open a Windows command prompt and navigate to that directory. Type the following command to retrieve the help menu from the tool. Refer to the OTAP documentation for a step-by-step discussion on how to use this tool to OTAP a new version of an application onto a running SmartMesh IP Mote.
python OtapFile.py --help
Usage: OtapFile.py [options]
Application to create OTAP files. Copyright (c) 2013, Dust Networks. All
rights reserved.
Options:
-h, --help show this help message and exit
--verbose display verbose output
-i INPUT_FILE, --input=INPUT_FILE
path to the input file
-o OUTPUT_FILE, --output=OUTPUT_FILE
path to the (OTAP) output file
--not-executable mark the image as not executable
--no-compression do not compress the file data
--skip-validation set a flag in the OTAP file's header to tell the
target device to skip validation of the app ID and
vendor ID
--hardware-id=HARDWARE_ID
[executable images only] ID of the hardware the
application in the OTAP file should run on
--vendor-id=VENDOR_ID
[executable images only] vendor ID of the application
contained in the OTAP file
--app-id=APP_ID [executable images only] ID of the application
contained in the OTAP file
--exe-version=VERSION
[executable images only] version of the application
contained in the OTAP file
--depends-version=DEPENDS_VERSION
[executable images only] minimal version that needs to
be running on the target device for this OTAP to be
accepted during the OTAP handshake
-p PARTITION_ID, --partition=PARTITION_ID
ID of the partition on the target device to write into
--start-addr=START_ADDR
absolute memory address in the target device to write
to. In case this is an executable image, the target
device prepends a 32-byte kernel header when the OTAP
operation is successful. When OTAP'ing an executable
image, the value of this parameter should therefore
point to 32 bytes after the beginnning of the
executable partition
The following command will convert the ocfdk_02_gpio_net.bin binary into the ocfdk_02_gpio_net.otap2 OTAP file. By using the --verbose switch, the tool prints more information.
python OtapFile.py --verbose -i ocfdk_02_gpio_net.bin -o ocfdk_02_gpio_net.otap2 --partition 2 --app-id 10 --start-addr 0x41020 --hardware-id 3 Creating OTAP file with the following parameters: - infile : ocfdk_02_gpio_net.bin - outfile : ocfdk_02_gpio_net.otap2 - is_executable : True - do_compression : True - skip_validation : False - hardware_id : 3 - verbose : True - input_file : ocfdk_02_gpio_net.bin - start_addr : 266272 - vendor_id : 1 - app_id : 10 - partition_id : 2 - output_file : ocfdk_02_gpio_net.otap2 - version : [1, 0, 0, 0] - depends_version : [0, 0, 0, 0] Read input (binary) file... Stripping kernel header... Compressing data... Creating OTAP header... Writing output (OTAP) file... done.
To distinguish from OTAP images for previous hardware that used the .otap file extension, images used with Eterna (LTC5800-based) hardware use .otap2.
The hardware, vendor, and app IDs are reserved for future use. They are currently fixed in the mote, and cannot be used to accept or reject an OTAP image for a particular piece of hardware. One needs to either match the values in the example, or use the --skip-validation flag when creating an OTAP image. It is critical therefore that OTAP be performed in such a way that a specific image is programmed only on the correct subset of motes for which it is intended. Once a part is OTAP'd with an incorrect image, it may not be recoverable without a direct connection to a programmer.