Initial commit

uf2conv.py

@@ -0,0 +1,861 @@
+#!/usr/bin/env python3
+r"""Convert firmware images between Intel HEX, raw BIN, and Raspberry Pi UF2.
+
+This is the course's single canonical copy of the converter. Every week that
+patches a binary refers to the copy at the repository root:
+
+    python ../uf2conv.py build/image-h.bin --base 0x10000000 \\
+        --family 0xe48bff59 --output build/hacked.uf2
+
+It descends from the upstream Raspberry Pi ``uf2conv.py``, with the following
+changes made for this course:
+
+* Full type annotations and Google-style docstrings on every public callable.
+* ``pathlib`` instead of ``os.path``, and explicit ``except`` clauses.
+* Latent crash bugs in the upstream error paths fixed (see
+  :func:`convert_from_uf2`).
+* Module globals replaced with an explicit :class:`ConverterContext`, so the
+  base address and family ID are threaded through rather than mutated behind
+  the caller's back.
+
+UF2 format, for reference
+-------------------------
+A UF2 file is a flat sequence of 512-byte blocks. Each block is::
+
+    offset  size  field
+    0x00    4     magicStart0 = 0x0A324655   ("UF2\\n")
+    0x04    4     magicStart1 = 0x9E5D5157   (arbitrary constant)
+    0x08    4     flags
+    0x0C    4     targetAddr
+    0x10    4     payloadSize   (max 476)
+    0x14    4     blockNo
+    0x18    4     numBlocks
+    0x1C    4     familyID
+    0x20    476   data
+    0x1FC   4     magicEnd = 0x0AB16F30
+
+Flags that matter here:
+
+* ``0x00000001`` -- "do not flash"; this block is a no-flash marker.
+* ``0x00002000`` -- "family ID present"; ``familyID`` is meaningful.
+
+For the RP2350 the family ID is ``0xe48bff59``, and it is what tells the
+boot ROM that this UF2 targets RP2350 hardware rather than, say, an RP2040 or
+a Pico W.
+
+See Also:
+--------
+* ``uf2families.json`` -- the family-name to family-ID table, loaded from the
+  directory containing this file.
+* ``flash.sh`` / ``flash.ps1`` -- program a raw ``.bin`` over SWD instead.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import struct
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from time import sleep
+
+# ---------------------------------------------------------------------------
+# UF2 format constants
+# ---------------------------------------------------------------------------
+
+#: First magic word, ``"UF2\n"`` read as a little-endian uint32.
+UF2_MAGIC_START0 = 0x0A324655
+#: Second magic word. The value is arbitrary but must be constant.
+UF2_MAGIC_START1 = 0x9E5D5157
+#: Trailing magic word closing every 512-byte block.
+UF2_MAGIC_END = 0x0AB16F30
+
+#: Size of one UF2 block in bytes.
+UF2_BLOCK_SIZE = 512
+#: Offset of the 32-byte block header within a block.
+UF2_HEADER_SIZE = 32
+#: Largest payload a single block may carry (476 = 512 - 32 header - 4 magic).
+UF2_MAX_PAYLOAD = UF2_BLOCK_SIZE - UF2_HEADER_SIZE - 4
+
+#: Flag bit marking a block the bootloader must NOT program.
+UF2_FLAG_NOFLASH = 0x00000001
+#: Flag bit announcing that ``familyID`` carries a meaningful value.
+UF2_FLAG_FAMILY_ID = 0x00002000
+
+#: Name of the marker file the boot ROM exposes on its flash-drive volume.
+INFO_FILE = "INFO_UF2.TXT"
+
+#: Struct format for the 32-byte UF2 block header.
+_HEADER_STRUCT = struct.Struct("<IIIIIIII")
+
+#: The default family ID assumed when the caller does not pass ``--family``.
+DEFAULT_FAMILY_ID = 0x0
+#: The default base address assumed when the caller does not pass ``--base``.
+#: Matches the upstream default; RP2350 firmware always overrides this.
+DEFAULT_BASE_ADDRESS = 0x2000
+
+
+class Uf2Error(Exception):
+    """Raised when an input file is malformed or internally inconsistent."""
+
+
+@dataclass
+class ConverterContext:
+    """Mutable conversion state shared across a single CLI invocation.
+
+    Attributes:
+        appstartaddr: Base address that payload offsets are relative to. Set
+            from ``--base``; ``0`` means "derive it from the input".
+        familyid: Family ID written into every UF2 block. ``0`` means "no
+            family flag", which is the correct behaviour for a plain BIN->UF2
+            conversion of RP2040-era images, and the wrong behaviour for
+            RP2350, which is why the course always passes ``--family``.
+    """
+
+    appstartaddr: int | None = DEFAULT_BASE_ADDRESS
+    familyid: int = DEFAULT_FAMILY_ID
+
+
+# ---------------------------------------------------------------------------
+# Format detection
+# ---------------------------------------------------------------------------
+
+
+def is_uf2(buf: bytes) -> bool:
+    """Report whether a buffer begins with the UF2 start magic.
+
+    Args:
+        buf: Raw file contents.
+
+    Returns:
+        ``True`` if the first two uint32 words are the UF2 start magic.
+    """
+    if len(buf) < 8:
+        return False
+    word0, word1 = _HEADER_STRUCT.unpack_from(buf, 0)[:2]
+    return word0 == UF2_MAGIC_START0 and word1 == UF2_MAGIC_START1
+
+
+def is_hex(buf: bytes) -> bool:
+    """Report whether a buffer looks like an Intel HEX file.
+
+    A file qualifies when it decodes as UTF-8, begins with a record marker
+    ``:``, and contains only characters legal in Intel HEX records.
+
+    Args:
+        buf: Raw file contents.
+
+    Returns:
+        ``True`` if the buffer should be treated as Intel HEX.
+    """
+    try:
+        text = buf[:30].decode("utf-8")
+    except UnicodeDecodeError:
+        return False
+    if not text.startswith(":"):
+        return False
+    return re.match(rb"^[:0-9a-fA-F\r\n]+$", buf) is not None
+
+
+# ---------------------------------------------------------------------------
+# UF2 -> BIN
+# ---------------------------------------------------------------------------
+
+
+def convert_from_uf2(buf: bytes, ctx: ConverterContext) -> bytes:
+    """Decode a UF2 file back into a flat binary image.
+
+    Blocks are visited in file order. Gaps between consecutive block addresses
+    are filled with zero words, and any trailing gap is dropped so that the
+    result ends at the last byte actually programmed.
+
+    A UF2 file may legitimately interleave blocks from several families (this
+    is how a multicore image ships both cores in one download). When more than
+    one family is present and the caller did not constrain the family with
+    ``--family``, the conversion is ambiguous, so the payload is emptied and
+    ``appstartaddr`` reset to ``0``.
+
+    Args:
+        buf: Complete UF2 file contents.
+        ctx: Conversion state; updated in place with the discovered base
+            address.
+
+    Returns:
+        The decoded payload.
+
+    Raises:
+        Uf2Error: If a block declares an oversized payload, the blocks are out
+            of order, or the implied padding exceeds 10 MiB.
+
+    Note:
+        The upstream Raspberry Pi version of this function crashes on its own
+        error paths: it builds the message with ``"..." + ptr`` where ``ptr``
+        is an ``int``, which raises :class:`TypeError` and masks the real
+        problem. The messages here use f-strings so the diagnostic survives.
+    """
+    numblocks = len(buf) // UF2_BLOCK_SIZE
+    curraddr: int | None = None
+    currfamilyid: int | None = None
+    families_found: dict[int, int] = {}
+    prev_flag: int | None = None
+    all_flags_same = True
+    outp: list[bytes] = []
+
+    for blockno in range(numblocks):
+        ptr = blockno * UF2_BLOCK_SIZE
+        block = buf[ptr : ptr + UF2_BLOCK_SIZE]
+        (
+            magic0,
+            magic1,
+            flags,
+            target_addr,
+            datalen,
+            _blockno,
+            _numblocks,
+            block_family,
+        ) = _HEADER_STRUCT.unpack_from(block, 0)
+
+        if magic0 != UF2_MAGIC_START0 or magic1 != UF2_MAGIC_START1:
+            print(f"Skipping block at {ptr:#x}; bad magic")
+            continue
+
+        if flags & UF2_FLAG_NOFLASH:
+            continue
+
+        if datalen > UF2_MAX_PAYLOAD:
+            msg = f"Invalid UF2 data size at {ptr:#x}: {datalen}"
+            raise Uf2Error(msg)
+
+        if flags & UF2_FLAG_FAMILY_ID and currfamilyid is None:
+            currfamilyid = block_family
+
+        # A new contiguous run starts when the address jumps or the family
+        # changes. appstartaddr tracks the start of the current run, which is
+        # what makes the reported start address the image's true base rather
+        # than the address of its last block.
+        if curraddr is None or (
+            flags & UF2_FLAG_FAMILY_ID and block_family != currfamilyid
+        ):
+            currfamilyid = block_family
+            curraddr = target_addr
+            if ctx.familyid == DEFAULT_FAMILY_ID or ctx.familyid == block_family:
+                ctx.appstartaddr = target_addr
+
+        padding = target_addr - curraddr
+        if padding < 0:
+            msg = f"Block out of order at {ptr:#x}: {target_addr:#x} < {curraddr:#x}"
+            raise Uf2Error(msg)
+        if padding > 10 * 1024 * 1024:
+            msg = f"More than 10M of padding needed at {ptr:#x}"
+            raise Uf2Error(msg)
+        if padding % 4 != 0:
+            msg = f"Non-word padding size at {ptr:#x}: {padding}"
+            raise Uf2Error(msg)
+
+        while padding > 0:
+            padding -= 4
+            outp.append(b"\x00\x00\x00\x00")
+
+        if ctx.familyid == DEFAULT_FAMILY_ID or (
+            flags & UF2_FLAG_FAMILY_ID and ctx.familyid == block_family
+        ):
+            outp.append(
+                block[UF2_HEADER_SIZE : UF2_HEADER_SIZE + datalen],
+            )
+
+        curraddr = target_addr + datalen
+
+        if flags & UF2_FLAG_FAMILY_ID:
+            existing = families_found.get(block_family)
+            if existing is None or existing > target_addr:
+                families_found[block_family] = target_addr
+
+        if prev_flag is None:
+            prev_flag = flags
+        elif prev_flag != flags:
+            all_flags_same = False
+
+        if blockno == numblocks - 1:
+            _print_uf2_header_info(families_found, all_flags_same, flags)
+            if len(families_found) > 1 and ctx.familyid == DEFAULT_FAMILY_ID:
+                outp = []
+                ctx.appstartaddr = 0x0
+
+    return b"".join(outp)
+
+
+def _print_uf2_header_info(
+    families_found: dict[int, int],
+    all_flags_same: bool,
+    flags: int,
+) -> None:
+    """Print the family summary block that follows a UF2->BIN conversion.
+
+    Args:
+        families_found: Mapping of family ID to the lowest target address seen
+            for that family.
+        all_flags_same: Whether every block carried an identical flag word.
+        flags: The flag word from the final block, used for display.
+    """
+    print("--- UF2 File Header Info ---")
+    families = load_families()
+    name_by_id = {value: key for key, value in families.items()}
+    for family_hex, address in families_found.items():
+        short_name = name_by_id.get(family_hex, "")
+        print(f"Family ID is {short_name}, hex value is {family_hex:#010x}")
+        print(f"Target Address is {address:#010x}")
+    if all_flags_same:
+        print(f"All block flag values consistent, {flags:#06x}")
+    else:
+        print("Flags were not all the same")
+    print("----------------------------")
+
+
+# ---------------------------------------------------------------------------
+# BIN -> UF2
+# ---------------------------------------------------------------------------
+
+
+def convert_to_uf2(file_content: bytes, ctx: ConverterContext) -> bytes:
+    """Wrap a raw binary in UF2 blocks.
+
+    The binary is split into 256-byte payloads; the final block is zero-padded.
+    Each block's ``targetAddr`` is the byte offset within the image plus
+    :attr:`ConverterContext.appstartaddr`, so for RP2350 firmware built at
+    ``0x10000000`` the caller passes ``--base 0x10000000``.
+
+    Args:
+        file_content: The raw image.
+        ctx: Conversion state supplying the base address and family ID.
+
+    Returns:
+        The UF2 file contents, always a whole number of 512-byte blocks.
+    """
+    datapadding = bytes(UF2_BLOCK_SIZE - 256 - UF2_HEADER_SIZE - 4)
+    numblocks = (len(file_content) + 255) // 256
+    flags = UF2_FLAG_FAMILY_ID if ctx.familyid else 0x0
+    base = ctx.appstartaddr or 0
+
+    blocks: list[bytes] = []
+    for blockno in range(numblocks):
+        ptr = 256 * blockno
+        chunk = file_content[ptr : ptr + 256]
+        header = _HEADER_STRUCT.pack(
+            UF2_MAGIC_START0,
+            UF2_MAGIC_START1,
+            flags,
+            ptr + base,
+            256,
+            blockno,
+            numblocks,
+            ctx.familyid,
+        )
+        payload = chunk + bytes(256 - len(chunk))
+        block = header + payload + datapadding + struct.pack("<I", UF2_MAGIC_END)
+        blocks.append(block)
+    return b"".join(blocks)
+
+
+def convert_to_carray(file_content: bytes) -> bytes:
+    """Render a binary as a C array initialiser for embedding in firmware.
+
+    Args:
+        file_content: The raw image.
+
+    Returns:
+        UTF-8 bytes of a C translation unit fragment.
+    """
+    parts = [
+        f"const unsigned long bindata_len = {len(file_content)};\n",
+        "const unsigned char bindata[] __attribute__((aligned(16))) = {",
+    ]
+    for index, value in enumerate(file_content):
+        if index % 16 == 0:
+            parts.append("\n")
+        parts.append(f"{value:#04x}, ")
+    parts.append("\n};\n")
+    return "".join(parts).encode()
+
+
+# ---------------------------------------------------------------------------
+# Intel HEX -> UF2
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Block:
+    """A single 256-byte-aligned region of an image under construction.
+
+    Attributes:
+        addr: Base address of the block, always 256-byte aligned.
+        data: The block's bytes, initialised to ``default_data``.
+    """
+
+    addr: int
+    data: bytearray
+
+    def __init__(self, addr: int, default_data: int = 0xFF) -> None:
+        """Initialise an erased 256-byte block.
+
+        Args:
+            addr: 256-byte-aligned base address of the block.
+            default_data: Fill byte; ``0xFF`` matches erased flash.
+        """
+        self.addr = addr
+        self.data = bytearray([default_data] * 256)
+
+    def encode(self, blockno: int, numblocks: int, ctx: ConverterContext) -> bytes:
+        """Serialise this block into a 512-byte UF2 block.
+
+        Args:
+            blockno: Index of this block within the file.
+            numblocks: Total number of blocks in the file.
+            ctx: Conversion state supplying the family ID.
+
+        Returns:
+            Exactly 512 bytes.
+        """
+        flags = UF2_FLAG_FAMILY_ID if ctx.familyid else 0x0
+        out = _HEADER_STRUCT.pack(
+            UF2_MAGIC_START0,
+            UF2_MAGIC_START1,
+            flags,
+            self.addr,
+            256,
+            blockno,
+            numblocks,
+            ctx.familyid,
+        )
+        out += self.data[0:256]
+        out += bytes(UF2_BLOCK_SIZE - 4 - len(out))
+        out += struct.pack("<I", UF2_MAGIC_END)
+        return out
+
+
+def convert_from_hex_to_uf2(text: str, ctx: ConverterContext) -> bytes:
+    """Assemble Intel HEX records into a UF2 file.
+
+    Only record types 0x00 (data), 0x01 (EOF), 0x02 (extended segment address)
+    and 0x04 (extended linear address) are handled; any other type is ignored,
+    matching the upstream behaviour.
+
+    Args:
+        text: Decoded Intel HEX file contents.
+        ctx: Conversion state; ``appstartaddr`` is set to the first data
+            address seen.
+
+    Returns:
+        The UF2 file contents.
+    """
+    ctx.appstartaddr = None
+    upper = 0
+    currblock: Block | None = None
+    blocks: list[Block] = []
+
+    for line in text.split("\n"):
+        if not line.startswith(":"):
+            continue
+        record = [int(line[i : i + 2], 16) for i in range(1, len(line) - 1, 2)]
+        rec_type = record[3]
+        if rec_type == 4:
+            upper = ((record[4] << 8) | record[5]) << 16
+        elif rec_type == 2:
+            upper = ((record[4] << 8) | record[5]) << 4
+        elif rec_type == 1:
+            break
+        elif rec_type == 0:
+            addr = upper + ((record[1] << 8) | record[2])
+            if ctx.appstartaddr is None:
+                ctx.appstartaddr = addr
+            index = 4
+            while index < len(record) - 1:
+                if currblock is None or currblock.addr & ~0xFF != addr & ~0xFF:
+                    currblock = Block(addr & ~0xFF)
+                    blocks.append(currblock)
+                currblock.data[addr & 0xFF] = record[index]
+                addr += 1
+                index += 1
+
+    numblocks = len(blocks)
+    return b"".join(blocks[i].encode(i, numblocks, ctx) for i in range(numblocks))
+
+
+# ---------------------------------------------------------------------------
+# Drive discovery
+# ---------------------------------------------------------------------------
+
+
+def _iter_candidate_dirs() -> list[Path]:
+    """Return the directories that may contain mounted removable volumes."""
+    if sys.platform == "win32":
+        return []
+
+    searchpaths = [Path("/mnt"), Path("/media")]
+    if sys.platform == "darwin":
+        searchpaths = [Path("/Volumes")]
+    elif sys.platform == "linux":
+        user = environ_user()
+        if user:
+            searchpaths += [Path("/media") / user, Path("/run/media") / user]
+        sudo_user = os.environ.get("SUDO_USER")
+        if sudo_user:
+            searchpaths += [
+                Path("/media") / sudo_user,
+                Path("/run/media") / sudo_user,
+            ]
+    return searchpaths
+
+
+def environ_user() -> str | None:
+    """Return the current user name from the environment.
+
+    Tried under several variable names so the search works on macOS, Linux and
+    Windows shells alike.
+
+    Returns:
+        The user name, or ``None`` if it cannot be determined.
+    """
+    for var in ("USER", "USERNAME", "LOGNAME"):
+        value = os.environ.get(var)
+        if value:
+            return value
+    return None
+
+
+def get_drives() -> list[Path]:
+    """Find mounted Pico boot drives.
+
+    A drive qualifies when it contains the ``INFO_UF2.TXT`` marker the boot ROM
+    writes when it presents the flash as a USB mass-storage device.
+
+    Returns:
+        Every qualifying mount point.
+    """
+    drives: list[Path] = []
+
+    if sys.platform == "win32":
+        command = (
+            "(Get-Volume | Where-Object { $_.FileSystemLabel -match 'RP2350|RPI-RP2' })"
+            ".DriveLetter"
+        )
+        try:
+            raw = subprocess.check_output(
+                ["powershell", "-Command", command],
+                text=True,
+            )
+        except (subprocess.CalledProcessError, FileNotFoundError, OSError):
+            return []
+        for letter in raw.split():
+            if len(letter) == 1 and letter.isalpha():
+                drives.append(Path(f"{letter.upper()}:\\"))
+        return drives
+
+    for rootpath in _iter_candidate_dirs():
+        if not rootpath.is_dir():
+            continue
+        try:
+            entries = list(rootpath.iterdir())
+        except OSError:
+            continue
+        for entry in entries:
+            if not entry.is_dir():
+                continue
+            if (entry / INFO_FILE).is_file():
+                drives.append(entry)
+    return drives
+
+
+def board_id(path: Path) -> str:
+    """Read the ``Board-ID`` field from a boot drive's info file.
+
+    Args:
+        path: Mount point of the boot drive.
+
+    Returns:
+        The board ID string, for example ``RP2350``.
+
+    Raises:
+        Uf2Error: If the info file is missing or has no ``Board-ID`` field.
+    """
+    info = path / INFO_FILE
+    if not info.is_file():
+        msg = f"Not a Pico boot drive: {path} has no {INFO_FILE}"
+        raise Uf2Error(msg)
+    match = re.search(r"Board-ID: ([^\r\n]*)", info.read_text())
+    if match is None:
+        msg = f"No Board-ID field in {info}"
+        raise Uf2Error(msg)
+    return match.group(1)
+
+
+def list_drives() -> None:
+    """Print every connected Pico boot drive and its board ID."""
+    for drive in get_drives():
+        try:
+            print(drive, board_id(drive))
+        except Uf2Error as exc:
+            print(f"{drive} <unreadable: {exc}>")
+
+
+def write_file(name: Path | str, buf: bytes) -> None:
+    """Write a buffer to disk and report the size written.
+
+    Args:
+        name: Destination path.
+        buf: Bytes to write.
+    """
+    path = Path(name)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(buf)
+    print(f"Wrote {len(buf)} bytes to {path}")
+
+
+def load_families() -> dict[str, int]:
+    """Load the family-name to family-ID table.
+
+    ``uf2families.json`` is read from the directory containing this script, so
+    the converter works regardless of the caller's working directory.
+
+    Returns:
+        Mapping of upper-case short name to family ID.
+
+    Raises:
+        Uf2Error: If the JSON file is missing or malformed.
+    """
+    pathname = Path(__file__).resolve().parent / "uf2families.json"
+    try:
+        raw_families = json.loads(pathname.read_text())
+    except FileNotFoundError as exc:
+        msg = f"Required family table not found: {pathname}"
+        raise Uf2Error(msg) from exc
+    except json.JSONDecodeError as exc:
+        msg = f"Malformed family table {pathname}: {exc}"
+        raise Uf2Error(msg) from exc
+
+    return {fam["short_name"]: int(fam["id"], 0) for fam in raw_families}
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Construct the command-line argument parser.
+
+    Returns:
+        A configured :class:`argparse.ArgumentParser`.
+    """
+    parser = argparse.ArgumentParser(
+        prog="uf2conv.py",
+        description="Convert firmware between Intel HEX, raw BIN and UF2.",
+        epilog=(
+            "Course example (RP2350 raw image built for XIP flash):\n"
+            "  python ../uf2conv.py build/image-h.bin "
+            "--base 0x10000000 \\\n"
+            "      --family 0xe48bff59 --output build/hacked.uf2\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "input",
+        metavar="INPUT",
+        nargs="?",
+        help="input file (HEX, BIN or UF2); omit when using --list",
+    )
+    parser.add_argument(
+        "-b",
+        "--base",
+        default=hex(DEFAULT_BASE_ADDRESS),
+        help=(
+            "base address of the application for BIN input "
+            f"(default: {hex(DEFAULT_BASE_ADDRESS)}; use 0x10000000 for RP2350 XIP)"
+        ),
+    )
+    parser.add_argument(
+        "-f",
+        "--family",
+        default=hex(DEFAULT_FAMILY_ID),
+        help=(
+            "family ID as a number or a name from uf2families.json "
+            f"(default: {hex(DEFAULT_FAMILY_ID)}; RP2350 is 0xe48bff59)"
+        ),
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        metavar="FILE",
+        help='write output to FILE; defaults to "flash.uf2" or "flash.bin"',
+    )
+    parser.add_argument(
+        "-d",
+        "--device",
+        dest="device_path",
+        help="select a specific device path to flash (reserved; unused)",
+    )
+    parser.add_argument(
+        "-l",
+        "--list",
+        action="store_true",
+        help="list connected Pico boot drives and exit",
+    )
+    parser.add_argument(
+        "-c",
+        "--convert",
+        action="store_true",
+        help="convert only; do not deploy to a mounted boot drive",
+    )
+    parser.add_argument(
+        "-D",
+        "--deploy",
+        action="store_true",
+        help="deploy the input file unchanged; do not convert",
+    )
+    parser.add_argument(
+        "-w",
+        "--wait",
+        action="store_true",
+        help="poll for a boot drive to appear instead of failing immediately",
+    )
+    parser.add_argument(
+        "-C",
+        "--carray",
+        action="store_true",
+        help="emit a C array initialiser instead of a UF2 file",
+    )
+    parser.add_argument(
+        "-i",
+        "--info",
+        action="store_true",
+        help="print UF2 header information and exit without converting",
+    )
+    return parser
+
+
+def _resolve_family(spec: str) -> int:
+    """Resolve a ``--family`` value to a numeric family ID.
+
+    Args:
+        spec: Either a family short name (case-insensitive) or an integer
+            literal such as ``0xe48bff59``.
+
+    Returns:
+        The numeric family ID.
+
+    Raises:
+        Uf2Error: If the value is neither a known name nor a valid integer.
+    """
+    families = load_families()
+    if spec.upper() in families:
+        return families[spec.upper()]
+    try:
+        return int(spec, 0)
+    except ValueError as exc:
+        msg = "Family ID needs to be a number or one of: " + ", ".join(families)
+        raise Uf2Error(msg) from exc
+
+
+def _wait_for_drive() -> Path | None:
+    """Poll for a boot drive to be mounted.
+
+    Returns:
+        The first drive found, or ``None`` if the wait was interrupted.
+    """
+    print("Waiting for drive to deploy...")
+    while True:
+        drives = get_drives()
+        if drives:
+            return drives[0]
+        sleep(0.1)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the command-line converter.
+
+    Args:
+        argv: Argument list, defaulting to :data:`sys.argv` ``[1:]``.
+
+    Returns:
+        ``0`` on success, ``1`` on a user or input error.
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    ctx = ConverterContext()
+    try:
+        ctx.familyid = _resolve_family(args.family)
+        ctx.appstartaddr = int(args.base, 0)
+    except (Uf2Error, ValueError) as exc:
+        print(exc, file=sys.stderr)
+        return 1
+
+    if args.list:
+        list_drives()
+        return 0
+
+    if not args.input:
+        print("Need an input file (or use --list)", file=sys.stderr)
+        return 1
+
+    source = Path(args.input)
+    if not source.is_file():
+        print(f"error: file not found: {source}", file=sys.stderr)
+        return 1
+
+    inpbuf = source.read_bytes()
+    from_uf2 = is_uf2(inpbuf)
+    ext = "uf2"
+
+    try:
+        if args.deploy:
+            outbuf = inpbuf
+        elif from_uf2 and not args.info:
+            outbuf = convert_from_uf2(inpbuf, ctx)
+            ext = "bin"
+        elif from_uf2 and args.info:
+            outbuf = b""
+            convert_from_uf2(inpbuf, ctx)
+        elif is_hex(inpbuf):
+            outbuf = convert_from_hex_to_uf2(inpbuf.decode("utf-8"), ctx)
+        elif args.carray:
+            outbuf = convert_to_carray(inpbuf)
+            ext = "h"
+        else:
+            outbuf = convert_to_uf2(inpbuf, ctx)
+    except Uf2Error as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if not args.deploy and not args.info:
+        print(
+            f"Converted to {ext}, output size: {len(outbuf)}, "
+            f"start address: {ctx.appstartaddr or 0:#x}",
+        )
+
+    if (args.convert or ext != "uf2") and args.output is None:
+        args.output = f"flash.{ext}"
+    if args.output:
+        write_file(args.output, outbuf)
+
+    if ext == "uf2" and not args.convert and not args.info:
+        drives = get_drives()
+        if not drives:
+            if args.wait:
+                found = _wait_for_drive()
+                drives = [found] if found else []
+            elif not args.output:
+                print("error: no drive to deploy", file=sys.stderr)
+                return 1
+        for drive in drives:
+            print(f"Flashing {drive} ({board_id(drive)})")
+            write_file(drive / "NEW.UF2", outbuf)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())