if820_ota_tool.py — BLE OTA firmware upgrade tool

A cross-platform command-line tool to perform an over-the-air (OTA) firmware upgrade of EZ-Serial firmware on Infineon / AIROC™ Bluetooth chipsets and modules (e.g. the Ezurio VELA IF820) over BLE.

Find it on Github: https://github.com/Ezurio/vela_if820_ota_upgrade

It is a Python port of the Windows WsOtaUpgrade application and speaks the exact same WICED OTA Firmware Upgrade GATT protocol, using the Bleak BLE library. Because Bleak is cross-platform, this tool runs on macOS, Linux and Windows without the original MFC/WinRT GUI app.

Requirements

  • Python 3.8 or newer
  • The bleak package (see installation below)
  • A host with a working Bluetooth LE adapter
  • A firmware image built for OTA (e.g. ..._download.ota.bin / *.ota.bin)

python vs python3

The commands below use python3, which is the usual name on macOS and most Linux distributions. On Windows (and some other setups) the interpreter is installed as python instead. Use whichever exists on your system — if python3 is not found, substitute python in every command (and likewise pip for pip3). Once the virtual environment is activated, python and pip inside it always point at the right interpreter regardless of platform.

You can check what you have with python3 --version or python --version.

Installation

From this directory, create a virtual environment and install the dependency:

python3 -m venv venv
source venv/bin/activate            # Windows: venv\Scripts\activate
pip install -r requirements.txt

Usage

python3 if820_ota_tool.py <image.bin> [--name "<BLE name>" | --address <BLE MAC>] [--timeout SECONDS]
  • <image.bin> — required. Path to the firmware image to flash.
  • --name — connect to the device advertising this exact BLE name. The name may contain spaces and colons, so quote it.
  • --address — connect directly by Bluetooth MAC address. Not supported on macOS (CoreBluetooth exposes opaque UUIDs, not MAC addresses) — use --name there.
  • --timeout — BLE scan timeout in seconds (default: 5). Increase it if the device is sometimes slow to be discovered. Applies to both the interactive scan and the --name lookup; it has no effect with --address.

--name and --address are mutually exclusive.

Interactive scan (no target specified)

If you provide neither --name nor --address, the tool scans for ~5 seconds, lists every device whose advertised name starts with EZ-Serial, and lets you pick one by number:

python3 if820_ota_tool.py firmware.ota.bin

Scanning 5 s for devices named 'EZ-Serial...'
Found 2 device(s):
  [0] EZ-Serial 85:05:6C            D1C2B697-C669-8662-98FC-5A88039577E3   -47 dBm
  [1] EZ-Serial 12:34:56            A8F1...                                 -71 dBm

Select device number to upgrade (or 'q' to quit): 0

Examples

# Upgrade a specific device by name
python3 if820_ota_tool.py firmware.ota.bin --name "EZ-Serial 85:05:6C"

# Upgrade by MAC address (Linux / Windows only)
python3 if820_ota_tool.py firmware.ota.bin --address AA:BB:CC:DD:EE:FF

# Scan and choose interactively
python3 if820_ota_tool.py firmware.ota.bin

# Give the device longer to show up (15 s scan)
python3 if820_ota_tool.py firmware.ota.bin --name "EZ-Serial 85:05:6C" --timeout 15

Example run

Loaded firmware image 'firmware.ota.bin' (103228 bytes).
Scanning 5 s for 'EZ-Serial 85:05:6C'...
Connecting...
Connected to D1C2B697-C669-8662-98FC-5A88039577E3.
Detected non-secure OTA firmware upgrade service.
Using data chunk size of 512 bytes.
Transferring: 100% (103228/103228 bytes)
Image CRC32 = 0x1a2b3c4d. Verifying...
Upgrade successful. The device will now reboot into the new firmware.

How it works

The tool implements the WICED OTA Firmware Upgrade protocol over a vendor-specific GATT service. After connecting it:

  1. Enables notifications on the Control Point characteristic.
  2. Sends PREPARE_DOWNLOAD and waits for an OK status.
  3. Sends DOWNLOAD with the 4-byte image length and waits for OK.
  4. Streams the image to the Data characteristic in MTU-sized chunks (MTU − 3, capped at 512 bytes; falls back to 20).
  5. Sends VERIFY with a CRC32 of the whole image. On OK the device commits the image and reboots into the new firmware.

Both the secure and non-secure OTA services are auto-detected (they share the same Control Point and Data characteristics; only the service UUID differs). The CRC32 is the standard zlib CRC (matching the device’s checksum).

Exit codes

Code Meaning
0 Success — firmware upgraded and device rebooting
1 OTA failed, aborted, or an unexpected error
2 --address used on macOS (unsupported)
3 Image file missing, unreadable, or empty
5 No target device selected / found

Troubleshooting

  • the 'bleak' package is required — activate the venv and pip install -r requirements.txt.
  • Times out waiting for device response — make sure the target is advertising, in range, and not already connected to another host. Move closer and retry.
  • Device stopped advertising - By default the EZ-Serial firmware stops advertising after 90 seconds. Advertising can be restarted by a device reset or with EZ-Serial gap_start_adv command.
  • --address is not supported on macOS — use --name "<BLE name>" instead.
  • Device not found when scanning — the tool matches names starting with EZ-Serial (case-sensitive). Confirm the device’s advertised name. If the device is simply slow to appear, raise the scan window with --timeout (e.g. --timeout 15).

  • Verbose debugging — set IF820_OTA_DEBUG=1 to print the Control Point characteristic properties and every raw notification:

    IF820_OTA_DEBUG=1 python3 if820_ota_tool.py firmware.ota.bin --name "EZ-Serial 85:05:6C"

Warning

Do not power off or disconnect the device during an upgrade. If an EEPROM or serial flash smaller than 64 KB is installed, memory after the upgrade may be corrupted — use the Recover procedure described in the BTSDK application project’s README to restore the device.