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.
436 lines
16 KiB
Python
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,
|
|
)
|