Overview
The elcap image subcommands provide functionality for manipulating firmware images and creating OTA (Over-The-Air) upgrade files. Each command has command line –options for execution, with situational requirements depending on the use case. This document covers when each option is required and how to use them. This information can also be obtained by running elcap with the --help option.
Image Combine
elcap image combine file1.hex file2.hex [file3.hex ...] --outfile <output_file>
Combines multiple files together into a single output file. This is useful for merging separate firmware components (e.g., bootloader, application) into a unified image file.
Arguments
| argument | description | required |
| files | List of files to combine (minimum 2 files required) | Yes |
Options
| --option | description | default |
| --outfile | Output file to write combined content | None |
| --help | Print help for this sub-command | None |
Usage
The combine command currently supports Intel HEX (.hex) file format. At least two files must be provided to perform a combine operation. The output file extension must match one of the input file extensions.
Basic usage:
elcap image combine file1.hex file2.hex --outfile combined.hex
Combining multiple files:
elcap image combine bootloader.hex application.hex config.hex --outfile final_image.hex
Notes
- At least 2 input files are required
- All input files must exist
- Currently only supports .hex (Intel HEX) file format
- Output file type must match at least one input file type
- Output directory is created automatically if it doesn't exist
Zigbee OTA (zbota)
Generates a Zigbee OTA (Over-The-Air) upgrade image file that conforms to the Zigbee Cluster Library specification. This command creates properly formatted OTA files with headers and sub-elements (tags) that can be used for over-the-air firmware updates of Zigbee devices.
Required Options
| --option | short | description | example |
| --outfile | -o | Output filename for the OTA file | firmware.ota |
| --mfg-id | -m | 2-byte manufacturer ID (ZigBee assigned identifier) | 0x1234 |
| --image-type | -i | 2-byte image type identifier (manufacturer specific) | 0x0001 |
| --version | -v | 4-byte file version (e.g., dotted version or hex) | 1.0.0.1 or 0x01000001 |
| --tag | -t | Tag specification in format TAG_ID:FILE_OR_LENGTH (can be used multiple times) | 0x0000:app.bin |
Optional Options
| --option | short | description | default |
| --string | | Header string text (max 32 chars, null-terminated ASCII) | None |
| --credentials | -c | 1-byte security credential version | None |
| --dest-eui64 | -d | Upgrade destination EUI64 (for device-specific files) | None |
| --min-hwv | | Minimum hardware version (2-byte) | None |
| --max-hwv | | Maximum hardware version (2-byte) | None |
| --integrity | -ic | Add image integrity code (AES-MMO hash) as tag 0x0003 | False |
| --help | | Print help for this sub-command | None |
Zigbee OTA File Format
The OTA file format consists of:
- OTA Header - Contains metadata about the image (manufacturer, version, device info, etc.)
- Sub-elements (Tags) - Self-describing data sections containing upgrade images, integrity codes, or manufacturer-specific data
Each sub-element has:
- Tag ID (2 bytes) - Identifies the type of data
- Length Field (4 bytes) - Size of the data section
- Data (variable) - The actual content
Valid Tag IDs
| Tag ID Range | Description |
| 0x0000 | Upgrade Image (firmware binary) |
| 0x0004 | Picture data |
| 0xF000 - 0xFFFE | Manufacturer specific use |
Reserved Tag IDs
| Tag ID Range | Description |
| 0x0003 | Image Integrity Code (AES-MMO hash) |
| 0x0001, 0x0002, 0x0005, 0x0006 | ECDSA signatures and certificates (Future Support) |
| 0xFFFF | Internal padding (reserved by ElCap) |
OTA Header Fields
The zbota command automatically generates an OTA header with the following fields:
| Field | Size (bytes) | Description |
| OTA file identifier | 4 | Fixed value: 0x0BEEF11E |
| OTA Header version | 2 | Current version: 0x0100 |
| OTA Header length | 2 | Calculated based on optional fields present |
| OTA Header Field control | 2 | Bitmask indicating which optional fields are included |
| Manufacturer code | 2 | From --mfg-id parameter |
| Image type | 2 | From --image-type parameter |
| File version | 4 | From --version parameter |
| ZigBee Stack version | 2 | Set to 0x0002 (ZigBee Pro) |
| OTA Header string | 32 | From --string parameter (null-terminated) |
| Total Image size | 4 | Calculated (includes header + all tags) |
| Security credential version | 0/1 | From --credentials parameter (optional) |
| Upgrade file destination | 0/8 | From --dest-eui64 parameter (optional) |
| Minimum hardware version | 0/2 | From --min-hwv parameter (optional) |
| Maximum hardware version | 0/2 | From --max-hwv parameter (optional) |
Tag Specifications
Tags are specified using the --tag option with the format: TAG_ID:FILE.bin or TAG_ID:LENGTH for creating NULL OTA files with LENGTH number of bytes.
Tag with File Source
Specifies a tag that reads data from a file:
--tag 0x0000:firmware.bin
The tag will contain the complete contents of firmware.bin.
Tag with Length Specification - NULL OTA
Specifies a tag that creates a padding block of a specified length:
Creates a tag with 1024 bytes of padding data.
Multiple Tags
Multiple tags can be specified by using the --tag option multiple times:
--tag 0x0000:app.bin --tag 0xff00:config.bin
Important Notes:
- Each tag ID can only be used once (no duplicates)
- All file paths must exist and be readable
- Tag IDs must be valid according to the Zigbee specification
File Version Format
The --version parameter can be specified in two formats:
Dotted Decimal Format
Hexadecimal Format
Same as above, in hex.
Hardware Version Fields
Hardware version fields (--min-hwv and --max-hwv) specify the range of hardware platforms the image is compatible with.
Format: 0xVVRR where VV=version, RR=revision
--min-hwv 0x0100 # Hardware version 1.0
--max-hwv 0x0102 # Hardware version 1.2
The device's hardware version must be >= minimum and <= maximum to use the OTA file.
Image Integrity Code
The --integrity flag adds an Image Integrity Code sub-element (tag 0x0003) containing an AES-MMO (Matyas-Meyer-Oseas) hash of the OTA file. This provides protection against unintended data corruption during storage and transfer.
When to use:
- Application standards that require integrity verification
- When ECDSA signatures are not being used
- To detect file corruption before transmission to devices
Note: Per Zigbee spec, integrity codes should NOT be used in conjunction with ECDSA signatures.
Common Use Cases
Firmware Update OTA
Standard firmware update with application code:
elcap image zbota --outfile update.ota --mfg-id 0x1234 --image-type 0x0001 --version 1.0.0.1 --tag 0x0000:firmware.bin
Example:
$ elcap image zbota --outfile zb_example.ota --mfg-id 0x1570 --image-type 0x0001 --version 0x20251205 --tag 0x0000:build/T32CM11C.Debug/zb_example-custom-signed.bin
Zigbee OTA Header:
OTA File ID: 0x0beef11e
Header Version: 0x0100
Header Length: 56 bytes
Field Control: 0x0000
Manufacturer ID: 0x1570
Image Type: 0x0001
Firmware Version: 0x20251205
Stack Version: 0x0002
Header String: Default Trident OTA header data.
Total Image Size: 322560 bytes
Upgrade Image Details:
Output File: zb_example.ota
Tag ID: 0xffff
Tag Data Length: 188 bytes
Tag ID: 0x0000
Tag File: build/T32CM11C.Debug/zb_example-custom-signed.bin
Tag Data Length: 322304 bytes
OTA image generated and saved to: zb_example.ota
Multi-Processor Update
Update that includes binary for Zigbee processor and secondary processor with AES-MMO integrity hash:
elcap image zbota --outfile update.ota --mfg-id 0x1234 --image-type 0x0001 --version 1.0.0.1 --tag 0x0000:zigbee_fw.bin --tag 0xf000:secondary_fw.bin --integrity
Example:
$ elcap image zbota --outfile zb_combo.ota --mfg-id 0x1570 --image-type 0x0001 --version 0x20251205 --tag 0x0000:build/T32CM11C.Debug/zb_example-custom-signed.bin --tag 0xf000:secondary_fw.bin --integrity
Zigbee OTA Header:
OTA File ID: 0x0beef11e
Header Version: 0x0100
Header Length: 56 bytes
Field Control: 0x0000
Manufacturer ID: 0x1570
Image Type: 0x0001
Firmware Version: 0x20251205
Stack Version: 0x0002
Header String: Default Trident OTA header data.
Total Image Size: 743708 bytes
Upgrade Image Details:
Output File: zb_combo.ota
Tag ID: 0xffff
Tag Data Length: 188 bytes
Tag ID: 0x0000
Tag File: build/T32CM11C.Debug/zb_example-custom-signed.bin
Tag Data Length: 322304 bytes
Tag ID: 0xf000
Tag File: secondary_fw.bin
Tag Data Length: 421120 bytes
Tag ID: 0x0003
AES MMO HASH: 071b2d1d872b2a0d267150c33050e278
Tag Data Length: 16 bytes
OTA image generated and saved to: zb_combo.ota
NULL OTA File
Create a NULL OTA file(s) for certification testing:
elcap image zbota --outfile firmware.ota --mfg-id 0x1234 --image-type 0x0001 --version 1.0.0.1 --tag 0x0000:32
This creates an upgrade image tag (0x0000) with 32 bytes of dummy data.
Example: NULL downgrade file:
$ elcap image zbota --outfile null_downgrade.ota --mfg-id 0x1570 --image-type 0x0001 --version 0.0.0.1 --tag 0x0000:32 --string "NULL Downgrade File"
Zigbee OTA Header:
OTA File ID: 0x0beef11e
Header Version: 0x0100
Header Length: 56 bytes
Field Control: 0x0000
Manufacturer ID: 0x1570
Image Type: 0x0001
Firmware Version: 0x00000001
Stack Version: 0x0002
Header String: NULL Downgrade File
Total Image Size: 94 bytes
Upgrade Image Details:
Output File: null_downgrade.ota
Tag ID: 0x0000
Tag Data Length: 32 bytes
OTA image generated and saved to: null_downgrade.ota
Example: NULL upgrade file:
$ elcap image zbota --outfile null_upgrade.ota --mfg-id 0x1570 --image-type 0x0001 --version 0xffffffff --tag 0x0000:32 --string "NULL Upgrade File"
Zigbee OTA Header:
OTA File ID: 0x0beef11e
Header Version: 0x0100
Header Length: 56 bytes
Field Control: 0x0000
Manufacturer ID: 0x1570
Image Type: 0x0001
Firmware Version: 0xffffffff
Stack Version: 0x0002
Header String: NULL Upgrade File
Total Image Size: 94 bytes
Upgrade Image Details:
Output File: null_upgrade.ota
Tag ID: 0x0000
Tag Data Length: 32 bytes
OTA image generated and saved to: null_upgrade.ota
Security Considerations
Image Integrity Code
- Provides protection against unintended data corruption
- Uses AES-MMO hash per Zigbee specification
- Does NOT provide authenticity verification
- Suitable for detecting file system errors and transfer corruption
ECDSA Signatures (Not yet implemented)
- Would provide authenticity and integrity verification
- Reserved tag IDs: 0x0001, 0x0002, 0x0005, 0x0006
- Cannot be combined with Image Integrity Code per Zigbee spec
1.15.0