fwtool

fwtool is a command-line utility for creating, updating, inspecting, and verifying a custom firmware metadata header prepended to a binary image.

It is intended for firmware packaging workflows where a raw application binary is post-processed into a single flashable image:

  • a fixed-size header is placed at the beginning that contains version, firmware size, and CRC information

  • the firmware firmware follows immediately after

This is useful for bootloaders or firmware update logic that need to validate and identify an application image before booting or programming it.

What it does

fwtool supports four subcommands:

  1. attach — prepend a new header to a raw firmware binary

  2. edit — replace the header of an already packaged binary

  3. inspect — print the parsed contents of an existing header

  4. verify — verify that an existing header matches the firmware

Header format

The tool generates a header with the following layout:

Offset

Size

Field

Description

0x00..0x03

4

magic

ASCII string XLAB

0x04..0x07

4

version

Little-endian bytes: [0x00, patch, minor, major]

0x08..0x0B

4

size

firmware size in bytes, little-endian uint32

0x0C..0x0F

4

crc32

CRC-32/MPEG-2 of firmware, little-endian uint32

0x10..end

—

padding

Filled with 0xFF

The total header size defaults to 512 bytes and is configurable via --header-size. It must be a power of two (minimum 16 bytes) so that the application vector table following it in flash is correctly aligned.

With the default 512-byte header, the padding region spans 0x10..0x1FF (496 bytes of 0xFF).

Notes

  • The CRC is calculated over the firmware only, not over the header.

  • The size stored in the header is the firmware size only.

  • The version is stored as:

    • byte 0: 0x00

    • byte 1: patch

    • byte 2: minor

    • byte 3: major

For example, version 1.2.3 is stored as:

0x00030201

Typical use case

A common workflow looks like this:

  • Link the firmware application so that it expects to execute after the reserved header space.

  • Build the raw application binary.

  • Use fwtool to prepend the metadata header.

  • Program the resulting combined binary into flash.

For example, with the default 512-byte header:

Flash address 0x08004000:
    [512-byte metadata header]
    [firmware payload]

Installation

Install using pip

pip install fwtool

Install using pipx

pipx install fwtool

Install using uv

uv tool install fwtool

Check installation

fwtool --version

Usage

fwtool <command> [arguments] [options]
  Subcommands
    Command Description
    attach Attach a new header to a raw firmware binary
    edit Replace the header of a packaged binary
    inspect Print header fields from a packaged binary
    verify Verify header of a packaged binary

  Common options
    --version Show program version and exit
    --help Show help message and exit

attach:

fwtool attach <binary> <version> <output> [options]
fwtool attach <binary> <version> --in-place [options]
  Argument / Option Description
  binary Path to raw input binary file
  version Firmware version string (e.g. 1, 1.2, 1.2.3)
  output Path to output file
  --in-place Modify the input file directly instead of writing output
  --header-size N Total header size in bytes; must be a power of 2 (default: 512)

edit:

fwtool edit <binary> <version> <output> [options]
fwtool edit <binary> <version> --in-place [options]
  Argument / Option Description
  binary Path to packaged binary file with existing header
  version New firmware version string
  output Path to output file
  --in-place Modify the input file directly instead of writing output
  --header-size N Total header size in bytes; must be a power of 2 (default: inferred from file)

inspect:

fwtool inspect <binary> [options]
  Argument / Option Description
  binary Path to packaged binary file
  --json Emit machine-readable JSON output

verify:

fwtool verify <binary> [options]
  Argument / Option Description
  binary Path to packaged binary file
  --json Emit machine-readable JSON output
  --quiet Suppress output; use exit code only
  --header-size N Total header size in bytes; must be a power of 2 (default: inferred from file)

Examples

Attach a new header to a raw binary

fwtool attach firmware.bin 1.2.3 packaged.bin

This creates:

packaged.bin = [512-byte header][firmware.bin firmware]

Attach with a custom header size

fwtool attach firmware.bin 1.2.3 packaged.bin --header-size 1024

Replace the header of an existing packaged binary

fwtool edit packaged.bin 1.2.4 updated.bin

This keeps the firmware but replaces the header with updated metadata.

Replace the header in place

fwtool edit packaged.bin 1.2.4 --in-place

This modifies packaged.bin directly.

Attach a header in place

fwtool attach firmware.bin 1.2.3 --in-place

This replaces the raw input file with a packaged binary containing the header.

Print header contents

fwtool inspect packaged.bin

Example output:

magic:   b'XLAB'
version: 1.2.3
size:    123456 bytes
crc32:   0x1a2b3c4d

Print header contents as JSON

fwtool inspect packaged.bin --json

Example output:

{
  "magic_ascii": "XLAB",
  "magic_hex": "584c4142",
  "version": {
    "major": 1,
    "minor": 2,
    "patch": 3,
    "string": "1.2.3"
  },
  "size": 123456,
  "crc": {
    "int": 439041101,
    "hex": "0x1a2b3c4d"
  }
}

Verify a packaged binary

fwtool verify packaged.bin

Example output:

magic:         OK
version:       1.2.3
header size:   512 bytes
size:          OK (header=123456, actual=123456)
crc32:         OK (header=0x1a2b3c4d, actual=0x1a2b3c4d)
verification:  OK

Verify quietly using only the exit code

fwtool verify packaged.bin --quiet
echo $?

Exit code meanings:

0: verification passed 1: verification failed

Verify with JSON output

fwtool verify packaged.bin --json

Example output:

{
  "ok": true,
  "magic_ok": true,
  "size_ok": true,
  "crc_ok": true,
  "header_size": 512,
  "header": {
    "magic_ascii": "XLAB",
    "magic_hex": "584c4142",
    "version": {
      "major": 1,
      "minor": 2,
      "patch": 3,
      "string": "1.2.3"
    },
    "size": 123456,
    "crc": {
      "int": 439041101,
      "hex": "0x1a2b3c4d"
    }
  },
  "firmware": {
    "size": 123456,
    "crc": {
      "int": 439041101,
      "hex": "0x1a2b3c4d"
    }
  }
}

Header size

The header size is configurable and defaults to 512 bytes.

Rules:

  • must be a power of two (16, 32, 64, 128, 256, 512, 1024, …)

  • must be at least 16 bytes (the minimum to hold the metadata fields)

  • ensures the application vector table following the header is correctly aligned

  • For edit and verify, if –header-size is not specified, the tool infers the header size from the stored firmware size field:

header_size = file_size - stored_firmware_size

If inference fails (e.g. corrupted size field), use –header-size to specify the size explicitly.

Version handling

Accepted version formats:

  • 1 -> 1.0.0

  • 1.2 -> 1.2.0

  • 1.2.3 -> 1.2.3

Rules:

  • missing components are filled with zero

  • extra components are ignored

  • each component must be in the range 0..255

Verification behavior

When fwtool verify is used, the tool checks:

  • the magic field is XLAB

  • the firmware size matches the size stored in the header

  • the firmware CRC matches the CRC stored in the header

  • The header itself is not included in the size or CRC calculation.

Exit codes

General operations

  • 0 on success

  • non-zero on failure

verify

  • 0 if verification succeeds

  • 1 if verification fails

Common workflow example

  • Build a raw firmware image:

arm-none-eabi-objcopy -O binary app.elf app.bin

  • Attach metadata header:

fwtool attach app.bin 1.2.3 app_packed.bin

  • Verify the packaged image:

fwtool verify app_packed.bin

  • Program the combined image to flash:

st-flash write app_packed.bin 0x08004000

Notes for embedded use

If your firmware image is packaged with a prepended header, the application must typically be linked to execute after the reserved header region.

Example with the default 512-byte (0x200) header:

  • metadata region starts at 0x08004000

  • header size is 0x200 (512 bytes)

  • application is linked to start at 0x08004200

  • Then the combined image can be programmed at 0x08004000, and the application

  • firmware will land at the correct runtime address.

Development

Run tests

pytest -q

License

MIT License