Files
nvcurve/nvcurve/wireview_firmware.py
T
ARIA 1e11a2c18b feat: wireview firmware check + DFU flash (bundled image, dfu-util)
Port of the wireview-linux firmware update feature:

- nvcurve/wireview_firmware.py: Intel-HEX parser (checksum-verified),
  BuildStruct identity extraction (vendor/product/version/build string
  at image base + 192), compatibility verdicts (version then build
  date, Noctua Edition product alias + 2026-09-02 floor), and a
  dfu-util flasher (progress parsing, exit-74-after-:leave quirk,
  timeouts).
- Bundle TG-WV-PRO2-FW.hex (v05, build 20260902_0741, base
  0x08000000) in nvcurve/firmware/.
- WireViewSerialDevice.enter_bootloader() sends the top-level 0xF1
  command; vendor/product ids are exposed in info().
- GET /api/wireview/firmware (device vs. bundled verdict, dfu-util
  availability, flash state) and POST /api/wireview/firmware/flash
  (gates: serial transport, product match, Noctua floor, downgrade/
  same require override). The flash runs as a background task
  (bootloader -> wait for 0483:df11 -> dfu-util) with progress
  streamed over /ws/wireview.
- WireView tab: Firmware card with device vs. bundled firmware,
  verdict, dfu-util/hwmon warnings, confirm dialog, live progress
  bar; re-checks after the device reboots.
- tests/test_wireview_firmware.py: 66 tests (HEX parser, checksum
  rejection, identity, all verdict paths, mocked flasher, bootloader
  command via pty); added to the Makefile test target.
- Docs: firmware section in docs/WireView.md, README note.
2026-10-05 20:07:19 +02:00

436 lines
16 KiB
Python

"""Firmware check and DFU flashing for the Thermal Grizzly WireView Pro II.
Ported from the wireview-linux project (WireView2/Services/FirmwareHexInfo.cs
and DfuUtilFlasher.cs), which follows the same DFU procedure as the official
Windows client:
1. The device is restarted into its STM32 DFU bootloader over the serial
port (top-level command 0xF1). It re-enumerates as USB device 0483:df11.
2. The bundled Intel-HEX image is flattened to a raw binary (gaps padded
with 0xFF, the erased-flash value) and downloaded with
``dfu-util -d 0483:df11 -a 0 -s 0x<base>:leave -D <bin>``.
The firmware's BuildStruct sits at a fixed offset from the image's lowest
address: vendor id at +192, product id at +193, version byte at +194, a
32-byte NUL-terminated ASCII build string at +227 (192+35). Comparisons
match the upstream Windows client so verdicts agree across ports.
Flashing is at your own risk: a power loss or unplug mid-flash can leave the
device unbootable until it is reflashed manually.
"""
from __future__ import annotations
import logging
import re
import subprocess
import threading
import time
from collections.abc import Callable
from dataclasses import dataclass
from datetime import date, datetime
from pathlib import Path
log = logging.getLogger("nvcurve.wireview_firmware")
# ── Bundled image ─────────────────────────────────────────────────────────────
FIRMWARE_FILENAME = "TG-WV-PRO2-FW.hex"
def bundled_firmware_path() -> Path:
"""Path of the firmware image shipped with nvcurve."""
return Path(__file__).resolve().parent / "firmware" / FIRMWARE_FILENAME
# ── Intel-HEX parsing ─────────────────────────────────────────────────────────
BUILD_STRUCT_OFFSET = 192
VENDOR_ID_OFFSET_IN_BUILD_STRUCT = 0
PRODUCT_ID_OFFSET_IN_BUILD_STRUCT = 1
VERSION_OFFSET_IN_BUILD_STRUCT = 2
BUILD_INFO_OFFSET_IN_BUILD_STRUCT = 35
BUILD_INFO_LENGTH = 32
MAX_IMAGE_SIZE = 4 * 1024 * 1024 # sanity cap, as in wireview-linux
class FirmwareImageError(ValueError):
"""The firmware image is missing, malformed, or implausible."""
def _parse_hex_to_memory_map(hex_path: str | Path) -> dict[int, int]:
"""Parse an Intel-HEX file into {absolute_address: byte}.
Supports data records (0x00), EOF (0x01), extended segment address
(0x02) and extended linear address (0x04). Record checksums are
verified; a corrupt file must never be flashed.
"""
mem: dict[int, int] = {}
upper_linear = 0
upper_segment = 0
have_linear = False
try:
path = Path(hex_path)
if not path.is_file():
raise FirmwareImageError(f"Firmware image not found: {hex_path}")
f = path.open(encoding="ascii", errors="replace")
except OSError as exc:
raise FirmwareImageError(f"Cannot read firmware image {hex_path}: {exc}") from exc
with f:
for raw in f:
line = raw.strip()
if len(line) < 11 or not line.startswith(":"):
continue
# Checksum: low byte of the sum of all bytes in the record (the
# count/address/type fields plus data) must be 0.
try:
record_bytes = bytes.fromhex(line[1:])
except ValueError as exc:
raise FirmwareImageError(f"Malformed HEX record: {line!r}") from exc
if sum(record_bytes) & 0xFF != 0:
raise FirmwareImageError(f"Bad checksum in HEX record: {line!r}")
count = record_bytes[0]
addr = int.from_bytes(record_bytes[1:3], "big")
record_type = record_bytes[3]
if record_type == 0: # data
base = (upper_linear << 16) if have_linear else upper_segment
for i in range(count):
mem[base + addr + i] = record_bytes[4 + i]
elif record_type == 1: # EOF
break
elif record_type == 2: # extended segment address
upper_segment = int.from_bytes(record_bytes[4:6], "big") << 4
have_linear = False
elif record_type == 4: # extended linear address
upper_linear = int.from_bytes(record_bytes[4:6], "big")
have_linear = True
return mem
@dataclass(frozen=True)
class FirmwareImageInfo:
"""Identity of a firmware image: the BuildStruct's vendor/product id,
version and build string (e.g. "TG-WV-PRO2-FW_20260902_0741")."""
vendor_id: int
product_id: int
version: int
build_string: str | None
@property
def build_time(self) -> datetime | None:
"""The build string's yyyyMMdd_HHmm timestamp, None when absent."""
return parse_build_timestamp(self.build_string)
def parse_build_timestamp(build_string: str | None) -> datetime | None:
"""Parse the build timestamp out of a build string such as
"TG-WV-PRO2-FW_20260902_0741" (upstream's TryParseBuildTimestamp)."""
if not build_string:
return None
m = re.search(r"_(\d{8})_(\d{4})(?!\d)", build_string)
if not m:
return None
try:
return datetime.strptime(m.group(1) + m.group(2), "%Y%m%d%H%M")
except ValueError:
return None
def read_firmware_info(hex_path: str | Path) -> FirmwareImageInfo:
"""Read the firmware identity out of a bundled Intel-HEX image."""
mem = _parse_hex_to_memory_map(hex_path)
if not mem:
raise FirmwareImageError("HEX file does not contain data records.")
build_struct = min(mem) + BUILD_STRUCT_OFFSET
if build_struct + VERSION_OFFSET_IN_BUILD_STRUCT not in mem:
raise FirmwareImageError("BuildStruct firmware version byte not found.")
if (
build_struct + VENDOR_ID_OFFSET_IN_BUILD_STRUCT not in mem
or build_struct + PRODUCT_ID_OFFSET_IN_BUILD_STRUCT not in mem
):
raise FirmwareImageError("BuildStruct vendor/product id not found.")
build_string: str | None = None
build_info_base = build_struct + BUILD_INFO_OFFSET_IN_BUILD_STRUCT
text = bytearray()
complete = True
for i in range(BUILD_INFO_LENGTH):
if build_info_base + i not in mem:
complete = False
break
text.append(mem[build_info_base + i])
if complete:
nul = text.find(0)
build_string = (
bytes(text[: nul if nul >= 0 else BUILD_INFO_LENGTH])
.decode("ascii", errors="replace")
.strip()
)
return FirmwareImageInfo(
mem[build_struct + VENDOR_ID_OFFSET_IN_BUILD_STRUCT],
mem[build_struct + PRODUCT_ID_OFFSET_IN_BUILD_STRUCT],
mem[build_struct + VERSION_OFFSET_IN_BUILD_STRUCT],
build_string,
)
def read_firmware_image(hex_path: str | Path) -> tuple[int, bytes]:
"""Convert an Intel-HEX image to a flat binary suitable for dfu-util,
padding gaps with 0xFF (erased-flash value). Returns (base_address, image)."""
mem = _parse_hex_to_memory_map(hex_path)
if not mem:
raise FirmwareImageError("HEX file does not contain data records.")
min_addr, max_addr = min(mem), max(mem)
size = max_addr - min_addr + 1
if size > MAX_IMAGE_SIZE:
raise FirmwareImageError(f"Firmware image is implausibly large ({size} bytes).")
buf = bytearray(b"\xFF" * size)
for addr, value in mem.items():
buf[addr - min_addr] = value
return min_addr, bytes(buf)
# ── Compatibility verdicts ────────────────────────────────────────────────────
# Same rules as wireview-linux's FirmwareCompatibility (upstream 1.0.8's
# FirmwareProductIdAliases / CompareBundledFirmwareToDevice, plus the Noctua
# Edition floor).
VENDOR_ID_THERMAL_GRIZZLY = 0xEF
PRODUCT_ID_PRO2 = 0x05
PRODUCT_ID_PRO2_NOCTUA = 0x06
#: Device (vendor, product) served by another product's image: the Noctua
#: Edition runs the Pro II firmware.
PRODUCT_ALIASES = {(VENDOR_ID_THERMAL_GRIZZLY, PRODUCT_ID_PRO2_NOCTUA): PRODUCT_ID_PRO2}
#: First firmware build with Noctua Edition support
#: (TG-WV-PRO2-FW_20260902_0741). An older image never goes onto product 6.
NOCTUA_MINIMUM_BUILD_DATE = date(2026, 9, 2)
# Verdicts, in gate order: product (with the alias), then the Noctua date
# floor, then version and build date. product_mismatch and too_old_for_noctua
# refuse the flash outright; downgrade and same need an explicit override;
# unknown (equal version, a build date missing) goes ahead like upstream.
VERDICT_NEWER = "newer"
VERDICT_SAME = "same"
VERDICT_UNKNOWN = "unknown"
VERDICT_DOWNGRADE = "downgrade"
VERDICT_PRODUCT_MISMATCH = "product_mismatch"
VERDICT_TOO_OLD_FOR_NOCTUA = "too_old_for_noctua"
def firmware_product_id(vendor_id: int, product_id: int) -> int:
"""The product id whose firmware serves this device (alias applied)."""
return PRODUCT_ALIASES.get((vendor_id, product_id), product_id)
def product_matches(
image: FirmwareImageInfo, device_vendor_id: int, device_product_id: int
) -> bool:
"""Same vendor, and the image's product is the device's (aliased) one."""
return (
device_vendor_id != 0
and image.vendor_id == device_vendor_id
and image.product_id == firmware_product_id(device_vendor_id, device_product_id)
)
def compare(
image: FirmwareImageInfo,
device_version: int | None,
device_build_time: datetime | None,
) -> int | None:
"""Version first, then build timestamp. Positive when the image is newer,
negative when older, None when either side is unknown."""
if device_version is None:
return None
by_version = (image.version > device_version) - (image.version < device_version)
if by_version != 0:
return by_version
image_time = image.build_time
if image_time is None or device_build_time is None:
return None
return (image_time > device_build_time) - (image_time < device_build_time)
def is_below_noctua_floor(
image: FirmwareImageInfo, device_vendor_id: int, device_product_id: int
) -> bool:
"""True when the image predates Noctua Edition support and the device is
one. An image without a parsable build date counts as too old."""
if (device_vendor_id, device_product_id) != (
VENDOR_ID_THERMAL_GRIZZLY,
PRODUCT_ID_PRO2_NOCTUA,
):
return False
t = image.build_time
return t is None or t.date() < NOCTUA_MINIMUM_BUILD_DATE
def evaluate(
image: FirmwareImageInfo,
device_vendor_id: int,
device_product_id: int,
device_version: int | None,
device_build_time: datetime | None,
) -> str:
"""Whether a firmware image may go onto a device, as a verdict string."""
if not product_matches(image, device_vendor_id, device_product_id):
return VERDICT_PRODUCT_MISMATCH
if is_below_noctua_floor(image, device_vendor_id, device_product_id):
return VERDICT_TOO_OLD_FOR_NOCTUA
cmp = compare(image, device_version, device_build_time)
if cmp is None:
return VERDICT_UNKNOWN
if cmp < 0:
return VERDICT_DOWNGRADE
if cmp > 0:
return VERDICT_NEWER
return VERDICT_SAME
# ── DFU flashing via dfu-util ─────────────────────────────────────────────────
DFU_VID = "0483"
DFU_PID = "df11"
DFU_DEVICE_TAG = f"[{DFU_VID}:{DFU_PID}]"
#: dfu-util redraws its progress bar with '\r' — the latest percentage in the
#: current line.
_PROGRESS_RE = re.compile(r"(\d{1,3})\s*%")
#: dfu-util exits 74 ("EX_IOERR") on some versions when the device detaches
#: right after ":leave" even though the download finished.
_DFU_UTIL_IOERR = 74
class FirmwareFlashError(RuntimeError):
"""The DFU flash failed; the message carries dfu-util's output."""
class DfuUtilFlasher:
"""Flashes firmware to the WireView Pro II's STM32 DFU bootloader
(0483:df11) by driving the system dfu-util binary. Requires the dfu-util
package and the udev rule for unprivileged USB access."""
@staticmethod
def dfu_util_version() -> str | None:
"""The dfu-util version string (first output line), or None if the
binary is missing or broken."""
try:
proc = subprocess.run(
["dfu-util", "--version"],
capture_output=True,
text=True,
timeout=5,
)
except (OSError, subprocess.TimeoutExpired):
return None
if proc.returncode != 0:
return None
out = proc.stdout.strip()
first = out.splitlines()[0].strip() if out else ""
return first or None
@staticmethod
def wait_for_dfu_device(timeout_s: float = 20.0) -> bool:
"""Poll ``dfu-util -l`` until the bootloader shows up (the device
re-enumerates a moment after the bootloader command). False on timeout."""
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
try:
proc = subprocess.run(
["dfu-util", "-l"],
capture_output=True,
text=True,
timeout=5,
)
if proc.returncode == 0 and DFU_DEVICE_TAG in proc.stdout.lower():
return True
except (OSError, subprocess.TimeoutExpired):
# dfu-util hiccup; keep polling until the deadline.
pass
time.sleep(0.5)
return False
@staticmethod
def flash(
bin_path: str | Path,
base_address: int,
progress_cb: Callable[[float], None] | None = None,
timeout_s: float = 300.0,
) -> None:
"""Download a flat firmware image to internal flash and reboot the
device (DfuSe ":leave"). progress_cb receives 0..1, parsed from
dfu-util's output. Raises FirmwareFlashError with dfu-util's output on
failure."""
args = [
"dfu-util",
f"-d {DFU_VID}:{DFU_PID}",
"-a",
"0",
f"-s 0x{base_address:08X}:leave",
"-D",
str(bin_path),
]
try:
proc = subprocess.Popen(
args,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
)
except OSError as exc:
raise FirmwareFlashError(f"Could not run dfu-util: {exc}") from exc
stdout_parts: list[str] = []
def _read_stdout() -> None:
# dfu-util redraws its progress bar with '\r', so read
# char-by-char and surface the latest percentage as it arrives.
line: list[str] = []
while True:
ch = proc.stdout.read(1) # type: ignore[union-attr]
if ch == "":
break
stdout_parts.append(ch)
if ch in "\r\n":
m = _PROGRESS_RE.search("".join(line))
if m and progress_cb is not None:
progress_cb(min(100, max(0, int(m.group(1)))) / 100.0)
line = []
else:
line.append(ch)
reader = threading.Thread(target=_read_stdout, daemon=True)
reader.start()
try:
proc.wait(timeout=timeout_s)
except subprocess.TimeoutExpired:
proc.kill()
reader.join(timeout=5)
raise FirmwareFlashError(
f"dfu-util did not finish within {timeout_s:.0f}s."
) from None
reader.join(timeout=5)
stderr = proc.stderr.read() if proc.stderr else ""
stdout = "".join(stdout_parts)
downloaded = "File downloaded successfully" in (stdout + stderr)
if proc.returncode != 0 and not downloaded:
detail = (stderr or stdout).strip()
if len(detail) > 600:
detail = "…" + detail[-600:]
raise FirmwareFlashError(f"dfu-util failed (exit {proc.returncode}).\n{detail}")
if proc.returncode == _DFU_UTIL_IOERR:
log.warning(
"dfu-util exited %d after the device detached (treated as success)",
_DFU_UTIL_IOERR,
)