OTA Commands#

Create an OTA Bootloader File#

Creates a Zigbee Over-the-air (OTA) bootloader file from one or more Gecko Bootloader (GBL) files and writes the output to the specified OTA file.

Command Line Syntax

$ commander ota create --upgrade-image <filename> --manufacturer-id <ID> --image-type <image type> --firmware-version <version> --string <text> -o <outfile> [--manufacture-tag <tag ID:filename> -stack-version <version> --credentials <credentials> --destinations <EUI64> --min-hw <version> --max-hw <version>]

Command Line Input Example

$ commander ota create --upgrade-image example.gbl --manufacturer-id 0x1002 --image-type 0x5678 --firmware-version 0x00000005 --string "Example" -o example.ota

Creates an OTA file example.ota from the GBL upgrade image example.gbl.

Command Line Output Example

Initializing OTA file...
Writing header data...
Manufacturer ID : 0x1002
Image Type      : 0x5678
Firmware version: 0x00000005
Stack Version   : 0x0002
Header String   : Example
Writing OTA file ...
DONE

Create a Null OTA File#

The certification process for the Zigbee Over-the-Air (OTA) Bootload cluster client requires that the manufacturer provides a NULL upgrade file to the test house for testing. A NULL OTA upgrade file does not contain an actual upgrade image inside it (such as a Gecko Bootloader (GBL) file). It is much smaller than a full upgrade image, but otherwise the same as a normal Zigbee OTA file.

You create NULL files by using the --null option instead of the --upgrade-image option. The --null option consists of a tag ID and a tag length. The tag ID should be something other than 0x0000, which Zigbee has defined as "Upgrade Image". The tag length is a number of bytes, usually something small, such as 10. This option generates a sequence of bytes, starting at 0 and incrementing based on the tag length passed in.

Command Line Syntax

$ commander ota create --null <tag ID:tag length> --manufacturer-id <ID> --image-type <image type> --firmware-version <version> --string <text> -o <outfile> [--credentials <credentials> --destinations <EUI64> --min-hw <version> --max-hw <version>]

Command Line Input Example

$ commander ota create --null 0xffff:10 --manufacturer-id 0x110c --image-type 0x5678 --firmware-version 0x0102 --string "NULL OTA file"  -o ~/projects/Binaries/null.ota

Creates a NULL OTA file with a tag ID 0xffff and a tag length of 10 bytes.

Command Line Output Example

Initializing OTA file...
Writing OTA file ...
DONE

Print OTA File Information#

Parses and prints the contents of an Over-the-air (OTA) file.

Command Line Syntax

$ commander ota parse <ota file>

Command Line Input Example

$ commander ota parse example.ota

Displays content of the OTA file example.ota.

Command Line Output Example

Header Magic:             0x0beef11e
Header Version:           0x0100
Header Length:            56 bytes
Header Field Control:     0x0000
Manufacturer ID:          0x110c
ImageType:                0x0027 (Manufacture Specific)
Firmware Version:         0x01020509
Zigbee stack version:     0x0002 (ZigBee Pro)
Header String:            NULL
Image Size:               121680 bytes
Found 4 tags
   Tag ID:                0x0000 (Upgrade Image)
   Tag Length:            120572 bytes
   Tag ID:                0xff01 (Manufacturer Specific)
   Tag Length:            516 bytes
   Tag ID:                0xff3e (Manufacturer Specific)
   Tag Length:            504 bytes
   Tag ID:                0xff46 (Manufacturer Specific)
   Tag Length:            8 bytes
DONE

Sign an OTA File#

The Zigbee Smart Energy Profile requires that the manufacturer signs Over-the-Air (OTA) files. The OTA client must validate the downloaded files prior to installation. Images are signed using certificates issued by Certicom. After the images are signed, the signer's certificate is included automatically as a tag in the OTA file, and a signature tag is added as the last tag in the OTA file. For more information, see AN714: Smart Energy ECC-Enabled Device Setup Process.

Note: MacOS does not support OTA signing.

Command Line Syntax

$ commander ota create --sign --certificate <certificate>  --upgrade-image <filename> --manufacturer-id <ID> --image-type <image type> --firmware-version <version> --string <text> -o <outfile> [--credentials <credentials> --destinations <EUI64> --min-hw <version> --max-hw <version>]

Command Line Input Example

$ commander ota create --sign --certificate certificate.txt --upgrade-image example.gbl --manufacturer-id 0x0345 --image-type 0x4567 --firmware-version 0x00000002  --string "Signed OTA file"  -o signed_file.ota

Creates a signed OTA file using certificate certificate.txt.

Command Line Output Example

Creating OTA file...
Writing header data...
Manufacturer ID : 0x0345
Image Type      : 0x4567
Firmware version: 0x00000002
Stack Version   : 0x0002
Header String   : Signed OTA file
Digest: 8DFD32A4C6F3C39E6C152F33A16AEAD2
Signed file using certificate.
Successfully verified signature.
Writing OTA file signed_file.ota...
DONE

Create an OTA File for External Signing#

Create an Over-the-air (OTA) image to be signed externally. The external certificate is added to the image. The signature can be added to the image using the sign command in the following section.

Command Line Syntax

$ commander ota create --extsign --certificate <certificate>  --upgrade-image <filename> --manufacturer-id <ID> --image-type <image type> --firmware-version <version> --string <text> -o <outfile> [--credentials <credentials> --destinations <EUI64> --min-hw <version> --max-hw <version>]

Command Line Input Example

$ commander ota create --extsign --certificate certificate.txt --upgrade-image example.gbl --manufacturer-id 0x0345 --image-type 0x4567 --firmware-version 0x00000002  --string "Silicon Labs Ota Support"  -o example_file.ota

Command Line Output Example

Creating OTA file...
Writing header data...
Manufacturer ID : 0x0345
Image Type      : 0x4567
Firmware version: 0x00000002
Stack Version   : 0x0002
Header String   : Silicon Labs Ota Support
Writing OTA file example_file.ota.extsign...
DONE

Externally Sign an OTA File#

Use the Simplicity Commander sign command to append an externally created signature to an Over-the-Air (OTA) file. You must specify the curve used to create the signature using the --curve option. Available curves are 163k1 or 283k1.

Command Line Syntax

$ commander ota sign <filename> --curve <curve (163k1|283k1)>  --signature <filename> -o <outfile>

Command Line Input Example

$ commander ota sign example.ota --curve <curve (163k1|283k1)>  --signature signature.txt -o signed_file.ota

Appends the externally created signature to the OTA file.

Command Line Output Example

DONE

Verify Signature of an OTA File#

Use the Simplicity Commander verify command to verify the signature of an Over-the-Air (OTA) file. You must provide the certificate used to sign the file.

Note: MacOS does not support OTA signature verification.

Command Line Syntax

$ commander ota verify <filename> --certificate <certificate>

Command Line Input Example

$ commander ota verify signed_file.ota --certificate certificate.txt

Verifies the signature of the OTA file.

Command Line Output Example

Digest: 8ABB04618622595401AD45FA33C7D670
Successfully verified signature
DONE

Create an OTA Matter File#

Create a Matter Over-the-air (OTA) software update file from an application and write the output to the specified OTA file.

Command Line Syntax

$ commander ota create --type matter --input <filename> --vendorid <vendor ID> --productid <product ID> --swversion <version> --swstring <version string> --digest <digest algorithm> [--releasenote <url> --min-sw <version> --max-sw <version>] --output <filename>

Supported digest algorithms are

sha256
sha384
sha512
sha3_224
sha3_256
sha3_384
sha3_512

Command Line Input Example

$ commander ota create --type matter --vendorid 0x1234 --productid 0x4321 --swversion 0x300001 --swstring "3.0.1" --input application.bin --digest sha256 --releasenote "https://releasenotes.com" --min-sw 0x300000 --max-sw 0x400000 --output upgrade_file.ota

Creates an OTA file upgrade_file.ota from the application image application.bin.

Command Line Output Example

Creating OTA file...
Writing header data...
Vendor ID              : 0x1234
Product ID             : 0x4321
Software Version       : 0x00300001
Software Version String: 3.0.1
Min Software Version   : 0x00300000
Max Software Version   : 0x00400000
Release Note           : https://releasenotes.com
Digest Type            : sha256
Writing OTA file upgrade_file.ota...
DONE

Parse a Matter OTA File#

Parse and print the contents of a Matter Over-the-air (OTA) software update file. The optional --output option extracts the application from the OTA file and writes it to the file specified by the --output option.

Command Line Syntax

$ commander ota parse <ota file> --type matter [--output <application>]

Command Line Input Example

$ commander ota parse example.ota --type matter --output my_application.bin

Displays content of the OTA file example.ota and extracts the application from the OTA file and writes it to my_application.bin.

Command Line Output Example

Magic: 1beef11e
Total Size  : 977 bytes
Header Size : 105 bytes
Header TLV:
[0] Vendor ID     : 4660     (0x1234)
[1] Product ID    : 17185    (0x4321)
[2] Version       : 3145729  (0x300001)
[3] Version String: 3.0.1
[4] Payload Size  : 856      (0x358)
[5] Min Version   : 3145728  (0x300000)
[6] Max Version   : 4194304  (0x400000)
[7] Release Notes : https://releasenotes.com
[8] Digest Type   : 1        (0x1)
[9] Digest        : 8f259c4727adbe755ec1a49e8bfdbedb3486f53721cae5434efe5d9971eb5d55
Writing application to my_application.bin...