OAD Image Tool

The OAD image tool is a script written in python that is intended to process the compiler output in the form of a hex file and prepare the image for over the air transfer.

The major components of the oad_image_tool include:

• Conversion from *.hex to *.bin

• Padding the image to be word aligned

• Calculating the CRC and embedding it in the image header

• Optional: Merging a split image into a single app + stack image

• Optional: Adding security info to the image header if present

The tool is automatically invoked by the OAD enabled projects in the SDK as a post build step. For sample invocations refer to the post build steps on these projects

Note

OAD Image Tool does not support non-executable types.

Running the tool

The OAD Image Tool is distributed in both source and binary form. The correct binary will be bundled with the installer for a given platform (i.e. Linux, Windows, Mac). However, the tool can also be run in source if desired.

The tool is intended to run as a post build step to an OAD application. When run as a post build step, the tool will generate an output binary file named <app_name>_oad.bin where <app_name> is the name and path specified by the required -o argument to the script.

It is recommended to use the OAD enabled example application from the intended protocol stack component of the SimpleLink CC13xx/CC26xx SDK and copy + modify the post build step as needed.

Running the Tool from Source

In general, it is recommended to invoke the tool via the binaries distributed with the SimpleLink CC13xx/CC26xx SDK. However if it is required to run the tool in source, the following steps should be taken:

• Ensure Python is installed on the system (Python 3 recommended)

• Install the required packages via pip (see requirements.txt in the same folder as the tool)

The tool project is located in <SDK_DIR>/tools/common/oad

Generating New Security Keys (Embedded)

By default, public and private keys will be provided in the private.pem and public.pem files. The private key will be used by the OAD image tool to sign the application image before outputting the binary. The path to the private key must be provided if using using security, this is provided using the -k option. You must be using the secure version of the tool to do this.

The default keys are also installed in the BIM projects in order for the out of box demos to work.

However, before production it is recommended that the customer generate new keys using the process detailed below:

Note

The key_generate.py script requires use of Python 3.7 to behave as expected.

1. Generate a new key pair by calling python keys/key_generate.py from within the OAD tool folder. This will override the existing private.pem public.pem, and key_info.txt files.

2. Replace the keys used by the BIM with the new ones generated by the tool. The code snippet below shows how to do this. Replace the “NEW ** HERE” placeholders below with the contents of the appropriate line in the key_info.txt file.

{
    .version    = SECURE_SIGN_TYPE,
    .len        = SECURE_CERT_LENGTH,
    .options    = SECURE_CERT_OPTIONS,
    .signerInfo = {/* NEW SIGNER INFO HERE */},
    .certPayload.eccKey.pubKeyX = {/* NEW PUB KEY X HERE */},
    .certPayload.eccKey.pubKeyY = {/* NEW PUB KEY Y HERE */}
};

3. The structure above can be found in the following file:

	CC2640R2F	CC13xx/CC26xx
Off-chip OAD	bim_main.c	bim_main.c
On-chip OAD	bim_onchip.c	bim_main.c

Note

You will need to add proper C style syntax to the key arrays when pasting them into the BIM files. Be sure to add a comma between each element and prepends all hex values with 0x. Refer to the placeholder keys for more information.

Required Arguments/Getting Help

If help is needed when running the tool, invoke it with the -h option which will describe the supported features of the tool, the arguments and the actions they perform. Usage is as follows:

python oad_image_tool.py -h
usage: oad_image_tool [-h] [-v] [-verbose] [-hex1 HEXPATH1] [-bdf BDFILEPATH]
                      [-hex2 [HEXPATH2]] [-k [KEYFILE]] -o OUTPUT
                      ProjType ProjDir BinaryType

OAD Hex to Binary Converter version

positional arguments:
  ProjType              Target project Type: (iar/ccs)
  ProjDir               Target project directory
  BinaryType            Persistent App = 0, Application = 1, Stack = 2,
                        Application + Stack Combined = 3, Application + Stack
                        Merged = 7

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -verbose, --verbose
  -hex1 HEXPATH1, --HexPath1 HEXPATH1
                        First .hex file path (app/stack)
  -bdf BDFILEPATH, --bdFilePath BDFILEPATH
                        Boundary file path
  -hex2 [HEXPATH2], --HexPath2 [HEXPATH2]
                        Second .hex file name (app/stack)
  -k [KEYFILE], --keyFile [KEYFILE]
                        Provide the location of the file containing your
                        private key
  -o OUTPUT, --output OUTPUT
                        Path and filename of output file(s) without extension