Technician tool v0.8

Imported from the Google Drive folder 004-technician_tool/v0.8.

README.md

@@ -0,0 +1,41 @@
+# KOTA Sensorbox Technician Tool v0.8
+
+Diagnoza sensorboxa przez USB, wgrywanie firmware z folderu `firmware/` i przygotowanie karty SD.
+Działa na Windows 10/11 i macOS 13 (Ventura) lub nowszym, na Macach z Intelem i Apple Silicon.
+
+## Uruchomienie
+
+**Windows:** dwuklik `run_windows.bat`.
+
+**macOS:** dwuklik `run_macos.command`.
+Jeśli Finder odpowie, że pliku nie można uruchomić (Google Drive gubi uprawnienie „wykonywalny”),
+otwórz Terminal i jednorazowo wpisz `bash ` (ze spacją), przeciągnij plik `run_macos.command` do okna i naciśnij Enter.
+Na stałe naprawia to: `chmod +x run_macos.command`.
+
+Przy pierwszym uruchomieniu skrypt proponuje instalację `uv` (menedżer Pythona, instaluje się tylko dla bieżącego
+użytkownika) i pobiera biblioteki. Potrzebny jest internet, trwa to 1–2 minuty. Kolejne starty są natychmiastowe.
+Środowisko jest poza folderem Google Drive:
+`%LOCALAPPDATA%\KotaTechnicianTool\venv-0.8` (Windows), `~/Library/Caches/KotaTechnicianTool/venv-0.8` (macOS).
+
+Sesje, kopie zapasowe flash i ustawienia są w `~/KotaTechnicianTool` (Windows: `C:\Users\<użytkownik>\KotaTechnicianTool`).
+
+## Port sensorboxa
+
+- Windows: `COMx - Sensorbox (native USB) [MAC]`
+- macOS: `/dev/cu.usbmodemXXXX - Sensorbox (native USB) [MAC]`
+
+Kabel USB musi przenosić dane (nie tylko ładowanie). Przy restartach z komunikatem o brownout użyj innego portu
+lub zasilacza.
+
+## Firmware
+
+Wgrać można tylko pliki `.bin` z folderu `firmware/`. Lista pokazuje datę kompilacji zapisaną w pliku,
+najnowszy build jest na górze. Nowy build: wrzuć plik do `firmware/` i kliknij **Refresh list**.
+
+## Testy (dla zespołu)
+
+```
+uv run --frozen pytest -q
+```
+
+Zmiany: `docs/CHANGES-v0.7.md`, `docs/CHANGES-v0.8.md`.

docs/CHANGES-v0.7.md

@@ -0,0 +1,23 @@
+# Technician tool v0.7 - changes
+
+## Serial reading (firmware 1.0.16+, see firmware-diagnostics-what-changed.md)
+- `KOTA: <record> key=value` lines are parsed into fields (`core/logline.py`, kind `KOTA`) and interpreted
+  directly by the engine (`diag/engine.py` `_kota_*`, knowledge in `diag/kota.py`) instead of regex rules:
+  boot, i2c, rtc, sd, matter, mic, health, status, led, restart.
+- Exact status LED (colour + pattern + meaning) from `led` lines; `status` lines give the reason and a
+  status finding that is resolved when the status changes. Cyan LED supported.
+- Restart cause from `last_restart=` / `restart reason=`; state before a restart from `led previous_boot`.
+- Error IDs `[E-XX-NN]`: looked up in `diag/error_ids.csv` (copy of the firmware's docs/error_ids.csv);
+  shown with the technician action. Old message rules still match (ID prefix is stripped for matching).
+- Diagnosis panel: new "Box self-report" section; log view filter "KOTA diagnostics + errors".
+- Matter QR dialog uses the exact QR/manual code reported by the box.
+- Older firmware (v1.0) is still diagnosed as before.
+
+## Flashing
+- Only `.bin` files in the tool's `firmware/` folder can be flashed (import / developer library removed,
+  no manifest needed). The list shows the compile date read from the firmware itself, newest first.
+- "Refresh list" and "Open firmware folder" buttons; broken or duplicate files are listed as "Not offered".
+- Flash verification compares the 8-digit build hash from the `KOTA: boot` line.
+
+Note: the KOTA lines are tested against lines built from the firmware source; the firmware has not yet
+been confirmed on hardware.

docs/CHANGES-v0.8.md

@@ -0,0 +1,21 @@
+# Technician tool v0.8 - changes
+
+## Windows + macOS
+- Dependencies verified to install on macOS arm64 and x86_64 (uv.lock: PySide6 6.11 universal2 wheels,
+  requires macOS 13+); Windows unchanged.
+- SD card check: macOS `diskutil` reports FAT32 partitions as `DOS_FAT_32` / `Windows_FAT_32`; these are now
+  accepted (previously a correct card was reported as "not FAT32" on a Mac).
+- Unit tests for the macOS serial-port filter (`/dev/cu.*` only) and FAT32 names.
+- README.md with launch steps for both systems (incl. the Google Drive executable-bit workaround on macOS);
+  docs/mac_agent_command.txt updated for a v0.8 test run on a Mac.
+
+## Diagnosis
+- Harmless Wi-Fi start-up errors are ignored (rule `benign.wifi_start`): `wifi:sta is connecting, return error`,
+  `esp_wifi_connect() failed: ESP_ERR_WIFI_CONN`, `Failed to get configured network when updating network
+  status` (unpaired box).
+- Brown-out resets are detected (`E BOD: Brownout detector was triggered`, ROM reports RTC_SW_SYS_RST).
+- Service report note = the Diagnosis panel as text (LED, firmware, box self-report, start-up progress with
+  times, findings with "Seen Nx, first at ... s, last at ... s" and log line), shortened to fit the service
+  form's 5000 characters.
+
+Not yet run on a real Mac: see docs/mac_agent_command.txt.

docs/mac_agent_command.txt

@@ -1,30 +1,35 @@
-You are testing the KOTA sensorbox technician tool v0.5 on macOS. The current folder is
-004-technician_tool/v0.5 (a Python/PySide6 desktop app; it has only been tested on Windows so far).
-
-Rules:
-- Python only via uv or conda/mamba. Never use bare/system python or pip.
-- Do not build, modify or flash firmware other than the bundled firmware/new_system.bin.
-- Do not push anything to Git or GitLab. This is a local demo.
-- Ask me before any destructive action: formatting an SD card, Full-mode flashing, or deleting files.
-  Before formatting, show me the exact disk (identifier, name, size, current files).
-- Do not change code without telling me. Report bugs with evidence (commands and output).
-
-Tests, in order. Report pass/fail with evidence for each:
-1. Launch: `bash run_macos.command` (it offers to install uv). The app window opens; note any warnings.
-2. Tests: `UV_PROJECT_ENVIRONMENT="$HOME/Library/Caches/KotaTechnicianTool/venv-0.5" uv run --frozen pytest -q`
-3. Serial: plug in the sensorbox (native USB). The port list shows a /dev/cu.usbmodem* "Sensorbox (native USB)"
-   entry with a MAC. Connect, press "Reset & capture": the boot log starts at "ESP-ROM:esp32s3" and the
-   Diagnosis panel identifies firmware v1.0 (build 45fa9d5b9). Check whether the port disappears after the
-   reset and whether the tool reconnects.
-4. Guided troubleshooting: run "Quick check" and answer truthfully with what I tell you the LED shows.
-5. Flash (App only, factory image; the box already runs it): the tool must enter flashing mode by itself,
-   write, restart the box and report "Success ... build 45fa9d5b9". Capture the esptool output.
-6. SD card tab: the settings load from ../../002-SD_card_format/ENV.txt. The card reader and card are listed
-   (internal disks must NOT be listed). Run "Check card", then, after my OK, "Format card and write ENV.TXT".
-   It must use `diskutil eraseDisk FAT32 KOTA MBRFormat` on the correct disk, write ENV.TXT byte-identical
-   to the template, and eject the card.
-7. "Service report..." opens the browser at https://service.kota-app.com/<MAC>#kota-report=... (it is fine
-   if the page itself cannot prefill yet).
-
-At the end, write a short report: macOS version, Mac model/architecture, each test with result, errors, and
-suggested fixes (file:line).
+You are testing the KOTA sensorbox technician tool v0.8 on macOS. The current folder is
+004-technician_tool/v0.8 (a Python/PySide6 desktop app; tested on Windows 11, macOS paths are covered by
+unit tests but not yet run on a real Mac).
+
+Rules:
+- Python only via uv or conda/mamba. Never use bare/system python or pip.
+- Do not build or modify firmware. Flash only files from the tool's firmware/ folder.
+- Do not push anything to Git or GitLab. This is a local demo.
+- Ask me before any destructive action: formatting an SD card, Full-mode flashing, or deleting files.
+  Before formatting, show me the exact disk (identifier, name, size, current files).
+- Do not change code without telling me. Report bugs with evidence (commands and output).
+
+Tests, in order. Report pass/fail with evidence for each:
+1. Launch: `bash run_macos.command` (it offers to install uv). The app window opens; note any warnings.
+   Also check whether a double-click in Finder works (Google Drive may drop the executable bit).
+2. Tests: `UV_PROJECT_ENVIRONMENT="$HOME/Library/Caches/KotaTechnicianTool/venv-0.8" uv run --frozen pytest -q`
+   (expect 172 passed).
+3. Serial: plug in the sensorbox (native USB). The port list shows a /dev/cu.usbmodem* "Sensorbox (native USB)"
+   entry with a MAC (no /dev/tty.* duplicate). Connect, press "Reset & capture": the log starts at
+   "ESP-ROM:esp32s3" and the Diagnosis panel shows firmware v1.0.16 (build 4f10989e), the "Box self-report"
+   section and the LED with its pattern. Check whether the port disappears after the reset and whether the
+   tool reconnects. Wait 2 minutes: a "KOTA: health" line appears every 60 s.
+4. Show filter "KOTA diagnostics + errors" shows only KOTA lines and errors.
+5. Guided troubleshooting: run "Quick check" and answer truthfully with what I tell you the LED shows.
+6. Flash (App only, the newest file in firmware/, chosen by its compile date): the tool must enter flashing mode
+   by itself, write, restart the box and report "Success ... build 4f10989e". Capture the esptool output.
+7. SD card tab: the card reader and card are listed (internal disks must NOT be listed). "Check card" must NOT
+   report a wrong file system for a FAT32 card. After my OK, "Format card and write ENV.TXT" must use
+   `diskutil eraseDisk FAT32 KOTA MBRFormat` on the correct disk, write ENV.TXT and eject the card.
+8. "Service report..." opens the browser at https://service.kota-app.com/<MAC>#kota-report=...; the note in
+   the form must match the Diagnosis panel (self-report, start-up progress with times, findings with
+   "Seen Nx, first at ... s").
+
+At the end, write a short report: macOS version, Mac model/architecture, each test with result, errors, and
+suggested fixes (file:line).

kota_tech/__init__.py

@@ -1,3 +1,3 @@
 """KOTA sensorbox technician tool."""
 
-__version__ = "0.6.0"
+__version__ = "0.8.0"

kota_tech/core/logline.py

@@ -1,146 +1,202 @@
-"""Serial byte stream -> framed, cleaned, parsed log lines.
-
-ESP-IDF log format: "<L> (<ms since boot>) <TAG>: <message>", optionally
-wrapped in ANSI colour codes. ROM/bootloader output (boot banner, reset
-reason) has no level prefix and is classified separately, since a boot
-banner is the only reliable reboot marker.
-"""
-
-from __future__ import annotations
-
-import re
-import time
-from dataclasses import dataclass, field
-from enum import Enum
-
-from .redact import redact
-
-ANSI_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
-ESP_LOG_RE = re.compile(r"^([EWIDV]) \((\d+)\) ([^:]{1,40}?): ?(.*)$")
-# ESP32-S3 ROM prints e.g. "ESP-ROM:esp32s3-20210327" then
-# "rst:0x1 (POWERON),boot:0x8 (SPI_FAST_FLASH_BOOT)".
-BOOT_BANNER_RE = re.compile(r"^ESP-ROM:")
-RESET_REASON_RE = re.compile(r"^rst:0x([0-9a-fA-F]+) \(([A-Z0-9_]+)\)")
-PANIC_RE = re.compile(
-    r"Guru Meditation Error|abort\(\) was called|ESP_ERROR_CHECK failed|"
-    r"^Backtrace:|Rebooting\.\.\.$"
-)
-
-
-class LineKind(str, Enum):
-    LOG = "log"          # ESP_LOGx line
-    BOOT = "boot"        # ROM boot banner (start of a new boot)
-    RESET = "reset"      # ROM reset-reason line
-    PANIC = "panic"      # crash / abort output
-    RAW = "raw"          # anything else (task list rows, line protocol, ...)
-    HOST = "host"        # event generated by this tool (connect, reset, ...)
-
-
-def host_event(text: str) -> LogLine:
-    return LogLine(f"--- {text} ---", LineKind.HOST)
-
-
-@dataclass(frozen=True)
-class LogLine:
-    text: str                      # cleaned + redacted
-    kind: LineKind
-    host_time: float = field(default_factory=time.time)
-    level: str | None = None       # E/W/I/D/V for LOG lines
-    uptime_ms: int | None = None
-    tag: str | None = None
-    message: str | None = None
-    reset_reason: str | None = None
-
-
-def clean(raw: str) -> str:
-    return ANSI_RE.sub("", raw).replace("\r", "").rstrip()
-
-
-def parse_line(raw: str, host_time: float | None = None) -> LogLine:
-    text = redact(clean(raw))
-    t = time.time() if host_time is None else host_time
-    if m := ESP_LOG_RE.match(text):
-        level, ms, tag, msg = m.groups()
-        return LogLine(text, LineKind.LOG, t, level, int(ms), tag.strip(), msg)
-    if BOOT_BANNER_RE.match(text):
-        return LogLine(text, LineKind.BOOT, t)
-    if m := RESET_REASON_RE.match(text):
-        return LogLine(text, LineKind.RESET, t, reset_reason=m.group(2))
-    if PANIC_RE.search(text):
-        return LogLine(text, LineKind.PANIC, t)
-    return LogLine(text, LineKind.RAW, t)
-
-
-class LineFramer:
-    """Accumulates bytes and yields complete lines.
-
-    A partial line is released after `idle_flush_s` without new bytes so
-    prompts / unterminated output are not held back forever.
-
-    Lines are also split where a new log line starts in the middle
-    ("I (2302) chip[DL]: I (2302) chip[DL]: Posting..."): the two S3 cores
-    interleave output, and the USB-Serial-JTAG FIFO keeps the tail of an old
-    line while no host reads, releasing it glued in front of the next live
-    output. After a (re)open, the fragment in front of the first such split
-    is stale and dropped. Timing cannot identify it, because the FIFO only
-    flushes when the board next prints, possibly seconds later.
-    """
-
-    def __init__(self, idle_flush_s: float = 0.3, max_line: int = 4096,
-                 drop_first_partial: bool = False):
-        self._buf = bytearray()
-        self._last_rx = 0.0
-        self.idle_flush_s = idle_flush_s
-        self.max_line = max_line
-        self._first_line_pending = drop_first_partial
-
-    def cancel_drop(self) -> None:
-        self._first_line_pending = False
-
-    def feed(self, data: bytes, now: float | None = None) -> list[str]:
-        now = time.monotonic() if now is None else now
-        if data:
-            self._buf.extend(data)
-            self._last_rx = now
-        out: list[str] = []
-        while (i := self._buf.find(b"\n")) >= 0:
-            out += self._emit(self._buf[:i])
-            del self._buf[: i + 1]
-        if len(self._buf) >= self.max_line:
-            out += self._emit(self._buf)
-            self._buf.clear()
-        return out
-
-    def poll_idle(self, now: float | None = None) -> list[str]:
-        now = time.monotonic() if now is None else now
-        if self._buf and now - self._last_rx >= self.idle_flush_s:
-            return self.flush()
-        return []
-
-    def flush(self) -> list[str]:
-        if not self._buf:
-            return []
-        out = self._emit(self._buf)
-        self._buf.clear()
-        return out
-
-    def _emit(self, raw: bytes | bytearray) -> list[str]:
-        parts = split_glued(bytes(raw).decode("utf-8", errors="replace"))
-        if self._first_line_pending:
-            self._first_line_pending = False
-            if len(parts) > 1:
-                parts = parts[1:]  # stale FIFO fragment from before the open
-        return parts
-
-
-# Start of a log line (optionally ANSI-coloured) or ROM banner.
-_LINE_START = re.compile(r"(?:\x1b\[[0-9;]*m)?(?:[EWIDV] \(\d+\) \S|ESP-ROM:)")
-
-
-def split_glued(text: str) -> list[str]:
-    # Left-to-right scan so an ANSI colour prefix stays with its line.
-    cuts = [m.start() for m in _LINE_START.finditer(text) if m.start() > 0]
-    if not cuts:
-        return [text]
-    bounds = [0, *cuts, len(text)]
-    return [text[a:b] for a, b in zip(bounds, bounds[1:]) if a < b]
+"""Serial byte stream -> framed, cleaned, parsed log lines.
+
+ESP-IDF log format: "<L> (<ms since boot>) <TAG>: <message>", optionally
+wrapped in ANSI colour codes. ROM/bootloader output (boot banner, reset
+reason) has no level prefix and is classified separately, since a boot
+banner is the only reliable reboot marker.
+
+Firmware 1.0.16+ adds structured diagnostic lines logged under the "KOTA"
+tag ("I (812) KOTA: boot fw=1.0.16 build=4f10989e ... last_restart=none")
+and prefixes every ESP_LOGE message with a stable error ID ("[E-SD-03] ").
+Both are parsed here so the diagnostics engine reads fields directly
+instead of matching message text.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+
+from .redact import redact
+
+ANSI_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+ESP_LOG_RE = re.compile(r"^([EWIDV]) \((\d+)\) ([^:]{1,40}?): ?(.*)$")
+# ESP32-S3 ROM prints e.g. "ESP-ROM:esp32s3-20210327" then
+# "rst:0x1 (POWERON),boot:0x8 (SPI_FAST_FLASH_BOOT)".
+BOOT_BANNER_RE = re.compile(r"^ESP-ROM:")
+RESET_REASON_RE = re.compile(r"^rst:0x([0-9a-fA-F]+) \(([A-Z0-9_]+)\)")
+# "[E-SD-03] Failed to initialize the card ..." (firmware error_ids.csv).
+ERROR_ID_RE = re.compile(r"^\[(E-[A-Z0-9]+-\d{2,})\] ?")
+KOTA_TAG = "KOTA"
+PANIC_RE = re.compile(
+    r"Guru Meditation Error|abort\(\) was called|ESP_ERROR_CHECK failed|"
+    r"^Backtrace:|Rebooting\.\.\.$"
+)
+
+
+class LineKind(str, Enum):
+    LOG = "log"          # ESP_LOGx line
+    BOOT = "boot"        # ROM boot banner (start of a new boot)
+    RESET = "reset"      # ROM reset-reason line
+    PANIC = "panic"      # crash / abort output
+    KOTA = "kota"        # structured "KOTA: <record> key=value ..." line
+    RAW = "raw"          # anything else (task list rows, line protocol, ...)
+    HOST = "host"        # event generated by this tool (connect, reset, ...)
+
+
+def host_event(text: str) -> LogLine:
+    return LogLine(f"--- {text} ---", LineKind.HOST)
+
+
+@dataclass(frozen=True)
+class LogLine:
+    text: str                      # cleaned + redacted
+    kind: LineKind
+    host_time: float = field(default_factory=time.time)
+    level: str | None = None       # E/W/I/D/V for LOG lines
+    uptime_ms: int | None = None
+    tag: str | None = None
+    message: str | None = None
+    reset_reason: str | None = None
+    error_id: str | None = None    # "E-SD-03" when the message carries one
+    record: str | None = None      # KOTA lines: "boot", "i2c", "health", ...
+    fields: dict[str, str] = field(default_factory=dict)   # KOTA key=value pairs
+    words: tuple[str, ...] = ()    # KOTA bare words ("verify", "OK", "->", ...)
+
+    @property
+    def match_text(self) -> str:
+        """Text for message rules: the error-ID prefix removed, so rules
+        written for older firmware keep matching."""
+        if self.error_id and self.message is not None and self.tag:
+            return self.text.replace(f"[{self.error_id}] ", "", 1)
+        return self.text
+
+
+def parse_kota(body: str) -> tuple[str, dict[str, str], tuple[str, ...]]:
+    """'rtc verify running=1 delta=2s ok=1' -> ('rtc', {...}, ('verify',)).
+
+    Values never contain spaces. The mic line has a parenthesised aside
+    ("(GPIO3=1, expected 1)"): brackets and commas are stripped from keys
+    and values, and the aside's words are kept as bare words.
+    """
+    tokens = body.split()
+    if not tokens:
+        return "", {}, ()
+    fields: dict[str, str] = {}
+    words: list[str] = []
+    for tok in tokens[1:]:
+        key, eq, value = tok.partition("=")
+        if eq and key.strip("(,"):
+            key = key.lstrip("(")
+            # "0x68=DS1307(missing)" keeps its bracket; "(GPIO3=1," loses it.
+            value = value.rstrip(",")
+            if tok.startswith("(") or value.endswith(")") and "(" not in value:
+                value = value.rstrip(")")
+            fields[key] = value
+        else:
+            words.append(tok.strip("(),"))
+    return tokens[0], fields, tuple(w for w in words if w)
+
+
+def clean(raw: str) -> str:
+    return ANSI_RE.sub("", raw).replace("\r", "").rstrip()
+
+
+def parse_line(raw: str, host_time: float | None = None) -> LogLine:
+    text = redact(clean(raw))
+    t = time.time() if host_time is None else host_time
+    if m := ESP_LOG_RE.match(text):
+        level, ms, tag, msg = m.groups()
+        tag = tag.strip()
+        if tag == KOTA_TAG:
+            record, fields, words = parse_kota(msg)
+            return LogLine(text, LineKind.KOTA, t, level, int(ms), tag, msg,
+                           record=record, fields=fields, words=words)
+        eid = None
+        if em := ERROR_ID_RE.match(msg):
+            eid, msg = em.group(1), msg[em.end():]
+        return LogLine(text, LineKind.LOG, t, level, int(ms), tag, msg, error_id=eid)
+    if BOOT_BANNER_RE.match(text):
+        return LogLine(text, LineKind.BOOT, t)
+    if m := RESET_REASON_RE.match(text):
+        return LogLine(text, LineKind.RESET, t, reset_reason=m.group(2))
+    if PANIC_RE.search(text):
+        return LogLine(text, LineKind.PANIC, t)
+    return LogLine(text, LineKind.RAW, t)
+
+
+class LineFramer:
+    """Accumulates bytes and yields complete lines.
+
+    A partial line is released after `idle_flush_s` without new bytes so
+    prompts / unterminated output are not held back forever.
+
+    Lines are also split where a new log line starts in the middle
+    ("I (2302) chip[DL]: I (2302) chip[DL]: Posting..."): the two S3 cores
+    interleave output, and the USB-Serial-JTAG FIFO keeps the tail of an old
+    line while no host reads, releasing it glued in front of the next live
+    output. After a (re)open, the fragment in front of the first such split
+    is stale and dropped. Timing cannot identify it, because the FIFO only
+    flushes when the board next prints, possibly seconds later.
+    """
+
+    def __init__(self, idle_flush_s: float = 0.3, max_line: int = 4096,
+                 drop_first_partial: bool = False):
+        self._buf = bytearray()
+        self._last_rx = 0.0
+        self.idle_flush_s = idle_flush_s
+        self.max_line = max_line
+        self._first_line_pending = drop_first_partial
+
+    def cancel_drop(self) -> None:
+        self._first_line_pending = False
+
+    def feed(self, data: bytes, now: float | None = None) -> list[str]:
+        now = time.monotonic() if now is None else now
+        if data:
+            self._buf.extend(data)
+            self._last_rx = now
+        out: list[str] = []
+        while (i := self._buf.find(b"\n")) >= 0:
+            out += self._emit(self._buf[:i])
+            del self._buf[: i + 1]
+        if len(self._buf) >= self.max_line:
+            out += self._emit(self._buf)
+            self._buf.clear()
+        return out
+
+    def poll_idle(self, now: float | None = None) -> list[str]:
+        now = time.monotonic() if now is None else now
+        if self._buf and now - self._last_rx >= self.idle_flush_s:
+            return self.flush()
+        return []
+
+    def flush(self) -> list[str]:
+        if not self._buf:
+            return []
+        out = self._emit(self._buf)
+        self._buf.clear()
+        return out
+
+    def _emit(self, raw: bytes | bytearray) -> list[str]:
+        parts = split_glued(bytes(raw).decode("utf-8", errors="replace"))
+        if self._first_line_pending:
+            self._first_line_pending = False
+            if len(parts) > 1:
+                parts = parts[1:]  # stale FIFO fragment from before the open
+        return parts
+
+
+# Start of a log line (optionally ANSI-coloured) or ROM banner.
+_LINE_START = re.compile(r"(?:\x1b\[[0-9;]*m)?(?:[EWIDV] \(\d+\) \S|ESP-ROM:)")
+
+
+def split_glued(text: str) -> list[str]:
+    # Left-to-right scan so an ANSI colour prefix stays with its line.
+    cuts = [m.start() for m in _LINE_START.finditer(text) if m.start() > 0]
+    if not cuts:
+        return [text]
+    bounds = [0, *cuts, len(text)]
+    return [text[a:b] for a, b in zip(bounds, bounds[1:]) if a < b]

kota_tech/diag/error_ids.csv

@@ -0,0 +1,193 @@
+id,module,severity,message,action
+E-SD-01,SD,error,Failed to take SPI mutex,Internal error - send the log to the firmware team
+E-SD-02,SD,error,"Failed to mount filesystem. If you want the card to be formatted, set the CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option.",SD card is not FAT formatted or is corrupt; reformat it as FAT32 and restore ENV.TXT
+E-SD-03,SD,error,Failed to initialize the card (%s). Make sure SD card lines have pull-up resistors in place.,Reseat the SD card; if it persists replace the card or check the SD connector
+E-SD-04,SD,error,Failed to stat %s,Reseat the SD card; if it persists replace the card or check the SD connector
+E-SD-05,SD,error,Failed to take SPI mutex,Internal error - send the log to the firmware team
+E-ENV-01,ENV,error,Failed to take SPI mutex,Internal error - send the log to the firmware team
+E-ENV-02,ENV,error,Failed to open .env file for reading,Check ENV.TXT on the SD card exists and has NAME=VALUE lines
+E-ENV-03,ENV,error,Failed to take SPI mutex,Internal error - send the log to the firmware team
+E-ENV-04,ENV,error,Failed to open existing .env file for reading; aborting write to avoid losing other variables,Check ENV.TXT on the SD card exists and has NAME=VALUE lines
+E-ENV-05,ENV,error,Failed to open .env file for writing,Check ENV.TXT on the SD card exists and has NAME=VALUE lines
+E-ENV-06,ENV,error,Failed to take SPI mutex,Internal error - send the log to the firmware team
+E-ENV-07,ENV,error,Failed to open existing .env file for reading; aborting delete to avoid losing other variables,Check ENV.TXT on the SD card exists and has NAME=VALUE lines
+E-ENV-08,ENV,error,Failed to open .env file for writing,Check ENV.TXT on the SD card exists and has NAME=VALUE lines
+E-ENV-09,ENV,error,Failed to take SPI mutex,Internal error - send the log to the firmware team
+E-INF-01,INF,error,Error %d at %s:%d,Internal error - send the log to the firmware team
+E-INF-02,INF,error,Failed to initialize HTTP client,Internal error - send the log to the firmware team
+E-INF-03,INF,error,"Failed to perform HTTP request: %d, %s",Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-04,INF,error,"Bad request, check line protocol format: %s",Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-05,INF,error,Failed to read INFLUX_URL from .env file,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-06,INF,error,Failed to read INFLUX_TOKEN from .env file,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-07,INF,error,Failed to take SPI mutex,Internal error - send the log to the firmware team
+E-INF-08,INF,error,Failed to open buffer file for reading,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-09,INF,error,Failed to take SPI mutex,Internal error - send the log to the firmware team
+E-INF-10,INF,error,Failed to open buffer file for clearing,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-11,INF,error,Failed to take SPI mutex,Internal error - send the log to the firmware team
+E-INF-12,INF,error,Failed to create buffer file,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-13,INF,error,Failed to open buffer file for appending,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-14,INF,error,Failed to take SPI mutex,Internal error - send the log to the firmware team
+E-INF-15,INF,error,Failed to open buffer file for counting,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-16,INF,error,Failed to read buffer for flushing: %s,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-17,INF,error,Failed to write chunk to Influx: %s,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-18,INF,error,Failed to write chunk with 5 retries to Influx: %s,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-19,INF,error,Failed to clear buffer after flushing: %s,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-20,INF,error,Failed to flush buffer before writing: %s,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-21,INF,error,Failed to write to Influx: %s,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-INF-22,INF,error,Failed to append new entry to buffer: %s,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-OTA-01,OTA,error,Error %s at %s:%d,Internal error - send the log to the firmware team
+E-OTA-02,OTA,error,Failed to create OTA task,Internal error - send the log to the firmware team
+E-OTA-03,OTA,error,Failed to open NVS: %s,Internal error - send the log to the firmware team
+E-OTA-04,OTA,error,Failed to read OTA token from NVS: %s,Internal error - send the log to the firmware team
+E-OTA-05,OTA,error,Failed to read OTA token from NVS: %s,Internal error - send the log to the firmware team
+E-OTA-06,OTA,error,Failed to get running partition,Check the network connection; if it persists send the log to the firmware team
+E-OTA-07,OTA,error,Failed to get OTA state,Check the network connection; if it persists send the log to the firmware team
+E-OTA-08,OTA,error,Failed to read update metadata from NVS: %s,Internal error - send the log to the firmware team
+E-OTA-09,OTA,error,Failed to report failed selfcheck: %s,Check the network connection; if it persists send the log to the firmware team
+E-OTA-10,OTA,error,Failed to initialize HTTP client,Internal error - send the log to the firmware team
+E-OTA-11,OTA,error,Device registration failed with status code: %d,Check the network connection; if it persists send the log to the firmware team
+E-OTA-12,OTA,error,Device registration failed: %s,Check the network connection; if it persists send the log to the firmware team
+E-OTA-13,OTA,error,Failed to check for updates: %s,Check the network connection; if it persists send the log to the firmware team
+E-OTA-14,OTA,error,Free stack size decreased from %u to %u,Internal error - send the log to the firmware team
+E-OTA-15,OTA,error,Failed to initialize HTTP client,Internal error - send the log to the firmware team
+E-OTA-16,OTA,error,OTA Update check failed with status code: %d,Check the network connection; if it persists send the log to the firmware team
+E-OTA-17,OTA,error,"Update %s has already been tried %u times and failed, not trying again",Internal error - send the log to the firmware team
+E-OTA-18,OTA,error,OTA update failed: %s,Check the network connection; if it persists send the log to the firmware team
+E-OTA-19,OTA,error,Failed to read update metadata from NVS: %s,Internal error - send the log to the firmware team
+E-OTA-20,OTA,error,Failed to read update ID from NVS: %s,Internal error - send the log to the firmware team
+E-OTA-21,OTA,error,Failed to read update ID from NVS: %s,Internal error - send the log to the firmware team
+E-OTA-22,OTA,error,Failed to read update tries from NVS: %s,Internal error - send the log to the firmware team
+E-OTA-23,OTA,error,Failing selfcheck: %s,Firmware update failed its self check and will roll back; check the sensors listed in the log
+E-OTA-24,OTA,error,Failed to send update result: %s,Check the network connection; if it persists send the log to the firmware team
+E-OTA-25,OTA,error,Failed to mark app as invalid for rollback: %s,Internal error - send the log to the firmware team
+E-OTA-26,OTA,error,Failed to send update result: %s,Check the network connection; if it persists send the log to the firmware team
+E-OTA-27,OTA,error,Failed to mark app as valid to commit update: %s,Internal error - send the log to the firmware team
+E-OTA-28,OTA,error,Failed to initialize HTTP client,Internal error - send the log to the firmware team
+E-OTA-29,OTA,error,Failed to send update result with status code: %d,Check the network connection; if it persists send the log to the firmware team
+E-WIFI-01,WIFI,error,esp_netif_init() failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-02,WIFI,error,esp_event_loop_create_default() failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-03,WIFI,error,esp_wifi_init() failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-04,WIFI,error,Failed to register WIFI_EVENT handler: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-05,WIFI,error,Failed to register IP_EVENT handler: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-06,WIFI,error,esp_wifi_set_mode() failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-07,WIFI,error,esp_timer_create() failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-08,WIFI,error,esp_wifi_start() failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-09,WIFI,error,esp_wifi_set_config() failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-10,WIFI,error,esp_wifi_connect() failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-11,WIFI,error,esp_wifi_set_mode(APSTA) failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-12,WIFI,error,esp_wifi_set_config(AP) failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-13,WIFI,error,esp_wifi_connect() failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-14,WIFI,error,esp_wifi_scan_start() failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-15,WIFI,error,esp_wifi_scan_get_ap_num() failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-WIFI-16,WIFI,error,esp_wifi_scan_get_ap_records() failed: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-PROV-01,PROV,error,mdns_init() failed: %s,Retry WiFi provisioning (short button press); restart the device if it persists
+E-PROV-02,PROV,error,httpd_start() failed: %s,Retry WiFi provisioning (short button press); restart the device if it persists
+E-MAIN-01,MAIN,error,Error %d at %s:%d,Internal error - send the log to the firmware team
+E-MAIN-02,MAIN,error,"Failed to open commissioning window, err:%",Internal error - send the log to the firmware team
+E-MAIN-03,MAIN,error,"Attribute update callback: endpoint_id: %u, cluster_id: 0x%lx, attribute_id: 0x%lx",Internal error - send the log to the firmware team
+E-MAIN-04,MAIN,error,Device MAC address: %02X:%02X:%02X:%02X:%02X:%02X,Internal error - send the log to the firmware team
+E-MAIN-05,MAIN,error,Failed to initialize SD card: %s,Reseat the SD card; if it persists replace the card or check the SD connector
+E-MAIN-06,MAIN,error,Failed to initialize EnvironmentService: %s,Check ENV.TXT on the SD card exists and has NAME=VALUE lines
+E-MAIN-07,MAIN,error,Failed to initialize WifiCredentialsService: %s,Check ENV.TXT on the SD card exists and has NAME=VALUE lines
+E-MAIN-08,MAIN,error,WiFi provisioning server failed to start: %s; clearing HTTP_SERVER and restarting,Retry WiFi provisioning (short button press); restart the device if it persists
+E-MAIN-09,MAIN,error,Failed to create Matter node,Internal error - send the log to the firmware team
+E-MAIN-10,MAIN,error,Failed to start ESP-Matter,Internal error - send the log to the firmware team
+E-MAIN-11,MAIN,error,Failed to start WifiService: %s,Check WiFi signal and credentials; re-run WiFi provisioning (short button press)
+E-MAIN-12,MAIN,error,"Failed to initialized the encrypted OTA, err: %d",Internal error - send the log to the firmware team
+E-MAIN-13,MAIN,error,Failed to initialize RTC: %s,Check the RTC (DS1307) and the sensor cable
+E-MAIN-14,MAIN,error,Failed to initialize Influx buffer: %s,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-MAIN-15,MAIN,error,Failed to initialize BME688: %s,Check the BME688 sensor and the sensor cable
+E-MAIN-16,MAIN,error,Failed to initialize SEN66: %s,"Check the SEN66 sensor, its power supply and the sensor cable"
+E-MAIN-17,MAIN,error,Failed to initialize AS7341: %s,Check the AS7341 light sensor and the sensor cable
+E-MAIN-18,MAIN,error,Failed to initialize Microphone: %s,Check the microphone board and its cable
+E-MAIN-19,MAIN,error,Failed to initialize Flicker sensor: %s,Check the flicker sensor and its cable
+E-MAIN-20,MAIN,error,Failed to initialize DeviceStatus: %s,Internal error - send the log to the firmware team
+E-MAIN-21,MAIN,error,BME688 self check failed: %s,Check the BME688 sensor and the sensor cable
+E-MAIN-22,MAIN,error,SEN66 self check failed: %s,"Check the SEN66 sensor, its power supply and the sensor cable"
+E-MAIN-23,MAIN,error,AS7341 self check failed: %s,Check the AS7341 light sensor and the sensor cable
+E-MAIN-24,MAIN,error,Microphone self check failed: %s,Check the microphone board and its cable
+E-MAIN-25,MAIN,error,Flicker sensor self check failed: %s,Check the flicker sensor and its cable
+E-MAIN-26,MAIN,error,Failed to report passed selfcheck: %s,Internal error - send the log to the firmware team
+E-MAIN-27,MAIN,error,Failed to flush Influx buffer: %s,Check the network connection and INFLUX_URL / INFLUX_TOKEN in ENV.TXT
+E-STAT-01,STAT,error,Failed to initialize LED strip: %s,Internal error - send the log to the firmware team
+E-SPI-01,SPI,error,Failed to take SPI mutex,Internal error - send the log to the firmware team
+E-RTC-01,RTC,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-RTC-02,RTC,error,Failed to add I2C device: %s,Check the RTC (DS1307) and the sensor cable
+E-RTC-03,RTC,error,Failed to initialize DS1307 control register: %s,Check the RTC (DS1307) and the sensor cable
+E-RTC-04,RTC,error,Attempted to set time on uninitialized DS1307,Internal error - send the log to the firmware team
+E-RTC-05,RTC,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-RTC-06,RTC,error,Attempted to get time on uninitialized DS1307,Internal error - send the log to the firmware team
+E-RTC-07,RTC,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-RTC-08,RTC,error,Attempted to start updating time on uninitialized DS1307,Internal error - send the log to the firmware team
+E-BME-01,BME,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-BME-02,BME,error,Failed to add I2C device: %d,Check the BME688 sensor and the sensor cable
+E-BME-03,BME,error,Failed to initialize BME688: %d,Check the BME688 sensor and the sensor cable
+E-BME-04,BME,error,Failed to set BME688 configuration: %d,Check the BME688 sensor and the sensor cable
+E-BME-05,BME,error,Failed to set BME688 heater configuration: %d,Check the BME688 sensor and the sensor cable
+E-BME-06,BME,error,Failed to set BME688 operation mode: %d,Check the BME688 sensor and the sensor cable
+E-BME-07,BME,error,Failed to get BME688 data: %d,Check the BME688 sensor and the sensor cable
+E-BME-08,BME,error,No new data available from BME688,Check the BME688 sensor and the sensor cable
+E-BME-09,BME,error,Failed to get data from BME688: %s,Check the BME688 sensor and the sensor cable
+E-BME-10,BME,error,Self check failed: %s,Check the BME688 sensor and the sensor cable
+E-BME-11,BME,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-BME-12,BME,error,I2C read failed: %s,Check the BME688 sensor and the sensor cable
+E-BME-13,BME,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-BME-14,BME,error,Failed to allocate memory for I2C write buffer,Internal error - send the log to the firmware team
+E-BME-15,BME,error,I2C write failed: %s,Check the BME688 sensor and the sensor cable
+E-SEN-01,SEN,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-SEN-02,SEN,error,Failed to add I2C device: %d,"Check the SEN66 sensor, its power supply and the sensor cable"
+E-SEN-03,SEN,error,Attempted to wake up uninitialized SEN66,Internal error - send the log to the firmware team
+E-SEN-04,SEN,error,Failed to take sensor mutex,Internal error - send the log to the firmware team
+E-SEN-05,SEN,error,Failed to send start measurement command: %d,"Check the SEN66 sensor, its power supply and the sensor cable"
+E-SEN-06,SEN,error,Attempted to sleep uninitialized SEN66,Internal error - send the log to the firmware team
+E-SEN-07,SEN,error,Failed to take sensor mutex,Internal error - send the log to the firmware team
+E-SEN-08,SEN,error,Failed to send stop measurement command: %d,"Check the SEN66 sensor, its power supply and the sensor cable"
+E-SEN-09,SEN,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-SEN-10,SEN,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-SEN-11,SEN,error,Failed to read ready status: %d,"Check the SEN66 sensor, its power supply and the sensor cable"
+E-SEN-12,SEN,error,"Sensor not ready after %d attempts, trying to wake it up","Check the SEN66 sensor, its power supply and the sensor cable"
+E-SEN-13,SEN,error,Failed to read measurement: %d,"Check the SEN66 sensor, its power supply and the sensor cable"
+E-SEN-14,SEN,error,Failed while awaiting sensor ready: %d,"Check the SEN66 sensor, its power supply and the sensor cable"
+E-SEN-15,SEN,error,Failed to read measurement for line protocol: %d,"Check the SEN66 sensor, its power supply and the sensor cable"
+E-SEN-16,SEN,error,Self-check failed: Sensor not ready: %d,"Check the SEN66 sensor, its power supply and the sensor cable"
+E-SEN-17,SEN,error,Self-check failed: Failed to read measurement: %d,"Check the SEN66 sensor, its power supply and the sensor cable"
+E-AS-01,AS,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-AS-02,AS,error,Failed to initialize AS7341: %s,Check the AS7341 light sensor and the sensor cable
+E-AS-03,AS,error,Attempted to wake up uninitialized AS7341,Internal error - send the log to the firmware team
+E-AS-04,AS,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-AS-05,AS,error,Failed to wake up AS7341: %s,Check the AS7341 light sensor and the sensor cable
+E-AS-06,AS,error,Attempted to put uninitialized AS7341 to sleep,Internal error - send the log to the firmware team
+E-AS-07,AS,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-AS-08,AS,error,Failed to put AS7341 to sleep: %s,Check the AS7341 light sensor and the sensor cable
+E-AS-09,AS,error,Attempted to get line protocol on uninitialized AS7341,Internal error - send the log to the firmware team
+E-AS-10,AS,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-AS-11,AS,error,Failed to read spectral data: %s,Check the AS7341 light sensor and the sensor cable
+E-AS-12,AS,error,Failed to read basic counts data: %s,Check the AS7341 light sensor and the sensor cable
+E-AS-13,AS,error,Failed to read flicker detection state: %s,Check the AS7341 light sensor and the sensor cable
+E-AS-14,AS,error,Self-check failed: Failed to read spectral data: %s,Check the AS7341 light sensor and the sensor cable
+E-MIC-01,MIC,error,Failed to create I2S channel: %s,Check the microphone board and its cable
+E-MIC-02,MIC,error,Failed to initialize I2S channel in standard mode: %s,Check the microphone board and its cable
+E-MIC-03,MIC,error,Failed to configure shutdown pin: %s,Check the microphone board and its cable
+E-MIC-04,MIC,error,Failed to read samples from I2S channel: %s,Check the microphone board and its cable
+E-MIC-05,MIC,error,Failed to read samples for line protocol: %s,Check the microphone board and its cable
+E-FLK-01,FLK,error,Error %s at %s:%d,Internal error - send the log to the firmware team
+E-FLK-02,FLK,error,Attempting to initialize sensor that is already initialized,Check the flicker sensor and its cable
+E-FLK-03,FLK,error,Failed to allocate memory for FFT buffers,Internal error - send the log to the firmware team
+E-FLK-04,FLK,error,Failed to initialize FFT: %s,Check the flicker sensor and its cable
+E-FLK-05,FLK,error,Attempting to read from uninitialized sensor,Internal error - send the log to the firmware team
+E-FLK-06,FLK,error,Failed to take I2C mutex,Internal error - send the log to the firmware team
+E-FLK-07,FLK,error,Failed to get dominant frequency: %s,Check the flicker sensor and its cable
+E-FLK-08,FLK,error,Attempting to read from uninitialized sensor,Internal error - send the log to the firmware team
+E-FLK-09,FLK,error,Failed to read ADC value: %s,Check the flicker sensor and its cable
+E-FLK-10,FLK,error,Failed to create gather task: %s,Internal error - send the log to the firmware team
+E-FLK-11,FLK,error,Attempting to self check uninitialized sensor,Internal error - send the log to the firmware team
+E-FLK-12,FLK,error,Self check failed to get dominant frequency: %s,Check the flicker sensor and its cable
+E-DEV-01,DEV,error,Failed to initialize ADC unit: %s,Internal error - send the log to the firmware team
+E-DEV-02,DEV,error,Failed to configure ADC channel: %s,Internal error - send the log to the firmware team
+E-DEV-03,DEV,error,Failed to install temperature sensor: %s,Internal error - send the log to the firmware team
+E-DEV-04,DEV,error,Failed to read ADC value: %s,Internal error - send the log to the firmware team
+E-DEV-05,DEV,error,Failed to allocate memory for task list buffer,Internal error - send the log to the firmware team
+E-GATH-01,GATH,error,Failed to take line protocol mutex,Internal error - send the log to the firmware team
+E-GATH-02,GATH,error,Failed to get line protocol from sensor,Device ran out of memory; restart it and send the log to the firmware team
+E-GATH-03,GATH,error,Failed to create task for sensor,Internal error - send the log to the firmware team
+E-GATH-04,GATH,error,Failed to create main gather task,Internal error - send the log to the firmware team

kota_tech/diag/firmware.py

@@ -1,97 +1,147 @@
-"""Firmware identification from the boot log.
-
-The app version string is "1.0" in every build seen so far, so builds are
-told apart by the ELF SHA256 prefix printed by app_init. Boxes receive new
-firmware over OTA; an unknown SHA usually means a box has already updated.
-"""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass, field
-
-
-@dataclass(frozen=True)
-class KnownFirmware:
-    name: str
-    source: str
-    sd_wifi: bool        # reads SSID/PASSWORD from ENV.TXT
-    setup_portal: bool   # short press -> Wi-Fi setup portal
-
-
-KNOWN: dict[str, KnownFirmware] = {
-    "45fa9d5b9": KnownFirmware(
-        name="v1.0 (built Jun 29 2026)",
-        source="factory image new_system.bin",
-        sd_wifi=False,
-        setup_portal=False,
-    ),
-    "c94ba0e9b": KnownFirmware(
-        name="v1.0 source build (Sep 26 2026)",
-        source="developer build, built by Krzysztof Kallas",
-        sd_wifi=True,
-        setup_portal=True,
-    ),
-}
-
-_ELF = re.compile(r"app_init: ELF file SHA256:\s+(?P<sha>[0-9a-f]{6,})")
-_VER = re.compile(r"app_init: App version:\s+(?P<v>\S+)")
-_BUILT = re.compile(r"app_init: Compile time:\s+(?P<t>.+)$")
-_IDF = re.compile(r"app_init: ESP-IDF:\s+(?P<v>\S+)")
-# Evidence of features, for builds not in KNOWN.
-_FEATURE_SD_WIFI = re.compile(r"WIFI_CREDENTIALS: ")
-_FEATURE_PORTAL = re.compile(r"WIFI_PROVISIONING: |Short press: ")
-# Deployed v1.0 logs the SD mount under the INFLUX_BUFFER tag.
-_LEGACY_SD_TAG = re.compile(r"INFLUX_BUFFER: SD card mounted")
-
-
-@dataclass
-class FirmwareInfo:
-    elf_sha: str | None = None
-    version: str | None = None
-    built: str | None = None
-    idf: str | None = None
-    evidence: set[str] = field(default_factory=set)
-
-    def observe(self, text: str) -> None:
-        if m := _ELF.search(text):
-            self.elf_sha = m.group("sha")
-        elif m := _VER.search(text):
-            self.version = m.group("v")
-        elif m := _BUILT.search(text):
-            self.built = m.group("t").strip()
-        elif m := _IDF.search(text):
-            self.idf = m.group("v")
-        if _FEATURE_SD_WIFI.search(text):
-            self.evidence.add("sd_wifi")
-        if _FEATURE_PORTAL.search(text):
-            self.evidence.add("setup_portal")
-        if _LEGACY_SD_TAG.search(text):
-            self.evidence.add("legacy_v1")
-
-    @property
-    def known(self) -> KnownFirmware | None:
-        if not self.elf_sha:
-            return None
-        return next((k for sha, k in KNOWN.items() if self.elf_sha.startswith(sha)), None)
-
-    @property
-    def supports_sd_wifi(self) -> bool | None:
-        """True/False when determinable, None when unknown (no boot seen)."""
-        if k := self.known:
-            return k.sd_wifi
-        if "sd_wifi" in self.evidence:
-            return True
-        if "legacy_v1" in self.evidence:
-            return False
-        return None
-
-    def describe(self) -> str:
-        if k := self.known:
-            return f"{k.name} - {k.source}"
-        if self.elf_sha:
-            built = f", built {self.built}" if self.built else ""
-            return f"Unknown build {self.elf_sha[:9]}{built} (probably updated over OTA)"
-        if "legacy_v1" in self.evidence:
-            return "Probably v1.0 factory image (press Reset & capture to confirm)"
-        return "Not identified yet - press Reset & capture"
+"""Firmware identification from the boot log.
+
+Up to firmware 1.0 the app version string was "1.0" in every build, so
+builds are told apart by the ELF SHA256 prefix printed by app_init. Boxes
+receive new firmware over OTA; an unknown SHA usually means a box has already
+updated.
+
+Firmware 1.0.16+ prints "KOTA: boot fw=1.0.16 build=4f10989e ..." (version
+unique per build, first 8 hex digits of the ELF SHA256). Builds found in the
+tool's firmware/ folder are registered with `register_local_build` so the
+box's build can be shown with its compile date.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class KnownFirmware:
+    name: str
+    source: str
+    sd_wifi: bool        # reads SSID/PASSWORD from ENV.TXT
+    setup_portal: bool   # short press -> Wi-Fi setup portal
+
+
+KNOWN: dict[str, KnownFirmware] = {
+    "45fa9d5b9": KnownFirmware(
+        name="v1.0 (built Jun 29 2026)",
+        source="factory image new_system.bin",
+        sd_wifi=False,
+        setup_portal=False,
+    ),
+    "c94ba0e9b": KnownFirmware(
+        name="v1.0 source build (Sep 26 2026)",
+        source="developer build, built by Krzysztof Kallas",
+        sd_wifi=True,
+        setup_portal=True,
+    ),
+}
+
+# elf sha (full or prefix) -> (version, compile time, file name) of builds in firmware/
+LOCAL_BUILDS: dict[str, tuple[str, str, str]] = {}
+
+
+def register_local_build(elf_sha: str, version: str, built: str, file_name: str) -> None:
+    LOCAL_BUILDS[elf_sha.lower()] = (version, built, file_name)
+
+
+def same_build(a: str | None, b: str | None) -> bool:
+    """ELF SHA prefixes of different lengths (8 from KOTA: boot, 9+ from
+    app_init, 64 from an image) name the same build if they agree."""
+    if not a or not b:
+        return False
+    n = min(len(a), len(b))
+    return n >= 6 and a[:n].lower() == b[:n].lower()
+
+
+def local_build(elf_sha: str | None) -> tuple[str, str, str] | None:
+    return next((v for sha, v in LOCAL_BUILDS.items() if same_build(sha, elf_sha)), None)
+
+
+_ELF = re.compile(r"app_init: ELF file SHA256:\s+(?P<sha>[0-9a-f]{6,})")
+_VER = re.compile(r"app_init: App version:\s+(?P<v>\S+)")
+_BUILT = re.compile(r"app_init: Compile time:\s+(?P<t>.+)$")
+_IDF = re.compile(r"app_init: ESP-IDF:\s+(?P<v>\S+)")
+# Evidence of features, for builds not in KNOWN.
+_FEATURE_SD_WIFI = re.compile(r"WIFI_CREDENTIALS: ")
+_FEATURE_PORTAL = re.compile(r"WIFI_PROVISIONING: |Short press: ")
+# Deployed v1.0 logs the SD mount under the INFLUX_BUFFER tag.
+_LEGACY_SD_TAG = re.compile(r"INFLUX_BUFFER: SD card mounted")
+
+
+@dataclass
+class FirmwareInfo:
+    elf_sha: str | None = None
+    version: str | None = None
+    built: str | None = None
+    idf: str | None = None
+    hw: str | None = None
+    evidence: set[str] = field(default_factory=set)
+
+    def observe_kota(self, fields: dict[str, str]) -> None:
+        """'KOTA: boot fw=1.0.16 build=4f10989e hw=2 ...'"""
+        if fields.get("fw"):
+            self.version = fields["fw"]
+        build = fields.get("build", "")
+        # app_init's longer prefix is kept if it agrees.
+        if build and not same_build(self.elf_sha, build):
+            self.elf_sha = build.lower()
+        if fields.get("hw"):
+            self.hw = fields["hw"]
+        self.evidence.add("kota")      # 1.0.16+: SD Wi-Fi and setup portal exist
+
+    def observe(self, text: str) -> None:
+        if m := _ELF.search(text):
+            self.elf_sha = m.group("sha")
+        elif m := _VER.search(text):
+            self.version = m.group("v")
+        elif m := _BUILT.search(text):
+            self.built = m.group("t").strip()
+        elif m := _IDF.search(text):
+            self.idf = m.group("v")
+        if _FEATURE_SD_WIFI.search(text):
+            self.evidence.add("sd_wifi")
+        if _FEATURE_PORTAL.search(text):
+            self.evidence.add("setup_portal")
+        if _LEGACY_SD_TAG.search(text):
+            self.evidence.add("legacy_v1")
+
+    @property
+    def known(self) -> KnownFirmware | None:
+        if not self.elf_sha:
+            return None
+        return next((k for sha, k in KNOWN.items() if same_build(self.elf_sha, sha)), None)
+
+    @property
+    def supports_sd_wifi(self) -> bool | None:
+        """True/False when determinable, None when unknown (no boot seen)."""
+        if k := self.known:
+            return k.sd_wifi
+        if "sd_wifi" in self.evidence or "kota" in self.evidence:
+            return True
+        if "legacy_v1" in self.evidence:
+            return False
+        return None
+
+    def describe(self) -> str:
+        if k := self.known:
+            return f"{k.name} - {k.source}"
+        if self.elf_sha and (self.version not in (None, "1.0") or local_build(self.elf_sha)):
+            local = local_build(self.elf_sha)
+            built = self.built or (local[1] if local else None)
+            text = f"v{self.version or (local[0] if local else '?')} (build {self.elf_sha[:8]}"
+            text += f", compiled {built})" if built else ")"
+            if self.hw:
+                text += f", hardware {self.hw}"
+            if local:
+                text += f" - same as firmware/{local[2]}"
+            return text
+        if self.elf_sha:
+            built = f", built {self.built}" if self.built else ""
+            return f"Unknown build {self.elf_sha[:9]}{built} (probably updated over OTA)"
+        if "legacy_v1" in self.evidence:
+            return "Probably v1.0 factory image (press Reset & capture to confirm)"
+        return "Not identified yet - press Reset & capture"

kota_tech/diag/guides.py

@@ -21,7 +21,7 @@ from .engine import LED, DiagnosticsEngine, Severity
 
 GUIDES_PATH = Path(__file__).with_name("guides.toml")
 # LED answers a technician can give (engine colours + a reboot-loop pattern).
-LED_ANSWERS = ["GREEN", "PURPLE", "RED", "BLUE", "WHITE", "YELLOW", "ORANGE", "OFF", "CYCLING"]
+LED_ANSWERS = ["GREEN", "PURPLE", "RED", "BLUE", "WHITE", "YELLOW", "ORANGE", "CYAN", "OFF", "CYCLING"]
 LED_ANSWER_LABELS = {**{k: v[0] for k, v in LED.items()},
                      "CYCLING": "Keeps changing / goes dark every few seconds"}
 STEP_TYPES = {"led", "question", "info", "wait", "route"}

kota_tech/diag/kota.py

@@ -0,0 +1,263 @@
+"""Knowledge about the structured "KOTA:" lines of firmware 1.0.16+.
+
+Firmware source of truth (kota-sensorboard/main):
+  boot_info.cpp  "boot fw=.. build=.. hw=.. mac=.. reset=.. mode=.. commissioned=.. last_restart=.."
+                 "restart reason=.." (W, printed just before a self-restart)
+  status.cpp     "status A -> B [code=N] reason=x", "led color=.. pattern=.. [n=..|period=..ms]",
+                 "led previous_boot status=.. code=..", "led restart_flash color=.."
+  i2c.cpp        "i2c SDA=1 SCL=1 0x39=AS7341 0x68=DS1307(missing) .. [bus=stuck]"
+  ds1307.cpp     "rtc running=1 time=..", "rtc read_failed err=..", "rtc verify running=1 delta=2s ok=1"
+  sd_card.cpp    "sd type=.. size=.. fs=.. free=.. env_keys=A,B buffer_lines=N", "sd mounted=0 [err=..]"
+  main.cpp       "matter fabrics=N window=open|closed qr=MT:.. manual=.."
+  microphone.cpp "mic enabled=0 (GPIO3=1, expected 0)"
+  health.cpp     "health up=60s status=OK wifi=connected rssi=-61 time_valid=1 sd=ok buffer=0
+                  heap=123456 psram=7.8M last_upload=12s|never ota=registered|unregistered|selfcheck"
+
+Error IDs ("[E-SD-03] ...") come from error_ids.csv, a copy of the
+firmware's docs/error_ids.csv (the firmware build generates its IDs from it).
+"""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from pathlib import Path
+
+ERROR_IDS_PATH = Path(__file__).with_name("error_ids.csv")
+
+# Firmware colour names (status.cpp colors[]) -> engine LED keys.
+LED_COLOURS = {
+    "green": "GREEN", "cyan": "CYAN", "white": "WHITE", "red": "RED",
+    "blue": "BLUE", "purple": "PURPLE", "yellow": "YELLOW", "orange": "ORANGE",
+}
+
+RED_CODES = {1: "BME688", 2: "SEN66", 3: "AS7341", 4: "Microphone", 5: "Flicker sensor", 6: "Self-check"}
+I2C_DEVICES = {"0x39": "AS7341", "0x68": "DS1307", "0x6B": "SEN66", "0x76": "BME688"}
+
+# last_restart values written by kota_restart() that are part of normal
+# operation (button presses, a finished setup, an installed update).
+INTENTIONAL_RESTARTS = {
+    "ota_update", "button_provisioning_abort", "button_wifi_cleared",
+    "button_provisioning_toggle", "provisioning_saved",
+}
+
+MODULES = {
+    "SD": "SD card", "ENV": "ENV.TXT", "INF": "InfluxDB upload", "OTA": "Firmware update",
+    "WIFI": "Wi-Fi", "PROV": "Wi-Fi setup", "MAIN": "Start-up", "STAT": "Status LED", "SPI": "SPI bus",
+    "RTC": "Clock (RTC)", "BME": "BME688", "SEN": "SEN66", "AS": "AS7341", "MIC": "Microphone",
+    "FLK": "Flicker sensor", "DEV": "Device", "GATH": "Sensor readings",
+}
+
+
+@dataclass(frozen=True)
+class ErrorId:
+    id: str
+    module: str
+    severity: str        # error | warning | retired
+    message: str
+    action: str
+
+    @property
+    def module_name(self) -> str:
+        return MODULES.get(self.module, self.module)
+
+
+def load_error_ids(path: Path = ERROR_IDS_PATH) -> dict[str, ErrorId]:
+    if not path.exists():
+        return {}
+    with path.open(encoding="utf-8", newline="") as fh:
+        return {r["id"]: ErrorId(r["id"], r["module"], r["severity"], r["message"], r["action"])
+                for r in csv.DictReader(fh)}
+
+
+def led_for_status(status: str, code: int) -> tuple[str, str]:
+    """(LED key, pattern text) for a status - mirrors Status::pattern_for().
+    Used when the box's own "led" line was not captured (connected mid-run)."""
+    if status == "OK":
+        return "GREEN", "solid"
+    if status == "ERROR":
+        return ("RED", f"{code} pulses") if 1 <= code <= 6 else ("RED", "solid")
+    if status == "OUT_OF_RESOURCES":
+        return "RED", "solid"
+    if status == "UPDATING":
+        return "YELLOW", "blinking"
+    if status == "SELF_CHECK":
+        return "ORANGE", "solid"
+    if status == "CONNECTION_ERROR":
+        return ("PURPLE", "blinking") if code == 1 else ("PURPLE", "solid")
+    if status == "RTC_ERROR":
+        return "BLUE", "2 pulses" if code == 2 else "1 pulse"
+    if status == "SD_ERROR":
+        return "WHITE", "fast blinking"
+    if status == "RESETING":
+        return "WHITE", "solid"
+    if status == "HTTP_SERVER":
+        return "WHITE", "breathing"
+    return "UNKNOWN", ""
+
+
+def pattern_text(fields: dict[str, str]) -> str:
+    """'led color=red pattern=pulses n=2' -> '2 pulses'."""
+    p = fields.get("pattern", "")
+    if p == "pulses":
+        n = fields.get("n", "?")
+        return f"{n} pulse" if n == "1" else f"{n} pulses"
+    if p == "blink":
+        period = fields.get("period", "").removesuffix("ms")
+        fast = period.isdigit() and int(period) <= 500
+        return ("fast blinking" if fast else "blinking") + (f" ({period} ms)" if period else "")
+    if p == "breathe":
+        return "breathing"
+    return p   # solid / off
+
+
+def led_meaning(colour: str, pattern: str) -> str:
+    """Technician meaning of a colour + pattern (firmware diagnostics doc)."""
+    if colour == "GREEN":
+        return "OK"
+    if colour == "CYAN":
+        return "phone connected for pairing" if "fast" in pattern else "waiting to be paired in Matter"
+    if colour == "WHITE":
+        if "fast" in pattern:
+            return "SD card or ENV.TXT error"
+        if "breath" in pattern:
+            return "Wi-Fi setup portal"
+        return "factory reset"
+    if colour == "RED":
+        if "pulse" in pattern:
+            n = int(pattern.split()[0]) if pattern.split()[0].isdigit() else 0
+            return f"{RED_CODES.get(n, 'sensor')} failed"
+        return "internal error / out of memory"
+    if colour == "BLUE":
+        return "I2C bus stuck (sensor cable)" if pattern.startswith("2") else "clock (RTC) not responding"
+    if colour == "PURPLE":
+        return "server rejected the box (check ENV.TXT credentials)" if "blink" in pattern else "no network"
+    if colour == "YELLOW":
+        return "downloading a firmware update"
+    if colour == "ORANGE":
+        return "self-check after an update"
+    return ""
+
+
+# Finding for the current firmware status (Status::set_status). key suffix ->
+# (severity, title, meaning, actions, explained_by). The status finding is
+# grouped under a more specific finding when one explains it.
+_SENSOR_ROOTS = ("sensor.init_failed", "sensor.selfcheck_failed", "kota.i2c_stuck", "kota.sensor_missing",
+                 "sen66.not_ready", "bme688.read_fail", "as7341.read_fail", "mic.read_fail",
+                 "ota.selfcheck_failed")
+_NET_ROOTS = ("matter.not_commissioned", "wifi.disconnected", "wifi.setup_portal", "kota.wifi_down",
+              "net.dns_fail", "net.tls_fail")
+
+
+def status_finding(status: str, code: int) -> tuple[str, str, str, str, tuple[str, ...], tuple[str, ...]] | None:
+    """(key, severity, title, meaning, actions, explained_by) or None for healthy states."""
+    if status == "ERROR":
+        if 1 <= code <= 5:
+            s = RED_CODES[code]
+            return (f"status.error.{code}", "critical", f"{s} fault (LED red, {code} pulses)",
+                    f"The firmware reports the {s} as failed.",
+                    (f"Open the case and check the {s} connector/cable.",
+                     "If several sensors fail: check the shared I2C cable.",
+                     "The box restarts itself after 150 s in this state."), _SENSOR_ROOTS)
+        if code == 6:
+            return ("status.error.6", "error", "Post-update self-check failed (LED red, 6 pulses)",
+                    "The new firmware failed its self-check and rolls back.",
+                    ("Check the sensor named in the log (inside the case), then power-cycle.",), _SENSOR_ROOTS)
+        return ("status.error", "error", "Internal error (LED red)",
+                "The firmware is in its general error state.",
+                ("Save the session log and send it to the firmware team.",
+                 "The box restarts itself after 150 s in this state."), _SENSOR_ROOTS)
+    if status == "OUT_OF_RESOURCES":
+        return ("status.oom", "error", "Firmware ran out of memory (LED red)",
+                "The firmware could not allocate memory; it restarts itself after 30 s.",
+                ("Power-cycle. If it repeats, save the session log for the firmware team.",),
+                ("sys.out_of_resources",))
+    if status == "CONNECTION_ERROR":
+        if code == 1:
+            return ("status.conn.1", "critical", "Server rejected the box (LED purple, blinking)",
+                    "The network works but the server refused the box (HTTP 401/403/404): "
+                    "INFLUX_URL / INFLUX_TOKEN in ENV.TXT are wrong or revoked.",
+                    ("Re-provision the SD card with the current ENV.TXT (SD card is inside the case).",),
+                    ("influx.auth", "influx.not_found"))
+        return ("status.conn", "error", "No connection to the servers (LED purple)",
+                "Uploads or the update check fail: no Wi-Fi, no Internet or the server is unreachable.",
+                ("Check the box is paired/connected to Wi-Fi and the network has Internet.",),
+                _NET_ROOTS + ("influx.buffer_fail", "ota.check_failed", "influx.server_error"))
+    if status == "RTC_ERROR":
+        if code == 2:
+            return ("status.rtc.2", "critical", "I2C bus stuck (LED blue, 2 pulses)",
+                    "SDA or SCL is held low: a shorted or broken sensor cable, or a faulty sensor.",
+                    ("Open the case and check the I2C cable between the boards.",
+                     "Unplug sensors one by one to find the one holding the bus."), ("kota.i2c_stuck",))
+        return ("status.rtc.1", "critical", "Clock chip (RTC) not responding (LED blue, 1 pulse)",
+                "The DS1307 clock does not answer on the I2C bus.",
+                ("Open the case and check the I2C cable/connector between the boards.",
+                 "If the cable is fine: the RTC module is faulty."),
+                ("rtc.init_failed", "kota.rtc_read_failed", "kota.sensor_missing"))
+    if status == "SD_ERROR":
+        return ("status.sd", "critical", "SD card or ENV.TXT error (LED white, fast blinking)",
+                "The SD card cannot be read or ENV.TXT is missing settings.",
+                ("Open the case, re-seat the SD card or re-provision it with the tool.",),
+                ("kota.sd_unmounted", "influx.env_missing", "sd.card_fail", "sd.mount_fail",
+                 "sd.env_open_fail", "influx.init_fail"))
+    if status == "RESETING":
+        return ("status.reset", "warning", "Factory reset in progress (LED white, solid)",
+                "The Matter button was held: the box forgets its Matter network.",
+                ("Pair the box again in the Matter app afterwards.",), ("sys.factory_reset",))
+    if status == "HTTP_SERVER":
+        return ("status.portal", "warning", "Box is in Wi-Fi setup mode (LED white, breathing)",
+                "The box hosts its own Wi-Fi network for configuration.",
+                ("Connect a phone to the box's network and open http://sensorbox.local/,",
+                 "or short-press the Matter button to leave setup mode."), ("wifi.setup_portal",))
+    return None   # OK, UPDATING, SELF_CHECK: covered by milestones / OTA rules
+
+
+# last_restart -> (severity, title, meaning, actions); None = not a fault.
+def restart_finding(reason: str) -> tuple[str, str, str, tuple[str, ...]] | None:
+    if reason in INTENTIONAL_RESTARTS or reason in ("none", "", "-"):
+        return None
+    if reason == "status_watchdog":
+        return ("warning", "Box restarted itself after 150 s in the red error state",
+                "By design the firmware restarts when it stays in the error state (red) for 150 s.",
+                ("Fix the grouped cause; the restarts stop by themselves.",))
+    if reason == "status_oom_watchdog":
+        return ("error", "Box restarted itself because it ran out of memory",
+                "The firmware was out of memory for 30 s and restarted.",
+                ("Save the session log for the firmware team.",))
+    if reason == "provisioning_failed":
+        return ("warning", "Wi-Fi setup portal failed to start",
+                "The setup portal could not start; the box cleared setup mode and restarted.",
+                ("Retry Wi-Fi setup (short button press); restart the device if it persists.",))
+    if reason == "panic":
+        return ("critical", "Firmware crashed (panic) and restarted",
+                "The firmware hit a fatal error.",
+                ("Press Reset & capture to record the crash; save the session log for the firmware team.",))
+    if reason in ("task_wdt", "int_wdt", "wdt"):
+        return ("error", "Firmware froze and was restarted by the watchdog",
+                f"The firmware stopped responding ({reason}); the watchdog restarted it.",
+                ("Save the session log for the firmware team.",))
+    if reason == "brownout":
+        return ("error", "Power supply voltage dropped (brown-out)",
+                "The supply voltage fell too low and the chip reset itself.",
+                ("Check the power supply, cable and connectors.",))
+    if reason == "unknown_sw":
+        return ("warning", "Unexpected software restart",
+                "The firmware restarted without recording a reason.",
+                ("Watch whether it repeats; save the session log for the firmware team.",))
+    return ("warning", f"Box restarted itself ({reason})",
+            f"The firmware recorded the restart reason '{reason}'.",
+            ("Save the session log for the firmware team if it repeats.",))
+
+
+def parse_size_gb(value: str) -> float | None:
+    """'7.3GB' -> 7.3 (sd_card.cpp format_gb)."""
+    v = value.upper().removesuffix("GB")
+    try:
+        return float(v)
+    except ValueError:
+        return None
+
+
+def parse_seconds(value: str) -> int | None:
+    v = value.removesuffix("s")
+    return int(v) if v.lstrip("-").isdigit() else None

kota_tech/flash/image.py

@@ -1,303 +1,260 @@
-"""Firmware images: validation, integrity and layout.
-
-Two origins:
-  * factory   - bundled with the tool (firmware/firmware.toml), SHA-256 locked;
-  * developer - a newer build the firmware team sends to technicians,
-                imported into a per-user library (~/KotaTechnicianTool/firmware).
-Two kinds:
-  * merged - bootloader at 0x0 + partition table + app (like new_system.bin);
-             App-only or Full flashing;
-  * app    - the application binary only (build/kota-sensorboard.bin);
-             App-only flashing, laid out like the factory image.
-
-Every image is checked structurally (ESP32-S3, kota-sensorboard app
-descriptor, segment checksum and the appended SHA-256) so a truncated or
-corrupted file is refused before anything is written.
-"""
-
-from __future__ import annotations
-
-import datetime as dt
-import hashlib
-import json
-import shutil
-import struct
-import tomllib
-from dataclasses import dataclass
-from pathlib import Path
-
-FIRMWARE_DIR = Path(__file__).resolve().parents[2] / "firmware"
-MANIFEST = FIRMWARE_DIR / "firmware.toml"
-LIBRARY_DIR = Path.home() / "KotaTechnicianTool" / "firmware"
-LIBRARY_INDEX = "library.json"
-
-PT_OFFSET = 0x8000
-PT_SIZE = 0xC00
-ESP32S3_CHIP_ID = 9
-IMAGE_MAGIC = 0xE9
-APP_DESC_MAGIC = 0xABCD5432
-FLASH_SIZES = {0: "1MB", 1: "2MB", 2: "4MB", 3: "8MB", 4: "16MB", 5: "32MB"}
-_MONTHS = {m: i for i, m in enumerate(
-    ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"], 1)}
-
-
-class ImageError(ValueError):
-    pass
-
-
-@dataclass(frozen=True)
-class Partition:
-    label: str
-    type: int
-    subtype: int
-    offset: int
-    size: int
-
-
-@dataclass(frozen=True)
-class AppInfo:
-    project: str
-    version: str
-    built: str          # "Jun 29 2026 11:03:32" as in the app descriptor
-    idf: str
-    elf_sha: str        # hex
-
-    @property
-    def built_at(self) -> dt.datetime | None:
-        try:
-            mon, day, year, hms = self.built.split()
-            h, m, s = (int(x) for x in hms.split(":"))
-            return dt.datetime(int(year), _MONTHS[mon], int(day), h, m, s)
-        except (ValueError, KeyError):
-            return None
-
-
-@dataclass(frozen=True)
-class FirmwareImage:
-    path: Path
-    name: str
-    notes: str
-    origin: str                      # "factory" | "developer"
-    kind: str                        # "merged" | "app"
-    sha256: str
-    flash_size: str
-    partitions: tuple[Partition, ...]
-    partition_table: bytes           # expected table on the box
-    app_offset: int                  # where the app starts inside the file
-    app_length: int                  # exact app image length (from its structure)
-    app: AppInfo
-    built_by: str = ""               # who compiled a developer build (shown in the UI)
-
-    @property
-    def data(self) -> bytes:
-        return self.path.read_bytes()
-
-    @property
-    def is_developer(self) -> bool:
-        return self.origin == "developer"
-
-    def partition(self, label: str) -> Partition:
-        for p in self.partitions:
-            if p.label == label:
-                return p
-        raise ImageError(f"partition {label!r} not in image")
-
-    def app_bytes(self) -> bytes:
-        return self.data[self.app_offset:self.app_offset + self.app_length]
-
-    def blank_otadata(self) -> bytes:
-        """Erased otadata: the bootloader then boots ota_0."""
-        return b"\xff" * self.partition("otadata").size
-
-    def label(self) -> str:
-        if self.origin == "factory":
-            tag = "factory"
-        else:
-            tag = "developer build" + (f" - built by {self.built_by}" if self.built_by else "")
-        return f"{self.app.version} built {self.app.built} [{self.app.elf_sha[:9]}] - {tag}"
-
-
-# ---------------------------------------------------------------- parsing
-
-def parse_partition_table(raw: bytes) -> tuple[Partition, ...]:
-    parts = []
-    for i in range(0, len(raw) - 31, 32):
-        entry = raw[i:i + 32]
-        magic = entry[:2]
-        if magic == b"\xaa\x50":
-            _, ptype, sub, off, size = struct.unpack_from("<HBBII", entry)
-            label = entry[12:28].split(b"\0")[0].decode("ascii", "replace")
-            parts.append(Partition(label, ptype, sub, off, size))
-        elif magic in (b"\xeb\xeb", b"\xff\xff"):   # MD5 entry / end
-            break
-        else:
-            raise ImageError(f"corrupt partition table entry at 0x{PT_OFFSET + i:x}")
-    return tuple(parts)
-
-
-def app_image_length(data: bytes, offset: int = 0) -> int:
-    """Validate an ESP app image at `offset`; return its exact length.
-
-    Checks the segment checksum and, when the header says so, the appended
-    SHA-256 - the same checks the bootloader performs before booting it.
-    """
-    if len(data) < offset + 24 or data[offset] != IMAGE_MAGIC:
-        raise ImageError(f"no firmware image at 0x{offset:x}")
-    segments = data[offset + 1]
-    chip_id = struct.unpack_from("<H", data, offset + 12)[0]
-    if chip_id != ESP32S3_CHIP_ID:
-        raise ImageError(f"image is for chip id {chip_id}, not ESP32-S3")
-    hash_appended = data[offset + 23] == 1
-    pos, checksum = offset + 24, 0xEF
-    for _ in range(segments):
-        if pos + 8 > len(data):
-            raise ImageError("image is truncated (segment header missing)")
-        _, seg_len = struct.unpack_from("<II", data, pos)
-        pos += 8
-        if pos + seg_len > len(data):
-            raise ImageError("image is truncated (segment data missing)")
-        for b in data[pos:pos + seg_len]:
-            checksum ^= b
-        pos += seg_len
-    pos += 15 - ((pos - offset) % 16)          # pad so the checksum ends a 16-byte block
-    if pos >= len(data) or data[pos] != checksum:
-        raise ImageError("image checksum is wrong - the file is corrupted")
-    pos += 1
-    if hash_appended:
-        if pos + 32 > len(data):
-            raise ImageError("image is truncated (SHA-256 missing)")
-        if hashlib.sha256(data[offset:pos]).digest() != data[pos:pos + 32]:
-            raise ImageError("image SHA-256 does not match its content - the file is corrupted")
-        pos += 32
-    return pos - offset
-
-
-def _app_info(data: bytes, offset: int) -> AppInfo:
-    d = data[offset + 0x20:offset + 0x20 + 256]
-    if len(d) < 256 or struct.unpack_from("<I", d)[0] != APP_DESC_MAGIC:
-        raise ImageError("firmware has no ESP-IDF app descriptor")
-    s = lambda o, n: d[o:o + n].split(b"\0")[0].decode("ascii", "replace")
-    info = AppInfo(project=s(48, 32), version=s(16, 32), built=f"{s(96, 16)} {s(80, 16)}",
-                   idf=s(112, 32), elf_sha=d[144:176].hex())
-    if info.project != "kota-sensorboard":
-        raise ImageError(f"firmware is {info.project!r}, not kota-sensorboard")
-    return info
-
-
-def inspect_image(path: Path, name: str = "", notes: str = "", origin: str = "factory",
-                  reference: FirmwareImage | None = None, built_by: str = "") -> FirmwareImage:
-    """Validate a merged or app-only image. App-only images need a `reference`
-    (the factory image) that provides the flash layout."""
-    data = path.read_bytes()
-    if len(data) >= PT_OFFSET + PT_SIZE and data[0] == IMAGE_MAGIC and data[PT_OFFSET:PT_OFFSET + 2] == b"\xaa\x50":
-        app_image_length(data, 0)              # bootloader must be intact
-        table = data[PT_OFFSET:PT_OFFSET + PT_SIZE]
-        parts = parse_partition_table(table)
-        labels = {p.label for p in parts}
-        for need in ("nvs", "otadata", "ota_0"):
-            if need not in labels:
-                raise ImageError(f"partition table has no {need!r} partition")
-        ota0 = next(p for p in parts if p.label == "ota_0")
-        kind, app_off, flash_size = "merged", ota0.offset, FLASH_SIZES.get(data[3] >> 4, "?")
-    elif data[:1] == bytes([IMAGE_MAGIC]):
-        if reference is None:
-            raise ImageError("app-only image needs the factory image as layout reference")
-        kind, app_off = "app", 0
-        parts, table, flash_size = reference.partitions, reference.partition_table, reference.flash_size
-        ota0 = next(p for p in parts if p.label == "ota_0")
-    else:
-        raise ImageError("not an ESP32 firmware file")
-    length = app_image_length(data, app_off)
-    if length > ota0.size:
-        raise ImageError(f"firmware ({length} bytes) does not fit the ota_0 partition ({ota0.size} bytes)")
-    app = _app_info(data, app_off)
-    return FirmwareImage(path, name or path.name, notes, origin, kind, hashlib.sha256(data).hexdigest(),
-                         flash_size, parts, table, app_off, length, app, built_by)
-
-
-# ------------------------------------------------------------- catalogue
-
-def bundled_images(manifest: Path = MANIFEST) -> list[FirmwareImage]:
-    """Images shipped with the tool whose file exists and matches its SHA-256.
-    Factory images first; bundled developer builds keep their origin/built_by."""
-    if not manifest.exists():
-        return []
-    out = []
-    for e in tomllib.loads(manifest.read_text(encoding="utf-8")).get("image", []):
-        path = manifest.parent / e["file"]
-        if not path.exists():
-            continue
-        origin = e.get("origin", "factory")
-        if origin not in ("factory", "developer"):
-            raise ImageError(f"{path.name}: unknown origin {origin!r} in the manifest")
-        img = inspect_image(path, e.get("name", ""), e.get("notes", ""), origin, built_by=e.get("built_by", ""))
-        if img.sha256 != e["sha256"].lower():
-            raise ImageError(f"{path.name}: SHA-256 does not match the manifest - file changed or corrupt")
-        out.append(img)
-    return sorted(out, key=lambda i: i.origin != "factory")
-
-
-def factory_images(manifest: Path = MANIFEST) -> list[FirmwareImage]:
-    """Only the official factory image(s)."""
-    return [i for i in bundled_images(manifest) if i.origin == "factory"]
-
-
-class FirmwareLibrary:
-    """Developer builds imported by the technician (persist across tool versions)."""
-
-    def __init__(self, root: Path = LIBRARY_DIR):
-        self.root = root
-
-    def _index(self) -> list[dict]:
-        f = self.root / LIBRARY_INDEX
-        return json.loads(f.read_text(encoding="utf-8")) if f.exists() else []
-
-    def _save(self, entries: list[dict]) -> None:
-        self.root.mkdir(parents=True, exist_ok=True)
-        (self.root / LIBRARY_INDEX).write_text(json.dumps(entries, indent=2), encoding="utf-8")
-
-    def images(self, reference: FirmwareImage | None) -> tuple[list[FirmwareImage], list[str]]:
-        """(valid images, problems) - a changed or broken file is reported, not offered."""
-        imgs, problems = [], []
-        for e in self._index():
-            path = self.root / e["file"]
-            try:
-                img = inspect_image(path, e.get("name", ""), e.get("notes", ""), "developer", reference,
-                                    e.get("built_by", ""))
-                if img.sha256 != e["sha256"]:
-                    raise ImageError("file changed since it was imported")
-                imgs.append(img)
-            except (OSError, ImageError) as exc:
-                problems.append(f"{e.get('original', e['file'])}: {exc}")
-        return imgs, problems
-
-    def import_file(self, src: Path, reference: FirmwareImage | None, notes: str = "",
-                    built_by: str = "") -> FirmwareImage:
-        img = inspect_image(src, origin="developer", reference=reference)   # validate before copying
-        entries = self._index()
-        existing = next((e for e in entries if e["sha256"] == img.sha256), None)
-        if existing:
-            return inspect_image(self.root / existing["file"], existing["name"], existing["notes"],
-                                 "developer", reference, existing.get("built_by", ""))
-        self.root.mkdir(parents=True, exist_ok=True)
-        fname = f"{img.app.elf_sha[:9]}_{img.sha256[:8]}.bin"
-        shutil.copyfile(src, self.root / fname)
-        built_by = built_by.strip()
-        name = f"Developer build {img.app.version} ({img.app.built})" + (f", built by {built_by}" if built_by else "")
-        entries.append({"file": fname, "sha256": img.sha256, "name": name, "original": src.name,
-                        "imported": dt.datetime.now().isoformat(timespec="seconds"), "notes": notes,
-                        "built_by": built_by})
-        self._save(entries)
-        return inspect_image(self.root / fname, name, notes, "developer", reference, built_by)
-
-    def remove(self, sha256: str) -> None:
-        entries = self._index()
-        keep = [e for e in entries if e["sha256"] != sha256]
-        for e in entries:
-            if e["sha256"] == sha256:
-                (self.root / e["file"]).unlink(missing_ok=True)
-        self._save(keep)
-
-
-# Backwards-compatible name used by earlier callers/tests.
-official_images = factory_images
+"""Firmware images: validation, integrity, layout and the firmware folder.
+
+The tool flashes ONLY the .bin files in its own firmware/ folder (next to
+kota_tech/). There is no import and no per-user library: to offer a build,
+the firmware team puts the file into that folder. Images are listed by the
+compile date stored in the firmware itself (ESP-IDF app descriptor), newest
+first, so the file name does not matter.
+
+Two kinds:
+  * merged - bootloader at 0x0 + partition table + app (merged-binary.bin);
+             App-only or Full flashing;
+  * app    - the application binary only (build/kota-sensorboard.bin);
+             App-only flashing, laid out like a merged image in the folder.
+
+Every image is checked structurally (ESP32-S3, kota-sensorboard app
+descriptor, segment checksum and the appended SHA-256) so a truncated or
+corrupted file is refused before anything is written.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import struct
+from dataclasses import dataclass
+from pathlib import Path
+
+FIRMWARE_DIR = Path(__file__).resolve().parents[2] / "firmware"
+
+PT_OFFSET = 0x8000
+PT_SIZE = 0xC00
+ESP32S3_CHIP_ID = 9
+IMAGE_MAGIC = 0xE9
+APP_DESC_MAGIC = 0xABCD5432
+FLASH_SIZES = {0: "1MB", 1: "2MB", 2: "4MB", 3: "8MB", 4: "16MB", 5: "32MB"}
+_MONTHS = {m: i for i, m in enumerate(
+    ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"], 1)}
+
+
+class ImageError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Partition:
+    label: str
+    type: int
+    subtype: int
+    offset: int
+    size: int
+
+
+@dataclass(frozen=True)
+class AppInfo:
+    project: str
+    version: str
+    built: str          # "Sep 28 2026 15:07:57" as in the app descriptor
+    idf: str
+    elf_sha: str        # hex
+
+    @property
+    def built_at(self) -> dt.datetime | None:
+        try:
+            mon, day, year, hms = self.built.split()
+            h, m, s = (int(x) for x in hms.split(":"))
+            return dt.datetime(int(year), _MONTHS[mon], int(day), h, m, s)
+        except (ValueError, KeyError):
+            return None
+
+    @property
+    def compiled(self) -> str:
+        """'2026-09-28 15:07' (ISO-like, sortable) or the raw descriptor text."""
+        t = self.built_at
+        return t.strftime("%Y-%m-%d %H:%M") if t else self.built
+
+
+@dataclass(frozen=True)
+class FirmwareImage:
+    path: Path
+    kind: str                        # "merged" | "app"
+    sha256: str
+    flash_size: str
+    partitions: tuple[Partition, ...]
+    partition_table: bytes           # expected table on the box
+    app_offset: int                  # where the app starts inside the file
+    app_length: int                  # exact app image length (from its structure)
+    app: AppInfo
+
+    @property
+    def name(self) -> str:
+        return self.path.name
+
+    @property
+    def data(self) -> bytes:
+        return self.path.read_bytes()
+
+    def partition(self, label: str) -> Partition:
+        for p in self.partitions:
+            if p.label == label:
+                return p
+        raise ImageError(f"partition {label!r} not in image")
+
+    def app_bytes(self) -> bytes:
+        return self.data[self.app_offset:self.app_offset + self.app_length]
+
+    def blank_otadata(self) -> bytes:
+        """Erased otadata: the bootloader then boots ota_0."""
+        return b"\xff" * self.partition("otadata").size
+
+    def label(self) -> str:
+        """Choice text: compile date first (that is what the technician picks by)."""
+        kind = "" if self.kind == "merged" else ", app only"
+        return f"Compiled {self.app.compiled}  -  v{self.app.version} [{self.app.elf_sha[:8]}]{kind}  ({self.name})"
+
+
+# ---------------------------------------------------------------- parsing
+
+def parse_partition_table(raw: bytes) -> tuple[Partition, ...]:
+    parts = []
+    for i in range(0, len(raw) - 31, 32):
+        entry = raw[i:i + 32]
+        magic = entry[:2]
+        if magic == b"\xaa\x50":
+            _, ptype, sub, off, size = struct.unpack_from("<HBBII", entry)
+            label = entry[12:28].split(b"\0")[0].decode("ascii", "replace")
+            parts.append(Partition(label, ptype, sub, off, size))
+        elif magic in (b"\xeb\xeb", b"\xff\xff"):   # MD5 entry / end
+            break
+        else:
+            raise ImageError(f"corrupt partition table entry at 0x{PT_OFFSET + i:x}")
+    return tuple(parts)
+
+
+def app_image_length(data: bytes, offset: int = 0) -> int:
+    """Validate an ESP app image at `offset`; return its exact length.
+
+    Checks the segment checksum and, when the header says so, the appended
+    SHA-256 - the same checks the bootloader performs before booting it.
+    """
+    if len(data) < offset + 24 or data[offset] != IMAGE_MAGIC:
+        raise ImageError(f"no firmware image at 0x{offset:x}")
+    segments = data[offset + 1]
+    chip_id = struct.unpack_from("<H", data, offset + 12)[0]
+    if chip_id != ESP32S3_CHIP_ID:
+        raise ImageError(f"image is for chip id {chip_id}, not ESP32-S3")
+    hash_appended = data[offset + 23] == 1
+    pos, checksum = offset + 24, 0xEF
+    for _ in range(segments):
+        if pos + 8 > len(data):
+            raise ImageError("image is truncated (segment header missing)")
+        _, seg_len = struct.unpack_from("<II", data, pos)
+        pos += 8
+        if pos + seg_len > len(data):
+            raise ImageError("image is truncated (segment data missing)")
+        for b in data[pos:pos + seg_len]:
+            checksum ^= b
+        pos += seg_len
+    pos += 15 - ((pos - offset) % 16)          # pad so the checksum ends a 16-byte block
+    if pos >= len(data) or data[pos] != checksum:
+        raise ImageError("image checksum is wrong - the file is corrupted")
+    pos += 1
+    if hash_appended:
+        if pos + 32 > len(data):
+            raise ImageError("image is truncated (SHA-256 missing)")
+        if hashlib.sha256(data[offset:pos]).digest() != data[pos:pos + 32]:
+            raise ImageError("image SHA-256 does not match its content - the file is corrupted")
+        pos += 32
+    return pos - offset
+
+
+def _app_info(data: bytes, offset: int) -> AppInfo:
+    d = data[offset + 0x20:offset + 0x20 + 256]
+    if len(d) < 256 or struct.unpack_from("<I", d)[0] != APP_DESC_MAGIC:
+        raise ImageError("firmware has no ESP-IDF app descriptor")
+    s = lambda o, n: d[o:o + n].split(b"\0")[0].decode("ascii", "replace")
+    info = AppInfo(project=s(48, 32), version=s(16, 32), built=f"{s(96, 16)} {s(80, 16)}",
+                   idf=s(112, 32), elf_sha=d[144:176].hex())
+    if info.project != "kota-sensorboard":
+        raise ImageError(f"firmware is {info.project!r}, not kota-sensorboard")
+    return info
+
+
+
+def inspect_image(path: Path, reference: FirmwareImage | None = None) -> FirmwareImage:
+    """Validate a merged or app-only image. App-only images need a `reference`
+    (a merged image) that provides the flash layout."""
+    data = path.read_bytes()
+    if len(data) >= PT_OFFSET + PT_SIZE and data[0] == IMAGE_MAGIC and data[PT_OFFSET:PT_OFFSET + 2] == b"\xaa\x50":
+        app_image_length(data, 0)              # bootloader must be intact
+        table = data[PT_OFFSET:PT_OFFSET + PT_SIZE]
+        parts = parse_partition_table(table)
+        labels = {p.label for p in parts}
+        for need in ("nvs", "otadata", "ota_0"):
+            if need not in labels:
+                raise ImageError(f"partition table has no {need!r} partition")
+        ota0 = next(p for p in parts if p.label == "ota_0")
+        kind, app_off, flash_size = "merged", ota0.offset, FLASH_SIZES.get(data[3] >> 4, "?")
+    elif data[:1] == bytes([IMAGE_MAGIC]):
+        if reference is None:
+            raise ImageError("app-only file, but there is no complete (merged) image in the folder "
+                             "to take the flash layout from")
+        kind, app_off = "app", 0
+        parts, table, flash_size = reference.partitions, reference.partition_table, reference.flash_size
+        ota0 = next(p for p in parts if p.label == "ota_0")
+    else:
+        raise ImageError("not an ESP32 firmware file")
+    length = app_image_length(data, app_off)
+    if length > ota0.size:
+        raise ImageError(f"firmware ({length} bytes) does not fit the ota_0 partition ({ota0.size} bytes)")
+    app = _app_info(data, app_off)
+    return FirmwareImage(path, kind, hashlib.sha256(data).hexdigest(),
+                         flash_size, parts, table, app_off, length, app)
+
+
+# ------------------------------------------------------------- catalogue
+
+def folder_images(folder: Path = FIRMWARE_DIR) -> tuple[list[FirmwareImage], list[str]]:
+    """(valid images newest-compiled first, problems) for the .bin files in `folder`.
+
+    A broken or foreign file is reported, never offered. The same build
+    under two file names is offered once.
+    """
+    if not folder.is_dir():
+        return [], [f"firmware folder not found: {folder}"]
+    files = sorted(p for p in folder.iterdir() if p.is_file() and p.suffix.lower() == ".bin")
+    merged: list[FirmwareImage] = []
+    app_only: list[Path] = []
+    problems: list[str] = []
+    for f in files:
+        try:
+            merged.append(inspect_image(f))
+        except ImageError as exc:
+            if "app-only" in str(exc):
+                app_only.append(f)
+            else:
+                problems.append(f"{f.name}: {exc}")
+        except OSError as exc:
+            problems.append(f"{f.name}: cannot read ({exc})")
+    merged.sort(key=_newest_first)
+    reference = merged[0] if merged else None
+    images = list(merged)
+    for f in app_only:
+        try:
+            images.append(inspect_image(f, reference))
+        except (ImageError, OSError) as exc:
+            problems.append(f"{f.name}: {exc}")
+    images.sort(key=_newest_first)
+    unique: dict[str, FirmwareImage] = {}
+    for img in images:
+        if img.sha256 in unique:
+            problems.append(f"{img.name}: same file as {unique[img.sha256].name} (listed once)")
+        else:
+            unique[img.sha256] = img
+    return list(unique.values()), problems
+
+
+def _newest_first(img: FirmwareImage) -> tuple:
+    # Unknown compile dates last; merged before app-only for the same date.
+    t = img.app.built_at
+    return (t is None, -t.timestamp() if t else 0.0, img.kind != "merged", img.name)

kota_tech/matter/payload.py

@@ -1,96 +1,113 @@
-"""Matter onboarding payloads: the "MT:..." QR string and the 11-digit manual code.
-
-Implements the Matter spec (5.1.3 QR payload, 5.1.4 manual pairing code):
-bit fields packed LSB-first, Base38 in 3-byte chunks, Verhoeff check digit.
-
-The sensorbox firmware uses the Matter SDK example commissionable data
-(CONFIG_EXAMPLE_COMMISSIONABLE_DATA_PROVIDER): every v1.0 box advertises
-VID 0xFFF1 / PID 0x8000 / discriminator 3840 with passcode 20202021, which is
-exactly the sticker (QR "MT:Y.K9042C00KA0648G00", manual 3497-011-2332).
-VID/PID/discriminator are taken from the box's own log when available; the
-passcode is never logged, so the known default is used.
-"""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-
-BASE38 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ-."
-RENDEZVOUS_BLE = 1 << 1
-DEFAULT_PASSCODE = 20202021          # Matter SDK test passcode used by the v1.0 firmware
-DEFAULT = dict(vendor_id=0xFFF1, product_id=0x8000, discriminator=3840)
-
-# chip[DIS]: Advertise commission parameter vendorID=65521 productID=32768 discriminator=3840/15 cm=1 cp=0
-_ADVERTISE = re.compile(r"vendorID=(\d+) productID=(\d+) discriminator=(\d+)")
-
-
-@dataclass(frozen=True)
-class SetupPayload:
-    vendor_id: int = DEFAULT["vendor_id"]
-    product_id: int = DEFAULT["product_id"]
-    discriminator: int = DEFAULT["discriminator"]
-    passcode: int = DEFAULT_PASSCODE
-    rendezvous: int = RENDEZVOUS_BLE
-    flow: int = 0                     # standard commissioning flow
-    version: int = 0
-    from_log: bool = False            # VID/PID/discriminator read from this box's log
-
-    def qr_text(self) -> str:
-        fields = [(self.version, 3), (self.vendor_id, 16), (self.product_id, 16), (self.flow, 2),
-                  (self.rendezvous, 8), (self.discriminator, 12), (self.passcode, 27), (0, 4)]
-        value, shift = 0, 0
-        for v, bits in fields:
-            if not 0 <= v < (1 << bits):
-                raise ValueError(f"field value {v} does not fit in {bits} bits")
-            value |= v << shift
-            shift += bits
-        return "MT:" + _base38(value.to_bytes(shift // 8, "little"))
-
-    def manual_code(self) -> str:
-        short = self.discriminator >> 8                       # upper 4 bits
-        chunk1 = short >> 2                                   # vid_pid_present = 0
-        chunk2 = ((short & 0x3) << 14) | (self.passcode & 0x3FFF)
-        chunk3 = self.passcode >> 14
-        digits = f"{chunk1}{chunk2:05d}{chunk3:04d}"
-        return digits + str(verhoeff_check(digits))
-
-    def manual_code_pretty(self) -> str:
-        c = self.manual_code()
-        return f"{c[:4]}-{c[4:7]}-{c[7:]}"
-
-
-def _base38(data: bytes) -> str:
-    out = []
-    for i in range(0, len(data), 3):
-        chunk = data[i:i + 3]
-        value = int.from_bytes(chunk, "little")
-        for _ in range({3: 5, 2: 4, 1: 2}[len(chunk)]):
-            value, rem = divmod(value, 38)
-            out.append(BASE38[rem])
-    return "".join(out)
-
-
-_D = [[0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [1, 2, 3, 4, 0, 6, 7, 8, 9, 5], [2, 3, 4, 0, 1, 7, 8, 9, 5, 6],
-      [3, 4, 0, 1, 2, 8, 9, 5, 6, 7], [4, 0, 1, 2, 3, 9, 5, 6, 7, 8], [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
-      [6, 5, 9, 8, 7, 1, 0, 4, 3, 2], [7, 6, 5, 9, 8, 2, 1, 0, 4, 3], [8, 7, 6, 5, 9, 3, 2, 1, 0, 4],
-      [9, 8, 7, 6, 5, 4, 3, 2, 1, 0]]
-_P = [[0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [1, 5, 7, 6, 2, 8, 3, 0, 9, 4], [5, 8, 0, 3, 7, 9, 6, 1, 4, 2],
-      [8, 9, 1, 6, 0, 4, 3, 5, 2, 7], [9, 4, 5, 3, 1, 2, 6, 8, 7, 0], [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
-      [2, 7, 9, 3, 8, 0, 6, 4, 1, 5], [7, 0, 4, 6, 9, 1, 3, 2, 5, 8]]
-_INV = [0, 4, 3, 2, 1, 5, 6, 7, 8, 9]
-
-
-def verhoeff_check(digits: str) -> int:
-    c = 0
-    for i, d in enumerate(reversed(digits)):
-        c = _D[c][_P[(i + 1) % 8][int(d)]]
-    return _INV[c]
-
-
-def payload_from_log(lines: list[str]) -> SetupPayload:
-    """Use the box's advertised VID/PID/discriminator if seen; defaults otherwise."""
-    for text in reversed(lines):
-        if m := _ADVERTISE.search(text):
-            return SetupPayload(int(m.group(1)), int(m.group(2)), int(m.group(3)), from_log=True)
-    return SetupPayload()
+"""Matter onboarding payloads: the "MT:..." QR string and the 11-digit manual code.
+
+Implements the Matter spec (5.1.3 QR payload, 5.1.4 manual pairing code):
+bit fields packed LSB-first, Base38 in 3-byte chunks, Verhoeff check digit.
+
+The sensorbox firmware uses the Matter SDK example commissionable data
+(CONFIG_EXAMPLE_COMMISSIONABLE_DATA_PROVIDER): every v1.0 box advertises
+VID 0xFFF1 / PID 0x8000 / discriminator 3840 with passcode 20202021, which is
+exactly the sticker (QR "MT:Y.K9042C00KA0648G00", manual 3497-011-2332).
+VID/PID/discriminator are taken from the box's own log when available; the
+passcode is never logged, so the known default is used.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+BASE38 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ-."
+RENDEZVOUS_BLE = 1 << 1
+DEFAULT_PASSCODE = 20202021          # Matter SDK test passcode used by the v1.0 firmware
+DEFAULT = dict(vendor_id=0xFFF1, product_id=0x8000, discriminator=3840)
+
+# chip[DIS]: Advertise commission parameter vendorID=65521 productID=32768 discriminator=3840/15 cm=1 cp=0
+_ADVERTISE = re.compile(r"vendorID=(\d+) productID=(\d+) discriminator=(\d+)")
+
+
+@dataclass(frozen=True)
+class SetupPayload:
+    vendor_id: int = DEFAULT["vendor_id"]
+    product_id: int = DEFAULT["product_id"]
+    discriminator: int = DEFAULT["discriminator"]
+    passcode: int = DEFAULT_PASSCODE
+    rendezvous: int = RENDEZVOUS_BLE
+    flow: int = 0                     # standard commissioning flow
+    version: int = 0
+    from_log: bool = False            # VID/PID/discriminator read from this box's log
+    qr: str | None = None             # exact payload reported by the box ("KOTA: matter qr=MT:...")
+    manual: str | None = None         # exact 11-digit manual code reported by the box
+
+    @property
+    def from_box(self) -> bool:
+        return self.qr is not None
+
+    def qr_text(self) -> str:
+        if self.qr:
+            return self.qr
+        fields = [(self.version, 3), (self.vendor_id, 16), (self.product_id, 16), (self.flow, 2),
+                  (self.rendezvous, 8), (self.discriminator, 12), (self.passcode, 27), (0, 4)]
+        value, shift = 0, 0
+        for v, bits in fields:
+            if not 0 <= v < (1 << bits):
+                raise ValueError(f"field value {v} does not fit in {bits} bits")
+            value |= v << shift
+            shift += bits
+        return "MT:" + _base38(value.to_bytes(shift // 8, "little"))
+
+    def manual_code(self) -> str:
+        if self.manual:
+            return self.manual
+        short = self.discriminator >> 8                       # upper 4 bits
+        chunk1 = short >> 2                                   # vid_pid_present = 0
+        chunk2 = ((short & 0x3) << 14) | (self.passcode & 0x3FFF)
+        chunk3 = self.passcode >> 14
+        digits = f"{chunk1}{chunk2:05d}{chunk3:04d}"
+        return digits + str(verhoeff_check(digits))
+
+    def manual_code_pretty(self) -> str:
+        c = self.manual_code()
+        return f"{c[:4]}-{c[4:7]}-{c[7:]}"
+
+
+def _base38(data: bytes) -> str:
+    out = []
+    for i in range(0, len(data), 3):
+        chunk = data[i:i + 3]
+        value = int.from_bytes(chunk, "little")
+        for _ in range({3: 5, 2: 4, 1: 2}[len(chunk)]):
+            value, rem = divmod(value, 38)
+            out.append(BASE38[rem])
+    return "".join(out)
+
+
+_D = [[0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [1, 2, 3, 4, 0, 6, 7, 8, 9, 5], [2, 3, 4, 0, 1, 7, 8, 9, 5, 6],
+      [3, 4, 0, 1, 2, 8, 9, 5, 6, 7], [4, 0, 1, 2, 3, 9, 5, 6, 7, 8], [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
+      [6, 5, 9, 8, 7, 1, 0, 4, 3, 2], [7, 6, 5, 9, 8, 2, 1, 0, 4, 3], [8, 7, 6, 5, 9, 3, 2, 1, 0, 4],
+      [9, 8, 7, 6, 5, 4, 3, 2, 1, 0]]
+_P = [[0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [1, 5, 7, 6, 2, 8, 3, 0, 9, 4], [5, 8, 0, 3, 7, 9, 6, 1, 4, 2],
+      [8, 9, 1, 6, 0, 4, 3, 5, 2, 7], [9, 4, 5, 3, 1, 2, 6, 8, 7, 0], [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
+      [2, 7, 9, 3, 8, 0, 6, 4, 1, 5], [7, 0, 4, 6, 9, 1, 3, 2, 5, 8]]
+_INV = [0, 4, 3, 2, 1, 5, 6, 7, 8, 9]
+
+
+def verhoeff_check(digits: str) -> int:
+    c = 0
+    for i, d in enumerate(reversed(digits)):
+        c = _D[c][_P[(i + 1) % 8][int(d)]]
+    return _INV[c]
+
+
+def payload_from_log(lines: list[str], qr: str | None = None, manual: str | None = None) -> SetupPayload:
+    """Firmware 1.0.16+ reports its exact QR payload and manual code
+    ("KOTA: matter ... qr=MT:... manual=..."); older firmware: use the
+    advertised VID/PID/discriminator if seen; defaults otherwise."""
+    base = SetupPayload()
+    for text in reversed(lines):
+        if m := _ADVERTISE.search(text):
+            base = SetupPayload(int(m.group(1)), int(m.group(2)), int(m.group(3)), from_log=True)
+            break
+    if qr:
+        return SetupPayload(base.vendor_id, base.product_id, base.discriminator, from_log=True,
+                            qr=qr, manual=manual if manual and manual.isdigit() else None)
+    return base

kota_tech/sd/provision.py

@@ -1,260 +1,261 @@
-"""Format an SD card for the sensorbox and write / check ENV.TXT.
-
-Card format required by the firmware: MBR partition table, FAT32 (its FAT
-driver has no exFAT and no long file names), ENV.TXT in the root.
-
-Windows: formatting needs administrator rights, so kota_tech.sd.win_format
-runs elevated (UAC prompt). It re-checks the disk (number, size, bus, not the
-Windows drive) right before erasing it, so a card swapped after the
-technician confirmed is not touched, and it writes MBR + FAT32 itself
-(no Storage cmdlets, which stalled on empty card-reader slots). Larger cards
-get a 32 GB FAT32 partition (Windows convention; plenty for the box).
-macOS: `diskutil eraseDisk FAT32 KOTA MBRFormat` (same as format_sd.sh).
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import plistlib
-import subprocess
-import sys
-import time
-import uuid
-from dataclasses import dataclass, field
-from pathlib import Path
-
-from .disks import Disk
-from .envfile import BUFFER_NAME, ENV_NAME, EnvCheck, EnvConfig, find_case_insensitive, parse_env
-
-VOLUME_LABEL = "KOTA"
-
-
-@dataclass
-class Outcome:
-    ok: bool
-    message: str
-    mount: str = ""
-    log: list[str] = field(default_factory=list)
-
-
-@dataclass
-class CardReport:
-    mount: str
-    filesystem: str
-    env: EnvCheck | None
-    buffered_lines: int | None      # measurements waiting on the card for upload
-    problems: list[str]
-
-
-# ----------------------------------------------------------------- Windows
-
-WORK_ROOT = Path.home() / "KotaTechnicianTool" / "tmp"
-
-
-def _workdir() -> Path:
-    # Not tempfile.mkdtemp(): on Windows it creates an owner-only folder, and a
-    # file written there by the ELEVATED script is then unreadable for this
-    # (non-elevated) process. A normally inherited ACL works for both.
-    work = WORK_ROOT / f"sd_{uuid.uuid4().hex[:10]}"
-    work.mkdir(parents=True, exist_ok=False)
-    return work
-
-
-def win_format_command(disk: Disk, result: Path) -> tuple[str, str, str]:
-    """(program, parameters, working dir) for the elevated helper."""
-    root = Path(__file__).resolve().parents[2]            # the version folder holding kota_tech/
-    params = f'-m kota_tech.sd.win_format --disk {int(disk.id)} --size {int(disk.size)} ' \
-             f'--label {VOLUME_LABEL} --result "{result}"'
-    return sys.executable, params, str(root)
-
-
-def _run_elevated(program: str, params: str, cwd: str, timeout_s: int = 300) -> int | None:
-    """ShellExecuteEx 'runas' + wait. None if the technician refused the UAC prompt."""
-    import ctypes
-    from ctypes import wintypes
-
-    class SHELLEXECUTEINFOW(ctypes.Structure):
-        _fields_ = [("cbSize", wintypes.DWORD), ("fMask", ctypes.c_ulong), ("hwnd", wintypes.HWND),
-                    ("lpVerb", wintypes.LPCWSTR), ("lpFile", wintypes.LPCWSTR), ("lpParameters", wintypes.LPCWSTR),
-                    ("lpDirectory", wintypes.LPCWSTR), ("nShow", ctypes.c_int), ("hInstApp", wintypes.HINSTANCE),
-                    ("lpIDList", ctypes.c_void_p), ("lpClass", wintypes.LPCWSTR), ("hkeyClass", wintypes.HKEY),
-                    ("dwHotKey", wintypes.DWORD), ("hIconOrMonitor", wintypes.HANDLE), ("hProcess", wintypes.HANDLE)]
-
-    SEE_MASK_NOCLOSEPROCESS, SW_HIDE = 0x40, 0
-    info = SHELLEXECUTEINFOW(cbSize=ctypes.sizeof(SHELLEXECUTEINFOW), fMask=SEE_MASK_NOCLOSEPROCESS,
-                             lpVerb="runas", lpFile=program, lpParameters=params, lpDirectory=cwd, nShow=SW_HIDE)
-    shell32 = ctypes.WinDLL("shell32", use_last_error=True)
-    k32 = ctypes.WinDLL("kernel32", use_last_error=True)
-    if not shell32.ShellExecuteExW(ctypes.byref(info)):
-        return None                                            # ERROR_CANCELLED (1223) or failure
-    k32.WaitForSingleObject(info.hProcess, timeout_s * 1000)
-    code = wintypes.DWORD()
-    k32.GetExitCodeProcess(info.hProcess, ctypes.byref(code))
-    k32.CloseHandle(info.hProcess)
-    return code.value
-
-
-def _format_windows(disk: Disk, log: list[str]) -> Outcome:
-    result = _workdir() / "result.json"
-    log.append("Asking Windows for administrator rights to format the card (UAC prompt)...")
-    t = time.perf_counter()
-    code = _run_elevated(*win_format_command(disk, result))
-    if code is None:
-        return Outcome(False, "Administrator permission was refused - the card was not formatted.", log=log)
-    try:
-        res = json.loads(result.read_text(encoding="utf-8"))
-    except (OSError, ValueError) as exc:
-        return Outcome(False, f"The formatter did not report back ({exc.__class__.__name__}, exit {code}). "
-                              "Check the card with 'Check card'.", log=log)
-    steps = ", ".join(f"{k} {v:.1f} s" for k, v in res.get("timings", {}).items())
-    log.append(f"{res.get('message', '')} ({time.perf_counter() - t:.1f} s incl. permission prompt; {steps})")
-    return Outcome(bool(res.get("ok")), res.get("message", ""), res.get("drive", ""), log)
-
-
-def _eject_windows(mount: str) -> bool:
-    """Flush, lock, dismount and eject the card - what 'Safely Remove' does.
-
-    Not Shell.Application InvokeVerb('Eject'): it fails silently because the
-    verb is named 'E&ject' (and is localised on non-English Windows).
-    """
-    import ctypes
-    from ctypes import wintypes
-
-    k32 = ctypes.WinDLL("kernel32", use_last_error=True)
-    k32.CreateFileW.restype = wintypes.HANDLE
-    k32.CreateFileW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, wintypes.LPVOID,
-                                wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE]
-    k32.DeviceIoControl.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.LPVOID, wintypes.DWORD,
-                                    wintypes.LPVOID, wintypes.DWORD, ctypes.POINTER(wintypes.DWORD), wintypes.LPVOID]
-    GENERIC_RW, SHARE_RW, OPEN_EXISTING = 0xC0000000, 0x3, 3
-    FSCTL_LOCK_VOLUME, FSCTL_DISMOUNT_VOLUME = 0x00090018, 0x00090020
-    IOCTL_STORAGE_MEDIA_REMOVAL, IOCTL_STORAGE_EJECT_MEDIA = 0x002D4804, 0x002D4808
-    handle = k32.CreateFileW(f"\\\\.\\{mount[0]}:", GENERIC_RW, SHARE_RW, None, OPEN_EXISTING, 0, None)
-    if handle in (None, wintypes.HANDLE(-1).value):
-        return False
-    ret = wintypes.DWORD()
-
-    def ioctl(code: int, buf=None, size: int = 0) -> bool:
-        return bool(k32.DeviceIoControl(handle, code, buf, size, None, 0, ctypes.byref(ret), None))
-
-    try:
-        k32.FlushFileBuffers(handle)
-        for _ in range(10):                       # Explorer/indexer may hold it briefly
-            if ioctl(FSCTL_LOCK_VOLUME):
-                break
-            time.sleep(0.5)
-        else:
-            return False
-        if not ioctl(FSCTL_DISMOUNT_VOLUME):
-            return False
-        allow = ctypes.c_bool(False)              # PREVENT_MEDIA_REMOVAL{FALSE}
-        ioctl(IOCTL_STORAGE_MEDIA_REMOVAL, ctypes.byref(allow), 1)
-        ioctl(IOCTL_STORAGE_EJECT_MEDIA)          # card readers may not support it; dismount suffices
-        return True
-    finally:
-        k32.CloseHandle(handle)
-
-
-# ------------------------------------------------------------------- macOS
-
-def _format_macos(disk: Disk, log: list[str]) -> Outcome:
-    log.append(f"diskutil eraseDisk FAT32 {VOLUME_LABEL} MBRFormat {disk.id}")
-    proc = subprocess.run(["diskutil", "eraseDisk", "FAT32", VOLUME_LABEL, "MBRFormat", disk.id],
-                          capture_output=True, text=True, timeout=600)
-    log += [l for l in proc.stdout.splitlines() if l.strip()]
-    if proc.returncode != 0:
-        return Outcome(False, "Formatting failed: " + (proc.stderr.strip() or proc.stdout.strip()[-200:])
-                       + " (is the card's write-protect switch on?)", log=log)
-    part = f"{disk.id}s1"
-    for _ in range(20):   # wait for the volume to mount
-        info = plistlib.loads(subprocess.run(["diskutil", "info", "-plist", part], capture_output=True).stdout or b"<plist><dict/></plist>")
-        if info.get("MountPoint"):
-            return Outcome(True, "Formatted FAT32 (MBR).", info["MountPoint"], log)
-        time.sleep(0.5)
-    return Outcome(False, "Formatted, but the card did not mount.", log=log)
-
-
-def _eject_macos(disk_id: str) -> bool:
-    return subprocess.run(["diskutil", "eject", disk_id], capture_output=True, timeout=60).returncode == 0
-
-
-# ------------------------------------------------------------------ common
-
-def write_env(mount: str, env: EnvConfig) -> Outcome:
-    """Write ENV.TXT (8.3 name, LF, no BOM), keep other files (buffered data), read back."""
-    problems = [i.text for i in env.problems() if i.level == "error"]
-    if problems:
-        return Outcome(False, "Settings are not valid: " + " ".join(problems))
-    root = Path(mount)
-    if not root.is_dir():
-        return Outcome(False, f"Card not found at {mount}.")
-    old = find_case_insensitive(root, ENV_NAME)
-    if old is not None and old.name != ENV_NAME:
-        old.unlink()                                   # replace env.txt / Env.txt variants
-    target = root / ENV_NAME
-    data = env.render()
-    with open(target, "wb") as fh:
-        fh.write(data)
-        fh.flush()
-        os.fsync(fh.fileno())
-    if target.read_bytes() != data:
-        return Outcome(False, "ENV.TXT read-back does not match - the card may be faulty.")
-    check = parse_env(target.read_bytes())
-    if not check.ok:
-        return Outcome(False, "ENV.TXT was written but does not validate: "
-                       + " ".join(i.text for i in check.issues if i.level == "error"))
-    return Outcome(True, f"ENV.TXT written and verified on {mount}.", mount)
-
-
-def format_and_write(disk: Disk, env: EnvConfig, eject_card: bool = True) -> Outcome:
-    problems = [i.text for i in env.problems() if i.level == "error"]
-    if problems:
-        return Outcome(False, "Settings are not valid: " + " ".join(problems))
-    log: list[str] = []
-    if sys.platform == "win32":
-        fmt = _format_windows(disk, log)
-    elif sys.platform == "darwin":
-        fmt = _format_macos(disk, log)
-    else:
-        return Outcome(False, "SD provisioning is supported on Windows and macOS only.")
-    if not fmt.ok:
-        return fmt
-    wr = write_env(fmt.mount, env)
-    log.append(wr.message)
-    if not wr.ok:
-        return Outcome(False, wr.message, fmt.mount, log)
-    if eject_card:
-        log.append("Card ejected - you can remove it." if eject(fmt.mount, disk) else
-                   "Could not eject the card automatically - use 'Safely remove' before pulling it out.")
-    return Outcome(True, "Card ready: formatted FAT32 and ENV.TXT verified.", fmt.mount, log)
-
-
-def eject(mount: str, disk: Disk | None = None) -> bool:
-    """True if the card was dismounted and can be pulled out safely."""
-    if sys.platform == "win32":
-        return _eject_windows(mount)
-    if sys.platform == "darwin" and disk is not None:
-        return _eject_macos(disk.id)
-    return False
-
-
-def check_card(mount: str, filesystem: str = "") -> CardReport:
-    """What the box would find on this card (values masked in the UI)."""
-    root = Path(mount)
-    problems: list[str] = []
-    fs = filesystem.upper()
-    if fs and "FAT32" not in fs and fs not in ("FAT", "MS-DOS FAT32", "MSDOS"):
-        problems.append(f"File system is {filesystem}; the box needs FAT32 - re-format the card.")
-    env_file = find_case_insensitive(root, ENV_NAME)
-    env = parse_env(env_file.read_bytes()) if env_file else None
-    if env_file is None:
-        problems.append("No ENV.TXT on the card - the box stops at start-up (white LED).")
-    elif len(env_file.name.split(".")[0]) > 8:
-        problems.append("ENV.TXT has a long name variant; use exactly ENV.TXT.")
-    buf = find_case_insensitive(root, BUFFER_NAME)
-    lines = None
-    if buf is not None:
-        with open(buf, "rb") as fh:
-            lines = sum(1 for ln in fh if ln.strip())
-    return CardReport(mount, filesystem, env, lines, problems)
+"""Format an SD card for the sensorbox and write / check ENV.TXT.
+
+Card format required by the firmware: MBR partition table, FAT32 (its FAT
+driver has no exFAT and no long file names), ENV.TXT in the root.
+
+Windows: formatting needs administrator rights, so kota_tech.sd.win_format
+runs elevated (UAC prompt). It re-checks the disk (number, size, bus, not the
+Windows drive) right before erasing it, so a card swapped after the
+technician confirmed is not touched, and it writes MBR + FAT32 itself
+(no Storage cmdlets, which stalled on empty card-reader slots). Larger cards
+get a 32 GB FAT32 partition (Windows convention; plenty for the box).
+macOS: `diskutil eraseDisk FAT32 KOTA MBRFormat` (same as format_sd.sh).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import plistlib
+import subprocess
+import sys
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .disks import Disk
+from .envfile import BUFFER_NAME, ENV_NAME, EnvCheck, EnvConfig, find_case_insensitive, parse_env
+
+VOLUME_LABEL = "KOTA"
+
+
+@dataclass
+class Outcome:
+    ok: bool
+    message: str
+    mount: str = ""
+    log: list[str] = field(default_factory=list)
+
+
+@dataclass
+class CardReport:
+    mount: str
+    filesystem: str
+    env: EnvCheck | None
+    buffered_lines: int | None      # measurements waiting on the card for upload
+    problems: list[str]
+
+
+# ----------------------------------------------------------------- Windows
+
+WORK_ROOT = Path.home() / "KotaTechnicianTool" / "tmp"
+
+
+def _workdir() -> Path:
+    # Not tempfile.mkdtemp(): on Windows it creates an owner-only folder, and a
+    # file written there by the ELEVATED script is then unreadable for this
+    # (non-elevated) process. A normally inherited ACL works for both.
+    work = WORK_ROOT / f"sd_{uuid.uuid4().hex[:10]}"
+    work.mkdir(parents=True, exist_ok=False)
+    return work
+
+
+def win_format_command(disk: Disk, result: Path) -> tuple[str, str, str]:
+    """(program, parameters, working dir) for the elevated helper."""
+    root = Path(__file__).resolve().parents[2]            # the version folder holding kota_tech/
+    params = f'-m kota_tech.sd.win_format --disk {int(disk.id)} --size {int(disk.size)} ' \
+             f'--label {VOLUME_LABEL} --result "{result}"'
+    return sys.executable, params, str(root)
+
+
+def _run_elevated(program: str, params: str, cwd: str, timeout_s: int = 300) -> int | None:
+    """ShellExecuteEx 'runas' + wait. None if the technician refused the UAC prompt."""
+    import ctypes
+    from ctypes import wintypes
+
+    class SHELLEXECUTEINFOW(ctypes.Structure):
+        _fields_ = [("cbSize", wintypes.DWORD), ("fMask", ctypes.c_ulong), ("hwnd", wintypes.HWND),
+                    ("lpVerb", wintypes.LPCWSTR), ("lpFile", wintypes.LPCWSTR), ("lpParameters", wintypes.LPCWSTR),
+                    ("lpDirectory", wintypes.LPCWSTR), ("nShow", ctypes.c_int), ("hInstApp", wintypes.HINSTANCE),
+                    ("lpIDList", ctypes.c_void_p), ("lpClass", wintypes.LPCWSTR), ("hkeyClass", wintypes.HKEY),
+                    ("dwHotKey", wintypes.DWORD), ("hIconOrMonitor", wintypes.HANDLE), ("hProcess", wintypes.HANDLE)]
+
+    SEE_MASK_NOCLOSEPROCESS, SW_HIDE = 0x40, 0
+    info = SHELLEXECUTEINFOW(cbSize=ctypes.sizeof(SHELLEXECUTEINFOW), fMask=SEE_MASK_NOCLOSEPROCESS,
+                             lpVerb="runas", lpFile=program, lpParameters=params, lpDirectory=cwd, nShow=SW_HIDE)
+    shell32 = ctypes.WinDLL("shell32", use_last_error=True)
+    k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    if not shell32.ShellExecuteExW(ctypes.byref(info)):
+        return None                                            # ERROR_CANCELLED (1223) or failure
+    k32.WaitForSingleObject(info.hProcess, timeout_s * 1000)
+    code = wintypes.DWORD()
+    k32.GetExitCodeProcess(info.hProcess, ctypes.byref(code))
+    k32.CloseHandle(info.hProcess)
+    return code.value
+
+
+def _format_windows(disk: Disk, log: list[str]) -> Outcome:
+    result = _workdir() / "result.json"
+    log.append("Asking Windows for administrator rights to format the card (UAC prompt)...")
+    t = time.perf_counter()
+    code = _run_elevated(*win_format_command(disk, result))
+    if code is None:
+        return Outcome(False, "Administrator permission was refused - the card was not formatted.", log=log)
+    try:
+        res = json.loads(result.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        return Outcome(False, f"The formatter did not report back ({exc.__class__.__name__}, exit {code}). "
+                              "Check the card with 'Check card'.", log=log)
+    steps = ", ".join(f"{k} {v:.1f} s" for k, v in res.get("timings", {}).items())
+    log.append(f"{res.get('message', '')} ({time.perf_counter() - t:.1f} s incl. permission prompt; {steps})")
+    return Outcome(bool(res.get("ok")), res.get("message", ""), res.get("drive", ""), log)
+
+
+def _eject_windows(mount: str) -> bool:
+    """Flush, lock, dismount and eject the card - what 'Safely Remove' does.
+
+    Not Shell.Application InvokeVerb('Eject'): it fails silently because the
+    verb is named 'E&ject' (and is localised on non-English Windows).
+    """
+    import ctypes
+    from ctypes import wintypes
+
+    k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    k32.CreateFileW.restype = wintypes.HANDLE
+    k32.CreateFileW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, wintypes.LPVOID,
+                                wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE]
+    k32.DeviceIoControl.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.LPVOID, wintypes.DWORD,
+                                    wintypes.LPVOID, wintypes.DWORD, ctypes.POINTER(wintypes.DWORD), wintypes.LPVOID]
+    GENERIC_RW, SHARE_RW, OPEN_EXISTING = 0xC0000000, 0x3, 3
+    FSCTL_LOCK_VOLUME, FSCTL_DISMOUNT_VOLUME = 0x00090018, 0x00090020
+    IOCTL_STORAGE_MEDIA_REMOVAL, IOCTL_STORAGE_EJECT_MEDIA = 0x002D4804, 0x002D4808
+    handle = k32.CreateFileW(f"\\\\.\\{mount[0]}:", GENERIC_RW, SHARE_RW, None, OPEN_EXISTING, 0, None)
+    if handle in (None, wintypes.HANDLE(-1).value):
+        return False
+    ret = wintypes.DWORD()
+
+    def ioctl(code: int, buf=None, size: int = 0) -> bool:
+        return bool(k32.DeviceIoControl(handle, code, buf, size, None, 0, ctypes.byref(ret), None))
+
+    try:
+        k32.FlushFileBuffers(handle)
+        for _ in range(10):                       # Explorer/indexer may hold it briefly
+            if ioctl(FSCTL_LOCK_VOLUME):
+                break
+            time.sleep(0.5)
+        else:
+            return False
+        if not ioctl(FSCTL_DISMOUNT_VOLUME):
+            return False
+        allow = ctypes.c_bool(False)              # PREVENT_MEDIA_REMOVAL{FALSE}
+        ioctl(IOCTL_STORAGE_MEDIA_REMOVAL, ctypes.byref(allow), 1)
+        ioctl(IOCTL_STORAGE_EJECT_MEDIA)          # card readers may not support it; dismount suffices
+        return True
+    finally:
+        k32.CloseHandle(handle)
+
+
+# ------------------------------------------------------------------- macOS
+
+def _format_macos(disk: Disk, log: list[str]) -> Outcome:
+    log.append(f"diskutil eraseDisk FAT32 {VOLUME_LABEL} MBRFormat {disk.id}")
+    proc = subprocess.run(["diskutil", "eraseDisk", "FAT32", VOLUME_LABEL, "MBRFormat", disk.id],
+                          capture_output=True, text=True, timeout=600)
+    log += [l for l in proc.stdout.splitlines() if l.strip()]
+    if proc.returncode != 0:
+        return Outcome(False, "Formatting failed: " + (proc.stderr.strip() or proc.stdout.strip()[-200:])
+                       + " (is the card's write-protect switch on?)", log=log)
+    part = f"{disk.id}s1"
+    for _ in range(20):   # wait for the volume to mount
+        info = plistlib.loads(subprocess.run(["diskutil", "info", "-plist", part], capture_output=True).stdout or b"<plist><dict/></plist>")
+        if info.get("MountPoint"):
+            return Outcome(True, "Formatted FAT32 (MBR).", info["MountPoint"], log)
+        time.sleep(0.5)
+    return Outcome(False, "Formatted, but the card did not mount.", log=log)
+
+
+def _eject_macos(disk_id: str) -> bool:
+    return subprocess.run(["diskutil", "eject", disk_id], capture_output=True, timeout=60).returncode == 0
+
+
+# ------------------------------------------------------------------ common
+
+def write_env(mount: str, env: EnvConfig) -> Outcome:
+    """Write ENV.TXT (8.3 name, LF, no BOM), keep other files (buffered data), read back."""
+    problems = [i.text for i in env.problems() if i.level == "error"]
+    if problems:
+        return Outcome(False, "Settings are not valid: " + " ".join(problems))
+    root = Path(mount)
+    if not root.is_dir():
+        return Outcome(False, f"Card not found at {mount}.")
+    old = find_case_insensitive(root, ENV_NAME)
+    if old is not None and old.name != ENV_NAME:
+        old.unlink()                                   # replace env.txt / Env.txt variants
+    target = root / ENV_NAME
+    data = env.render()
+    with open(target, "wb") as fh:
+        fh.write(data)
+        fh.flush()
+        os.fsync(fh.fileno())
+    if target.read_bytes() != data:
+        return Outcome(False, "ENV.TXT read-back does not match - the card may be faulty.")
+    check = parse_env(target.read_bytes())
+    if not check.ok:
+        return Outcome(False, "ENV.TXT was written but does not validate: "
+                       + " ".join(i.text for i in check.issues if i.level == "error"))
+    return Outcome(True, f"ENV.TXT written and verified on {mount}.", mount)
+
+
+def format_and_write(disk: Disk, env: EnvConfig, eject_card: bool = True) -> Outcome:
+    problems = [i.text for i in env.problems() if i.level == "error"]
+    if problems:
+        return Outcome(False, "Settings are not valid: " + " ".join(problems))
+    log: list[str] = []
+    if sys.platform == "win32":
+        fmt = _format_windows(disk, log)
+    elif sys.platform == "darwin":
+        fmt = _format_macos(disk, log)
+    else:
+        return Outcome(False, "SD provisioning is supported on Windows and macOS only.")
+    if not fmt.ok:
+        return fmt
+    wr = write_env(fmt.mount, env)
+    log.append(wr.message)
+    if not wr.ok:
+        return Outcome(False, wr.message, fmt.mount, log)
+    if eject_card:
+        log.append("Card ejected - you can remove it." if eject(fmt.mount, disk) else
+                   "Could not eject the card automatically - use 'Safely remove' before pulling it out.")
+    return Outcome(True, "Card ready: formatted FAT32 and ENV.TXT verified.", fmt.mount, log)
+
+
+def eject(mount: str, disk: Disk | None = None) -> bool:
+    """True if the card was dismounted and can be pulled out safely."""
+    if sys.platform == "win32":
+        return _eject_windows(mount)
+    if sys.platform == "darwin" and disk is not None:
+        return _eject_macos(disk.id)
+    return False
+
+
+def check_card(mount: str, filesystem: str = "") -> CardReport:
+    """What the box would find on this card (values masked in the UI)."""
+    root = Path(mount)
+    problems: list[str] = []
+    # Windows says "FAT32"; macOS diskutil says "DOS_FAT_32" / "Windows_FAT_32" / "MS-DOS FAT32".
+    fs = filesystem.upper().replace("_", "").replace(" ", "")
+    if fs and "FAT32" not in fs and fs not in ("FAT", "MSDOS"):
+        problems.append(f"File system is {filesystem}; the box needs FAT32 - re-format the card.")
+    env_file = find_case_insensitive(root, ENV_NAME)
+    env = parse_env(env_file.read_bytes()) if env_file else None
+    if env_file is None:
+        problems.append("No ENV.TXT on the card - the box stops at start-up (white LED).")
+    elif len(env_file.name.split(".")[0]) > 8:
+        problems.append("ENV.TXT has a long name variant; use exactly ENV.TXT.")
+    buf = find_case_insensitive(root, BUFFER_NAME)
+    lines = None
+    if buf is not None:
+        with open(buf, "rb") as fh:
+            lines = sum(1 for ln in fh if ln.strip())
+    return CardReport(mount, filesystem, env, lines, problems)

kota_tech/service/report.py

@@ -1,101 +1,155 @@
-"""Hand-off of a diagnosis to the KOTA service system (Google Apps Script).
-
-The tool opens the box's service page in the technician's browser:
-    <base><MAC>#kota-report=<base64url(JSON)>
-The service page (v1.1.0+) reads the fragment and pre-fills status and note;
-the technician checks it, adds the location and saves - so the report is
-authored by their own Google login and the tool holds no credentials.
-The fragment is never sent to any server (redirect host or Apps Script).
-"""
-
-from __future__ import annotations
-
-import base64
-import json
-import re
-
-from .. import __version__
-from ..diag.engine import Report, Severity
-
-DEFAULT_BASE = "https://service.kota-app.com/"
-NOTE_LIMIT = 4000        # the service form accepts 5000; leave room for the technician
-
-# Status names exactly as in the service system (Code.gs STATUSES).
-OK = "Działa poprawnie"
-CHECK = "Do sprawdzenia"
-IN_SERVICE = "W trakcie serwisu"
-HARDWARE = "Błąd hardware"
-SOFTWARE = "Błąd software"
-POWER = "Problem z zasilaniem"
-CONNECTIVITY = "Problem z łącznością"
-
-# Root-finding rule id prefix -> service status (first match wins).
-_STATUS_BY_RULE = [
-    ("reboot.brownout", POWER), ("reboot.power", POWER), ("tech.power.", POWER),
-    ("sys.crash", SOFTWARE), ("reboot.watchdog", SOFTWARE), ("sys.out_of_resources", SOFTWARE),
-    ("influx.bad_request", SOFTWARE), ("ota.selfcheck_failed", SOFTWARE), ("tech.quick.hung", SOFTWARE),
-    ("rtc.init_failed", HARDWARE), ("rtc.lost_after_sync", HARDWARE), ("i2c.", HARDWARE), ("sensor.", HARDWARE),
-    ("sd.", HARDWARE), ("sen66.", HARDWARE), ("bme688.", HARDWARE), ("as7341.", HARDWARE),
-    ("mic.read_fail", HARDWARE), ("mic.silent", HARDWARE), ("tech.rtc_i2c.", HARDWARE), ("tech.sensors.", HARDWARE),
-    ("tech.mic.mic_faulty", HARDWARE), ("tech.mic.mic_switch_faulty", HARDWARE), ("tech.white.sd_", HARDWARE),
-    ("matter.", CONNECTIVITY), ("net.", CONNECTIVITY), ("wifi.", CONNECTIVITY), ("influx.", CONNECTIVITY),
-    ("ota.", CONNECTIVITY), ("tech.network.", CONNECTIVITY),
-    ("rtc.clock_not_running", CHECK), ("reboot.", CHECK),
-]
-_MAC = re.compile(r"^[0-9A-F]{12}$")
-
-
-def normalize_mac(mac: str) -> str:
-    return re.sub(r"[^0-9A-Fa-f]", "", mac or "").upper()
-
-
-def service_status(report: Report) -> str:
-    """Suggested status; the technician can change it in the form."""
-    problems = [rc for rc in report.roots if rc.severity >= Severity.WARNING]
-    if not problems:
-        return OK if any(m == "data_uploaded" and t is not None for m, _, t in report.milestones) else CHECK
-    rid = problems[0].finding.rule_id
-    for prefix, status in _STATUS_BY_RULE:
-        if rid.startswith(prefix):
-            return status
-    return CHECK
-
-
-def service_note(report: Report, limit: int = NOTE_LIMIT) -> str:
-    lines = [f"[KOTA Technician Tool {__version__}] {report.verdict}",
-             f"Firmware: {report.firmware.describe()}",
-             f"Expected LED: {report.led.capitalize()}"]
-    reached = [label for _, label, t in report.milestones if t is not None]
-    missing = [label for _, label, t in report.milestones if t is None]
-    if reached:
-        lines.append("OK: " + ", ".join(reached))
-    if missing:
-        lines.append("Not reached: " + ", ".join(missing))
-    for rc in report.roots:
-        f = rc.finding
-        lines.append(f"- [{f.severity.label}] {f.title}")
-        for c in rc.consequences:
-            lines.append(f"    -> {c.title}")
-    if report.technician:
-        lines.append("Technician checks:")
-        lines += [f"  * {t}" for t in report.technician[-12:]]
-    text = "\n".join(lines)
-    return text if len(text) <= limit else text[:limit - 20].rstrip() + "\n...(shortened)"
-
-
-def report_url(mac: str, report: Report, base: str = DEFAULT_BASE) -> str:
-    mac = normalize_mac(mac)
-    if not _MAC.match(mac):
-        raise ValueError(f"not a box MAC address: {mac!r}")
-    payload = {"v": 1, "mac": mac, "status": service_status(report), "note": service_note(report),
-               "tool": f"v{__version__}"}
-    raw = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
-    frag = base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
-    base = base if base.endswith("/") else base + "/"
-    return f"{base}{mac}#kota-report={frag}"
-
-
-def decode_fragment(url: str) -> dict:
-    """Inverse of report_url (used by tests and for troubleshooting)."""
-    frag = url.split("#kota-report=", 1)[1]
-    return json.loads(base64.urlsafe_b64decode(frag + "=" * (-len(frag) % 4)).decode("utf-8"))
+"""Hand-off of a diagnosis to the KOTA service system (Google Apps Script).
+
+The tool opens the box's service page in the technician's browser:
+    <base><MAC>#kota-report=<base64url(JSON)>
+The service page (v1.1.0+) reads the fragment and pre-fills status and note;
+the technician checks it, adds the location and saves - so the report is
+authored by their own Google login and the tool holds no credentials.
+The fragment is never sent to any server (redirect host or Apps Script).
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+
+from .. import __version__
+from ..diag.engine import Report, Severity
+
+DEFAULT_BASE = "https://service.kota-app.com/"
+NOTE_LIMIT = 4800        # the service form and Code.gs accept 5000; leave room for the technician
+
+# Status names exactly as in the service system (Code.gs STATUSES).
+OK = "Działa poprawnie"
+CHECK = "Do sprawdzenia"
+IN_SERVICE = "W trakcie serwisu"
+HARDWARE = "Błąd hardware"
+SOFTWARE = "Błąd software"
+POWER = "Problem z zasilaniem"
+CONNECTIVITY = "Problem z łącznością"
+
+# Root-finding rule id prefix -> service status (first match wins).
+_STATUS_BY_RULE = [
+    ("reboot.brownout", POWER), ("reboot.power", POWER), ("tech.power.", POWER),
+    ("sys.crash", SOFTWARE), ("reboot.watchdog", SOFTWARE), ("sys.out_of_resources", SOFTWARE),
+    ("influx.bad_request", SOFTWARE), ("ota.selfcheck_failed", SOFTWARE), ("tech.quick.hung", SOFTWARE),
+    ("rtc.init_failed", HARDWARE), ("rtc.lost_after_sync", HARDWARE), ("i2c.", HARDWARE), ("sensor.", HARDWARE),
+    ("sd.", HARDWARE), ("sen66.", HARDWARE), ("bme688.", HARDWARE), ("as7341.", HARDWARE),
+    ("mic.read_fail", HARDWARE), ("mic.silent", HARDWARE), ("tech.rtc_i2c.", HARDWARE), ("tech.sensors.", HARDWARE),
+    ("tech.mic.mic_faulty", HARDWARE), ("tech.mic.mic_switch_faulty", HARDWARE), ("tech.white.sd_", HARDWARE),
+    ("matter.", CONNECTIVITY), ("net.", CONNECTIVITY), ("wifi.", CONNECTIVITY), ("influx.", CONNECTIVITY),
+    ("ota.", CONNECTIVITY), ("tech.network.", CONNECTIVITY),
+    # firmware 1.0.16+ (KOTA: lines, status, error IDs)
+    ("reboot.crash", SOFTWARE), ("reboot.status_oom_watchdog", SOFTWARE), ("status.oom", SOFTWARE),
+    ("kota.low_heap", SOFTWARE),
+    ("kota.i2c_stuck", HARDWARE), ("kota.sensor_missing", HARDWARE), ("kota.rtc_", HARDWARE),
+    ("kota.sd_", HARDWARE), ("status.error", HARDWARE), ("status.rtc", HARDWARE), ("status.sd", HARDWARE),
+    ("kota.wifi_down", CONNECTIVITY), ("kota.weak_wifi", CONNECTIVITY), ("kota.no_upload", CONNECTIVITY),
+    ("kota.ota_unregistered", CONNECTIVITY), ("kota.buffer_backlog", CONNECTIVITY), ("status.conn", CONNECTIVITY),
+    ("kota.time_invalid", CHECK),
+    *((f"eid.{m}", HARDWARE) for m in ("SD", "ENV", "RTC", "BME", "SEN", "AS", "MIC", "FLK", "SPI")),
+    *((f"eid.{m}", CONNECTIVITY) for m in ("INF", "WIFI", "OTA", "PROV")),
+    ("eid.", SOFTWARE),
+    ("rtc.clock_not_running", CHECK), ("reboot.", CHECK),
+]
+_MAC = re.compile(r"^[0-9A-F]{12}$")
+
+
+def normalize_mac(mac: str) -> str:
+    return re.sub(r"[^0-9A-Fa-f]", "", mac or "").upper()
+
+
+def service_status(report: Report) -> str:
+    """Suggested status; the technician can change it in the form."""
+    problems = [rc for rc in report.roots if rc.severity >= Severity.WARNING]
+    if not problems:
+        return OK if any(m == "data_uploaded" and t is not None for m, _, t in report.milestones) else CHECK
+    rid = problems[0].finding.rule_id
+    for prefix, status in _STATUS_BY_RULE:
+        if rid.startswith(prefix):
+            return status
+    return CHECK
+
+
+BOX_MARK = {"ok": "✔", "warn": "!", "bad": "✖", "info": "i"}   # same marks as the Diagnosis panel
+SD_WIFI = {True: "reads Wi-Fi settings from the SD card",
+           False: "does not read Wi-Fi settings from the SD card",
+           None: "Wi-Fi-from-SD support unknown"}
+
+
+def service_note(report: Report, limit: int = NOTE_LIMIT) -> str:
+    """The Diagnosis panel as text: verdict, LED, firmware, box self-report,
+    start-up progress with times, findings with details and when they were seen.
+
+    Falls back to shorter finding details when the full text does not fit the
+    service form (consequences' explanations first, then all), then truncates.
+    """
+    for detail in ("all", "roots", "none"):
+        text = _note(report, detail)
+        if len(text) <= limit:
+            return text
+    return text[:limit - 20].rstrip() + "\n...(shortened)"
+
+
+def _note(report: Report, detail: str) -> str:
+    fw = report.firmware
+    source = " (reported by the box)" if report.led_exact else ""
+    lines = [f"[KOTA Technician Tool {__version__}] {report.verdict}", "",
+             f"Status LED should be: {report.led_text()}{source}"]
+    if report.led_reason:
+        lines.append(f"  from: {report.led_reason}")
+    lines += ["", f"Firmware: {fw.describe()}", f"  {SD_WIFI[fw.supports_sd_wifi]}"]
+    if report.box:
+        lines += ["", "Box self-report (KOTA lines):"]
+        lines += [f"  {BOX_MARK.get(st, '-')} {topic}: {text}" for topic, text, st in report.box]
+    lines += ["", "Start-up progress (current boot):"]
+    lines += [f"  ✔ {label} ({t / 1000:.1f} s)" if t is not None else f"  ○ {label}"
+              for _, label, t in report.milestones]
+    lines += ["", "Findings - root causes first:" if report.roots else "Findings: no problems detected in the log"]
+    for rc in report.roots:
+        lines += _finding(rc.finding, "", detail in ("all", "roots"))
+        for c in rc.consequences:
+            lines += _finding(c, "    ↳ ", detail == "all")
+    for title, items in (("Seen in earlier boots only", report.earlier),
+                         ("Resolved during this session", report.resolved)):
+        if items:
+            lines += ["", f"{title} ({len(items)}):"]
+            lines += [f"  - [{f.severity.label}] {f.title} - {f.seen_text()}" for f in items]
+    if report.technician:
+        lines += ["", "Technician checks:"]
+        lines += [f"  * {t}" for t in report.technician[-12:]]
+    return "\n".join(lines)
+
+
+def _finding(f, prefix: str, detailed: bool) -> list[str]:
+    ind = " " * len(prefix) + "  "
+    out = [f"{prefix}[{f.severity.label}] {f.title}"]
+    if detailed:
+        out.append(f"{ind}What it means: {f.meaning}")
+        if f.actions:
+            out.append(f"{ind}What to do:")
+            out += [f"{ind}  {i}. {a}" for i, a in enumerate(f.actions, 1)]
+        out += [f"{ind}Error {eid}" + (f": {a}" if a else "") for eid, a in f.error_ids.items()]
+    out.append(f"{ind}{f.seen_text()}")
+    if f.evidence:
+        out.append(f"{ind}Log: {f.evidence[-1]}")
+    return out
+
+
+def report_url(mac: str, report: Report, base: str = DEFAULT_BASE) -> str:
+    mac = normalize_mac(mac)
+    if not _MAC.match(mac):
+        raise ValueError(f"not a box MAC address: {mac!r}")
+    payload = {"v": 1, "mac": mac, "status": service_status(report), "note": service_note(report),
+               "tool": f"v{__version__}"}
+    raw = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    frag = base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+    base = base if base.endswith("/") else base + "/"
+    return f"{base}{mac}#kota-report={frag}"
+
+
+def decode_fragment(url: str) -> dict:
+    """Inverse of report_url (used by tests and for troubleshooting)."""
+    frag = url.split("#kota-report=", 1)[1]
+    return json.loads(base64.urlsafe_b64decode(frag + "=" * (-len(frag) % 4)).decode("utf-8"))

kota_tech/ui/cheatsheet.py

@@ -1,85 +1,87 @@
-"""Quick-start cheat sheet shown on launch.
-
-Targets the DEPLOYED firmware: new_system.bin, app "kota-sensorboard"
-1.0, built Jun 29 2026 11:03:32, ELF SHA256 45fa9d5b9... (verified on a
-live board). That build has no Wi-Fi setup portal / SSID-on-SD support;
-those exist only in the newer, unbuilt source. The status LED is always
-SOLID; the separate small LED toggles every second while alive.
-"""
-
-# (swatch colour, LED name, meaning, first action)
-LED_TABLE = [
-    ("#2e9e44", "Green", "Everything OK.", "Nothing to do."),
-    ("#8e44ad", "Purple",
-     "No Internet / InfluxDB or OTA server unreachable.",
-     "Check the box is commissioned in the Matter app (sticker QR code) and the "
-     "site Wi-Fi has Internet. Board reboots itself after ~2.5 min of purple."),
-    ("#d64541", "Red",
-     "Sensor or hardware fault (BME688, SEN66, AS7341, microphone, flicker) "
-     "or failed self-check after update.",
-     "Connect serial - the log names the failing sensor. Check sensor cables."),
-    ("#2f6fd6", "Blue",
-     "Clock (RTC DS1307) failed to start. The RTC is the first I2C device, "
-     "so a broken I2C cable also shows blue.",
-     "Check the I2C harness first, then the RTC module / coin cell."),
-    ("#e6c229", "Yellow", "Firmware update downloading.", "Do not switch off. Wait."),
-    ("#f08c1a", "Orange", "Self-check after an update (~2.5 min).",
-     "Wait; should turn green (or red on failure)."),
-    ("#f4f4f4", "White",
-     "SD card missing/unreadable or ENV.TXT incomplete - or a factory reset is "
-     "in progress (Matter button held 5 s).",
-     "If nobody pressed the Matter button: the SD card is inside the case - "
-     "unscrew, re-seat or re-provision it."),
-    ("#444444", "Off", "Firmware did not start (or crashed very early).",
-     "Check power switch & USB cable. If the small LED is also dark: re-flash."),
-]
-
-HINTS = [
-    "<b>Colour keeps changing / LED goes dark every few seconds</b> = reboot loop. "
-    "Connect serial and press <i>Reset &amp; capture</i>: the last lines before the "
-    "reboot name the cause.",
-    "<b>Small LED next to the RGB LED</b> blinks once per second while the "
-    "firmware runs. Not blinking = firmware hung or not running.",
-    "<b>Outside the case</b> (back): power switch, the <b>microphone switch</b> just above it "
-    "(off = no noise measurements), and the Matter button. Holding the "
-    "Matter button <b>5 s</b> factory-resets the box (it forgets its Matter "
-    "network and must be commissioned again with the sticker QR code).",
-    "<b>Inside the case</b> (unscrew): RESET and BOOT buttons and the SD card. "
-    "Normally not needed - the tool resets the board over USB.",
-    "<b>Gathering messages for the first ~2 minutes</b> are normal "
-    "(the air-quality sensor warms up for 120 s).",
-]
-
-STEPS = [
-    "Switch the sensorbox <b>power switch ON</b>.",
-    "Connect the laptop to the box's <b>native USB</b> port with a data-capable cable.",
-    "Open the <b>Serial monitor</b> tab, choose the sensorbox port, press "
-    "<b>Connect</b>.",
-    "Press <b>Reset &amp; capture</b> to record a full boot log from the first line.",
-    "Read the <b>Diagnosis</b> panel on the right, then open <b>Guided troubleshooting</b> "
-    "and start <b>Quick check</b>: the tool asks what you see and checks the log live.",
-]
-
-
-def cheatsheet_html() -> str:
-    rows = "".join(
-        f"<tr><td style='padding:6px'><span style='background:{c};"
-        f"border:1px solid #888'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span>&nbsp;<b>{name}</b></td>"
-        f"<td style='padding:6px'>{meaning}</td><td style='padding:6px'>{action}</td></tr>"
-        for c, name, meaning, action in LED_TABLE
-    )
-    steps = "".join(f"<li>{s}</li>" for s in STEPS)
-    hints = "".join(f"<li>{h}</li>" for h in HINTS)
-    return f"""
-    <h2>Sensorbox quick start</h2>
-    <ol>{steps}</ol>
-    <h3>RGB status LED (always solid colour)</h3>
-    <table border='1' cellspacing='0' cellpadding='0' width='100%'>
-      <tr><th align='left' style='padding:6px'>LED</th>
-          <th align='left' style='padding:6px'>Most likely meaning</th>
-          <th align='left' style='padding:6px'>First action</th></tr>
-      {rows}
-    </table>
-    <h3>Good to know</h3>
-    <ul>{hints}</ul>
-    """
+"""Quick-start cheat sheet shown on launch.
+
+LED table for firmware 1.0.16+ (firmware-diagnostics-what-changed.md,
+status.cpp Status::pattern_for): colour AND pattern name the fault. Older
+boxes (v1.0, built Jun 29 2026) show the same colours, always solid.
+"""
+
+# (swatch colour, LED name, pattern -> meaning, first action)
+LED_TABLE = [
+    ("#2e9e44", "Green", "solid: everything OK.", "Nothing to do."),
+    ("#1fc8d8", "Cyan",
+     "breathing: not paired in Matter yet<br>fast blink: a phone is connected for pairing.",
+     "Pair the box in the Matter app (QR sticker or the QR code in the tool)."),
+    ("#f4f4f4", "White",
+     "fast blink: SD card or ENV.TXT error<br>solid: factory reset (Matter button held 5 s)<br>"
+     "breathing: Wi-Fi setup portal.",
+     "SD card is inside the case: re-seat or re-provision it. Setup portal: short-press the button to leave."),
+    ("#d64541", "Red",
+     "1-6 pulses: 1 BME688, 2 SEN66, 3 AS7341, 4 microphone, 5 flicker, 6 self-check failed<br>"
+     "solid: other internal error / out of memory.",
+     "Count the pulses, then check that sensor's cable. The box restarts itself after 150 s."),
+    ("#2f6fd6", "Blue",
+     "1 pulse: clock (RTC) not responding<br>2 pulses: I2C bus stuck (shorted / broken sensor cable).",
+     "Check the I2C cable between the boards first, then the RTC module."),
+    ("#8e44ad", "Purple",
+     "solid: no network<br>blinking: server rejected the box (wrong ENV.TXT credentials).",
+     "Solid: check Wi-Fi / Internet. Blinking: re-provision the SD card with the current ENV.TXT."),
+    ("#e6c229", "Yellow", "blinking, faster over time: downloading an update.", "Do not switch off. Wait."),
+    ("#f08c1a", "Orange", "solid: self-check after an update (~2.5 min).",
+     "Wait; should turn green (or red on failure)."),
+    ("#444444", "Off", "Firmware did not start (or crashed very early).",
+     "Check power switch & USB cable. If the small LED is also dark: re-flash."),
+]
+
+HINTS = [
+    "<b>Before a self-restart</b> the LED flashes the error colour 3 times; <b>after the restart</b> it "
+    "shows the previous error for 3 s. So a reboot loop shows its cause. Connect serial and press "
+    "<i>Reset &amp; capture</i>: the tool reads the restart reason from the box.",
+    "<b>Small LED next to the RGB LED</b> (heartbeat): blinks once per second while online, "
+    "double-blinks while offline. Dark or steady = firmware hung or not running.",
+    "<b>Serial monitor</b>: lines starting with <b>KOTA:</b> are the box's own diagnosis (boot, I2C, SD, "
+    "clock, Matter, microphone, status, LED, and a health line every 60 s). The Diagnosis panel reads them "
+    "directly; filter the view with <i>KOTA diagnostics + errors</i>. Error lines carry a code like "
+    "<b>[E-SD-03]</b> - the tool shows the recommended action for it.",
+    "<b>Outside the case</b> (back): power switch, the <b>microphone switch</b> just above it "
+    "(off = no noise measurements), and the Matter button. Holding the "
+    "Matter button <b>5 s</b> factory-resets the box (it forgets its Matter "
+    "network and must be commissioned again with the sticker QR code).",
+    "<b>Inside the case</b> (unscrew): RESET and BOOT buttons and the SD card. "
+    "Normally not needed - the tool resets the board over USB.",
+    "<b>Flashing</b> uses only the firmware files in the tool's <b>firmware</b> folder; choose the build "
+    "by its compile date.",
+]
+
+STEPS = [
+    "Switch the sensorbox <b>power switch ON</b>.",
+    "Connect the laptop to the box's <b>native USB</b> port with a data-capable cable.",
+    "Open the <b>Serial monitor</b> tab, choose the sensorbox port, press "
+    "<b>Connect</b>.",
+    "Press <b>Reset &amp; capture</b> to record a full boot log from the first line.",
+    "Read the <b>Diagnosis</b> panel on the right, then open <b>Guided troubleshooting</b> "
+    "and start <b>Quick check</b>: the tool asks what you see and checks the log live.",
+]
+
+
+def cheatsheet_html() -> str:
+    rows = "".join(
+        f"<tr><td style='padding:6px'><span style='background:{c};"
+        f"border:1px solid #888'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span>&nbsp;<b>{name}</b></td>"
+        f"<td style='padding:6px'>{meaning}</td><td style='padding:6px'>{action}</td></tr>"
+        for c, name, meaning, action in LED_TABLE
+    )
+    steps = "".join(f"<li>{s}</li>" for s in STEPS)
+    hints = "".join(f"<li>{h}</li>" for h in HINTS)
+    return f"""
+    <h2>Sensorbox quick start</h2>
+    <ol>{steps}</ol>
+    <h3>RGB status LED - colour and pattern</h3>
+    <table border='1' cellspacing='0' cellpadding='0' width='100%'>
+      <tr><th align='left' style='padding:6px'>LED</th>
+          <th align='left' style='padding:6px'>Pattern: meaning</th>
+          <th align='left' style='padding:6px'>First action</th></tr>
+      {rows}
+    </table>
+    <h3>Good to know</h3>
+    <ul>{hints}</ul>
+    """

kota_tech/ui/diag_panel.py

@@ -1,234 +1,252 @@
-"""Diagnostics side panel: renders a diag.engine.Report.
-
-Layout: verdict banner, expected LED, firmware, start-up milestones, a
-findings tree (root causes; their consequences as children; titles only)
-and a wrapped detail pane for the selected finding.
-"""
-
-from __future__ import annotations
-
-from PySide6.QtCore import Qt
-from PySide6.QtGui import QBrush, QColor
-from PySide6.QtWidgets import (
-    QFrame,
-    QHBoxLayout,
-    QLabel,
-    QListWidget,
-    QListWidgetItem,
-    QPushButton,
-    QSizePolicy,
-    QSplitter,
-    QTextBrowser,
-    QTreeWidget,
-    QTreeWidgetItem,
-    QVBoxLayout,
-    QWidget,
-)
-
-from ..diag.engine import LED, Finding, Report, Severity
-
-SEV_COLOR = {
-    Severity.CRITICAL: "#b03a2e",
-    Severity.ERROR: "#d9534f",
-    Severity.WARNING: "#c77c02",
-    Severity.INFO: "#2e6da4",
-}
-# verdict banner (background, text) by verdict severity; None = healthy
-BANNER = {
-    Severity.CRITICAL: ("#f6d5d1", "#7b1e14"),
-    Severity.ERROR: ("#f9dedc", "#8a2019"),
-    Severity.WARNING: ("#fdebc8", "#6b4400"),
-    None: ("#d8f0dd", "#1b5e2a"),
-}
-_KEY = Qt.ItemDataRole.UserRole
-
-
-def _heading(text: str) -> QLabel:
-    lbl = QLabel(text)
-    f = lbl.font()
-    f.setBold(True)
-    lbl.setFont(f)
-    return lbl
-
-
-def _esc(s: str) -> str:
-    return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
-
-
-class DiagnosticsPanel(QWidget):
-    def __init__(self, parent: QWidget | None = None):
-        super().__init__(parent)
-        self.setMinimumWidth(380)
-
-        self.verdict = QLabel(wordWrap=True)
-        self.verdict.setMargin(10)
-        vf = self.verdict.font()
-        vf.setPointSize(vf.pointSize() + 2)
-        vf.setBold(True)
-        self.verdict.setFont(vf)
-
-        self.led_swatch = QLabel()
-        self.led_swatch.setFixedSize(22, 22)
-        self.led_text = QLabel(wordWrap=True)
-        led_row = QHBoxLayout()
-        led_row.addWidget(self.led_swatch, 0, Qt.AlignmentFlag.AlignTop)
-        led_row.addWidget(self.led_text, 1)
-
-        self.firmware = QLabel(wordWrap=True)
-        self.firmware.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
-
-        self.milestones = QListWidget()
-        self.milestones.setFrameShape(QFrame.Shape.NoFrame)
-        self.milestones.setSelectionMode(QListWidget.SelectionMode.NoSelection)
-        self.milestones.setSizePolicy(QSizePolicy.Policy.Preferred, QSizePolicy.Policy.Maximum)
-
-        self.tree = QTreeWidget()
-        self.tree.setHeaderHidden(True)
-        self.tree.setIndentation(16)
-        self.tree.setTextElideMode(Qt.TextElideMode.ElideRight)
-        self.detail = QTextBrowser()
-        self.detail.setOpenExternalLinks(False)
-        findings = QSplitter(Qt.Orientation.Vertical)
-        findings.addWidget(self.tree)
-        findings.addWidget(self.detail)
-        findings.setSizes([220, 260])
-
-        lay = QVBoxLayout(self)
-        lay.setContentsMargins(4, 0, 0, 0)
-        lay.addWidget(self.verdict)
-        lay.addWidget(_heading("Status LED should be"))
-        lay.addLayout(led_row)
-        lay.addWidget(_heading("Firmware"))
-        lay.addWidget(self.firmware)
-        self.qr_btn = QPushButton("Matter pairing QR code...")
-        self.qr_btn.setToolTip("Show the box's Matter QR code on screen to scan with the phone")
-        lay.addWidget(self.qr_btn, 0, Qt.AlignmentFlag.AlignLeft)
-        lay.addWidget(_heading("Start-up progress (current boot)"))
-        lay.addWidget(self.milestones)
-        lay.addWidget(_heading("Findings - root causes first; click one for details"))
-        lay.addWidget(findings, 1)
-
-        self._findings: dict[str, Finding] = {}
-        self._selected: str | None = None
-        # key -> expanded, chosen by the user; survives the rebuild on refresh.
-        self._expanded: dict[str, bool] = {}
-        self.tree.currentItemChanged.connect(self._on_select)
-        self.tree.itemCollapsed.connect(lambda it: self._remember(it, False))
-        self.tree.itemExpanded.connect(lambda it: self._remember(it, True))
-
-    # ------------------------------------------------------------------
-    def show_report(self, r: Report) -> None:
-        bg, fg = BANNER.get(r.verdict_severity, BANNER[Severity.WARNING])
-        if r.lines == 0:
-            bg, fg = "#e6e6e6", "#333333"
-        self.verdict.setText(r.verdict)
-        self.verdict.setStyleSheet(f"QLabel {{ background:{bg}; color:{fg}; border-radius:6px; }}")
-
-        name, colour = LED[r.led]
-        self.led_swatch.setStyleSheet(
-            f"QLabel {{ background:{colour}; border:1px solid #777; border-radius:11px; }}")
-        ask = "" if r.led == "UNKNOWN" else " - <i>check it matches the box</i>"
-        reason = f"<br><small style='color:#666'>from: {_esc(r.led_reason)}</small>" if r.led_reason else ""
-        self.led_text.setText(f"<b>{name}</b>{ask}{reason}")
-
-        fw = r.firmware
-        sd = {True: "reads Wi-Fi settings from the SD card",
-              False: "does not read Wi-Fi settings from the SD card",
-              None: "Wi-Fi-from-SD support unknown"}
-        self.firmware.setText(f"{_esc(fw.describe())}<br><small>{sd[fw.supports_sd_wifi]}</small>")
-
-        self.milestones.clear()
-        for _, label, t in r.milestones:
-            done = t is not None
-            it = QListWidgetItem(("✔  " if done else "○  ") + label
-                                 + (f"   ({t / 1000:.1f} s)" if done else ""))
-            it.setForeground(QBrush(QColor("#1b7a33" if done else "#8a8a8a")))
-            self.milestones.addItem(it)
-        rows = min(max(self.milestones.count(), 1), 15)
-        self.milestones.setFixedHeight(rows * max(self.milestones.sizeHintForRow(0), 16) + 6)
-
-        self._fill_tree(r)
-
-    def _fill_tree(self, r: Report) -> None:
-        self.tree.blockSignals(True)
-        self.tree.clear()
-        self._findings = {}
-        if not r.roots:
-            it = QTreeWidgetItem(["No problems detected in the log so far."])
-            it.setForeground(0, QBrush(QColor("#1b7a33")))
-            self.tree.addTopLevelItem(it)
-        for rc in r.roots:
-            top = self._item(rc.finding, bold=True)
-            self.tree.addTopLevelItem(top)
-            for c in rc.consequences:
-                top.addChild(self._item(c, prefix="↳ "))
-            top.setExpanded(self._expanded.get(rc.finding.key, True))
-        for title, key, items in (("Seen in earlier boots only", "grp:earlier", r.earlier),
-                                  ("Resolved during this session", "grp:resolved", r.resolved)):
-            if not items:
-                continue
-            grp = QTreeWidgetItem([f"{title} ({len(items)})"])
-            grp.setData(0, _KEY, key)
-            grp.setForeground(0, QBrush(QColor("#666666")))
-            self.tree.addTopLevelItem(grp)
-            for f in items:
-                grp.addChild(self._item(f, prefix="✔ " if key == "grp:resolved" else ""))
-            grp.setExpanded(self._expanded.get(key, False))
-        # Keep the selection across refreshes; default to the top root cause.
-        target = self._selected if self._selected in self._findings else (
-            r.roots[0].finding.key if r.roots else None)
-        self.tree.blockSignals(False)
-        self._select(target)
-
-    def _remember(self, item: QTreeWidgetItem, expanded: bool) -> None:
-        if key := item.data(0, _KEY):
-            self._expanded[key] = expanded
-
-    def _item(self, f: Finding, prefix: str = "", bold: bool = False) -> QTreeWidgetItem:
-        it = QTreeWidgetItem([f"{prefix}[{f.severity.label}]  {f.title}"])
-        it.setData(0, _KEY, f.key)
-        it.setForeground(0, QBrush(QColor(SEV_COLOR.get(f.severity, "#333333"))))
-        it.setToolTip(0, f.title)
-        if bold:
-            font = it.font(0)
-            font.setBold(True)
-            it.setFont(0, font)
-        self._findings[f.key] = f
-        return it
-
-    def _select(self, key: str | None) -> None:
-        if key is None:
-            self.detail.setHtml("<p style='color:#666'>Nothing to show yet.</p>")
-            return
-        match = self.tree.findItems("*", Qt.MatchFlag.MatchWildcard | Qt.MatchFlag.MatchRecursive)
-        for it in match:
-            if it.data(0, _KEY) == key:
-                self.tree.setCurrentItem(it)
-                return
-
-    def _on_select(self, cur: QTreeWidgetItem | None, _prev) -> None:
-        key = cur.data(0, _KEY) if cur else None
-        f = self._findings.get(key or "")
-        if f is None:
-            return
-        self._selected = key
-        self.detail.setHtml(_detail_html(f))
-
-
-def _detail_html(f: Finding) -> str:
-    colour = SEV_COLOR.get(f.severity, "#333")
-    actions = "".join(f"<li>{_esc(a)}</li>" for a in f.actions)
-    seen = f"Seen {f.count}x"
-    if f.first_uptime_ms is not None:
-        seen += f", first at {f.first_uptime_ms / 1000:.1f} s after start"
-    if f.resolved and f.resolved_by:
-        seen += f" - resolved ({_esc(f.resolved_by)})"
-    evidence = "<br>".join(_esc(e) for e in f.evidence)
-    return (
-        f"<h3 style='color:{colour}; margin:0'>{_esc(f.title)}</h3>"
-        f"<p><b>What it means:</b> {_esc(f.meaning)}</p>"
-        + (f"<p><b>What to do:</b></p><ol>{actions}</ol>" if actions else "")
-        + f"<p style='color:#666'>{seen}</p>"
-        + (f"<p style='color:#555; font-family:Consolas,Menlo,monospace; font-size:9pt'>{evidence}</p>"
-           if evidence else "")
-    )
+"""Diagnostics side panel: renders a diag.engine.Report.
+
+Layout: verdict banner, expected LED (colour + pattern + meaning when the
+box reports it), firmware, the box's own self-report (KOTA lines), start-up
+milestones, a findings tree (root causes; their consequences as children;
+titles only) and a wrapped detail pane for the selected finding.
+"""
+
+from __future__ import annotations
+
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QBrush, QColor
+from PySide6.QtWidgets import (
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QListWidget,
+    QListWidgetItem,
+    QPushButton,
+    QSizePolicy,
+    QSplitter,
+    QTextBrowser,
+    QTreeWidget,
+    QTreeWidgetItem,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ..diag.engine import LED, Finding, Report, Severity
+
+SEV_COLOR = {
+    Severity.CRITICAL: "#b03a2e",
+    Severity.ERROR: "#d9534f",
+    Severity.WARNING: "#c77c02",
+    Severity.INFO: "#2e6da4",
+}
+# verdict banner (background, text) by verdict severity; None = healthy
+BANNER = {
+    Severity.CRITICAL: ("#f6d5d1", "#7b1e14"),
+    Severity.ERROR: ("#f9dedc", "#8a2019"),
+    Severity.WARNING: ("#fdebc8", "#6b4400"),
+    None: ("#d8f0dd", "#1b5e2a"),
+}
+_KEY = Qt.ItemDataRole.UserRole
+BOX_STATE = {"ok": ("#1b7a33", "✔"), "warn": ("#c77c02", "!"), "bad": ("#b03a2e", "✖"), "info": ("#2e6da4", "i")}
+
+
+def _heading(text: str) -> QLabel:
+    lbl = QLabel(text)
+    f = lbl.font()
+    f.setBold(True)
+    lbl.setFont(f)
+    return lbl
+
+
+def _esc(s: str) -> str:
+    return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+class DiagnosticsPanel(QWidget):
+    def __init__(self, parent: QWidget | None = None):
+        super().__init__(parent)
+        self.setMinimumWidth(380)
+
+        self.verdict = QLabel(wordWrap=True)
+        self.verdict.setMargin(10)
+        vf = self.verdict.font()
+        vf.setPointSize(vf.pointSize() + 2)
+        vf.setBold(True)
+        self.verdict.setFont(vf)
+
+        self.led_swatch = QLabel()
+        self.led_swatch.setFixedSize(22, 22)
+        self.led_text = QLabel(wordWrap=True)
+        led_row = QHBoxLayout()
+        led_row.addWidget(self.led_swatch, 0, Qt.AlignmentFlag.AlignTop)
+        led_row.addWidget(self.led_text, 1)
+
+        self.firmware = QLabel(wordWrap=True)
+        self.firmware.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+
+        self.box_title = _heading("Box self-report (KOTA lines)")
+        self.box = QLabel(wordWrap=True)
+        self.box.setTextFormat(Qt.TextFormat.RichText)
+        self.box.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+
+        self.milestones = QListWidget()
+        self.milestones.setFrameShape(QFrame.Shape.NoFrame)
+        self.milestones.setSelectionMode(QListWidget.SelectionMode.NoSelection)
+        self.milestones.setSizePolicy(QSizePolicy.Policy.Preferred, QSizePolicy.Policy.Maximum)
+
+        self.tree = QTreeWidget()
+        self.tree.setHeaderHidden(True)
+        self.tree.setIndentation(16)
+        self.tree.setTextElideMode(Qt.TextElideMode.ElideRight)
+        self.detail = QTextBrowser()
+        self.detail.setOpenExternalLinks(False)
+        findings = QSplitter(Qt.Orientation.Vertical)
+        findings.addWidget(self.tree)
+        findings.addWidget(self.detail)
+        findings.setSizes([220, 260])
+
+        lay = QVBoxLayout(self)
+        lay.setContentsMargins(4, 0, 0, 0)
+        lay.addWidget(self.verdict)
+        lay.addWidget(_heading("Status LED should be"))
+        lay.addLayout(led_row)
+        lay.addWidget(_heading("Firmware"))
+        lay.addWidget(self.firmware)
+        self.qr_btn = QPushButton("Matter pairing QR code...")
+        self.qr_btn.setToolTip("Show the box's Matter QR code on screen to scan with the phone")
+        lay.addWidget(self.qr_btn, 0, Qt.AlignmentFlag.AlignLeft)
+        lay.addWidget(self.box_title)
+        lay.addWidget(self.box)
+        lay.addWidget(_heading("Start-up progress (current boot)"))
+        lay.addWidget(self.milestones)
+        lay.addWidget(_heading("Findings - root causes first; click one for details"))
+        lay.addWidget(findings, 1)
+
+        self._findings: dict[str, Finding] = {}
+        self._selected: str | None = None
+        # key -> expanded, chosen by the user; survives the rebuild on refresh.
+        self._expanded: dict[str, bool] = {}
+        self.tree.currentItemChanged.connect(self._on_select)
+        self.tree.itemCollapsed.connect(lambda it: self._remember(it, False))
+        self.tree.itemExpanded.connect(lambda it: self._remember(it, True))
+
+    # ------------------------------------------------------------------
+    def show_report(self, r: Report) -> None:
+        bg, fg = BANNER.get(r.verdict_severity, BANNER[Severity.WARNING])
+        if r.lines == 0:
+            bg, fg = "#e6e6e6", "#333333"
+        self.verdict.setText(r.verdict)
+        self.verdict.setStyleSheet(f"QLabel {{ background:{bg}; color:{fg}; border-radius:6px; }}")
+
+        name, colour = LED[r.led]
+        self.led_swatch.setStyleSheet(
+            f"QLabel {{ background:{colour}; border:1px solid #777; border-radius:11px; }}")
+        ask = "" if r.led == "UNKNOWN" else " - <i>check it matches the box</i>"
+        pattern = f", {_esc(r.led_pattern)}" if r.led_pattern else ""
+        meaning = f" = {_esc(r.led_meaning)}" if r.led_meaning else ""
+        source = " <small style='color:#1b7a33'>(reported by the box)</small>" if r.led_exact else ""
+        reason = f"<br><small style='color:#666'>from: {_esc(r.led_reason)}</small>" if r.led_reason else ""
+        self.led_text.setText(f"<b>{name}{pattern}</b>{meaning}{source}{ask}{reason}")
+
+        fw = r.firmware
+        sd = {True: "reads Wi-Fi settings from the SD card",
+              False: "does not read Wi-Fi settings from the SD card",
+              None: "Wi-Fi-from-SD support unknown"}
+        self.firmware.setText(f"{_esc(fw.describe())}<br><small>{sd[fw.supports_sd_wifi]}</small>")
+
+        self.box_title.setVisible(bool(r.box))
+        self.box.setVisible(bool(r.box))
+        self.box.setText("<table cellspacing='0' cellpadding='1'>" + "".join(
+            f"<tr><td style='color:{BOX_STATE[st][0]}'><b>{BOX_STATE[st][1]}</b>&nbsp;</td>"
+            f"<td><b>{_esc(topic)}</b>&nbsp;</td><td>{_esc(text)}</td></tr>"
+            for topic, text, st in r.box) + "</table>")
+
+        self.milestones.clear()
+        for _, label, t in r.milestones:
+            done = t is not None
+            it = QListWidgetItem(("✔  " if done else "○  ") + label
+                                 + (f"   ({t / 1000:.1f} s)" if done else ""))
+            it.setForeground(QBrush(QColor("#1b7a33" if done else "#8a8a8a")))
+            self.milestones.addItem(it)
+        rows = min(max(self.milestones.count(), 1), 15)
+        self.milestones.setFixedHeight(rows * max(self.milestones.sizeHintForRow(0), 16) + 6)
+
+        self._fill_tree(r)
+
+    def _fill_tree(self, r: Report) -> None:
+        self.tree.blockSignals(True)
+        self.tree.clear()
+        self._findings = {}
+        if not r.roots:
+            it = QTreeWidgetItem(["No problems detected in the log so far."])
+            it.setForeground(0, QBrush(QColor("#1b7a33")))
+            self.tree.addTopLevelItem(it)
+        for rc in r.roots:
+            top = self._item(rc.finding, bold=True)
+            self.tree.addTopLevelItem(top)
+            for c in rc.consequences:
+                top.addChild(self._item(c, prefix="↳ "))
+            top.setExpanded(self._expanded.get(rc.finding.key, True))
+        for title, key, items in (("Seen in earlier boots only", "grp:earlier", r.earlier),
+                                  ("Resolved during this session", "grp:resolved", r.resolved)):
+            if not items:
+                continue
+            grp = QTreeWidgetItem([f"{title} ({len(items)})"])
+            grp.setData(0, _KEY, key)
+            grp.setForeground(0, QBrush(QColor("#666666")))
+            self.tree.addTopLevelItem(grp)
+            for f in items:
+                grp.addChild(self._item(f, prefix="✔ " if key == "grp:resolved" else ""))
+            grp.setExpanded(self._expanded.get(key, False))
+        # Keep the selection across refreshes; default to the top root cause.
+        target = self._selected if self._selected in self._findings else (
+            r.roots[0].finding.key if r.roots else None)
+        self.tree.blockSignals(False)
+        self._select(target)
+
+    def _remember(self, item: QTreeWidgetItem, expanded: bool) -> None:
+        if key := item.data(0, _KEY):
+            self._expanded[key] = expanded
+
+    def _item(self, f: Finding, prefix: str = "", bold: bool = False) -> QTreeWidgetItem:
+        it = QTreeWidgetItem([f"{prefix}[{f.severity.label}]  {f.title}"])
+        it.setData(0, _KEY, f.key)
+        it.setForeground(0, QBrush(QColor(SEV_COLOR.get(f.severity, "#333333"))))
+        it.setToolTip(0, f.title)
+        if bold:
+            font = it.font(0)
+            font.setBold(True)
+            it.setFont(0, font)
+        self._findings[f.key] = f
+        return it
+
+    def _select(self, key: str | None) -> None:
+        if key is None:
+            self.detail.setHtml("<p style='color:#666'>Nothing to show yet.</p>")
+            return
+        match = self.tree.findItems("*", Qt.MatchFlag.MatchWildcard | Qt.MatchFlag.MatchRecursive)
+        for it in match:
+            if it.data(0, _KEY) == key:
+                self.tree.setCurrentItem(it)
+                return
+
+    def _on_select(self, cur: QTreeWidgetItem | None, _prev) -> None:
+        key = cur.data(0, _KEY) if cur else None
+        f = self._findings.get(key or "")
+        if f is None:
+            return
+        self._selected = key
+        self.detail.setHtml(_detail_html(f))
+
+
+def _detail_html(f: Finding) -> str:
+    colour = SEV_COLOR.get(f.severity, "#333")
+    actions = "".join(f"<li>{_esc(a)}</li>" for a in f.actions)
+    seen = _esc(f.seen_text())
+    evidence = "<br>".join(_esc(e) for e in f.evidence)
+    codes = "".join(f"<li><b>{_esc(eid)}</b>" + (f" - {_esc(a)}" if a else "") + "</li>"
+                    for eid, a in f.error_ids.items())
+    return (
+        f"<h3 style='color:{colour}; margin:0'>{_esc(f.title)}</h3>"
+        f"<p><b>What it means:</b> {_esc(f.meaning)}</p>"
+        + (f"<p><b>What to do:</b></p><ol>{actions}</ol>" if actions else "")
+        + (f"<p><b>Firmware error codes</b> (error_ids.csv):</p><ul>{codes}</ul>" if codes else "")
+        + f"<p style='color:#666'>{seen}</p>"
+        + (f"<p style='color:#555; font-family:Consolas,Menlo,monospace; font-size:9pt'>{evidence}</p>"
+           if evidence else "")
+    )

kota_tech/ui/flash_tab.py

@@ -1,398 +1,364 @@
-"""Flash firmware tab: factory image or imported developer builds; App-only by default."""
-
-from __future__ import annotations
-
-import datetime as dt
-import tempfile
-from pathlib import Path
-
-from PySide6.QtCore import QObject, Qt, QTimer, Signal
-from PySide6.QtWidgets import (
-    QButtonGroup,
-    QCheckBox,
-    QFileDialog,
-    QInputDialog,
-    QComboBox,
-    QGroupBox,
-    QHBoxLayout,
-    QLabel,
-    QMessageBox,
-    QPlainTextEdit,
-    QProgressBar,
-    QPushButton,
-    QRadioButton,
-    QVBoxLayout,
-    QWidget,
-)
-
-from ..core.session import SESSIONS_DIR
-from ..flash.image import FirmwareImage, FirmwareLibrary, ImageError, bundled_images
-from ..flash.plan import Mode, build_plan
-from ..flash.runner import FlashRunner, Result
-from ..serialio.ports import PortInfo, list_serial_ports
-
-BACKUP_DIR = SESSIONS_DIR.parent / "backups"
-VERIFY_TIMEOUT_MS = 45_000
-
-HELP = (
-    "<b>If flashing cannot connect:</b> use a data-capable USB cable directly on the laptop, close "
-    "other programs using the port, then retry. Last resort (case must be opened): hold <b>BOOT</b>, "
-    "press and release <b>RESET</b>, release <b>BOOT</b>, and press Start again."
-)
-
-
-class _Bridge(QObject):
-    step = Signal(int, str)
-    progress = Signal(int)
-    output = Signal(str)
-    done = Signal(object)
-
-
-class FlashTab(QWidget):
-    def __init__(self, serial_tab, parent: QWidget | None = None):
-        super().__init__(parent)
-        self.serial_tab = serial_tab
-        self._images: list[FirmwareImage] = []
-        self._ports: list[PortInfo] = []   # before any signal can call _update()
-        self._runner: FlashRunner | None = None
-        self._port: PortInfo | None = None
-        self._image: FirmwareImage | None = None
-
-        # 1. box
-        box = QGroupBox("1. Sensorbox")
-        self.port_combo = QComboBox(minimumWidth=360)
-        refresh = QPushButton("Refresh")
-        refresh.clicked.connect(self.refresh_ports)
-        self.box_fw = QLabel(wordWrap=True)
-        bl = QVBoxLayout(box)
-        row = QHBoxLayout()
-        row.addWidget(self.port_combo)
-        row.addWidget(refresh)
-        row.addStretch(1)
-        bl.addLayout(row)
-        bl.addWidget(self.box_fw)
-
-        # 2. firmware
-        fwbox = QGroupBox("2. Firmware")
-        self.image_combo = QComboBox(minimumWidth=360)
-        self.import_btn = QPushButton("Import firmware file...")
-        self.import_btn.setToolTip("Add a newer build the firmware team sent you (.bin)")
-        self.import_btn.clicked.connect(self._import)
-        self.remove_btn = QPushButton("Remove from list")
-        self.remove_btn.clicked.connect(self._remove)
-        self.image_info = QLabel(wordWrap=True)
-        self.image_info.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
-        fl = QVBoxLayout(fwbox)
-        fl.addWidget(self.image_combo)
-        brow = QHBoxLayout()
-        brow.addWidget(self.import_btn)
-        brow.addWidget(self.remove_btn)
-        brow.addStretch(1)
-        fl.addLayout(brow)
-        fl.addWidget(self.image_info)
-        self._library = FirmwareLibrary()
-        self._reference: FirmwareImage | None = None
-        self._problems: list[str] = []
-
-        # 3. mode
-        modebox = QGroupBox("3. What to write")
-        self.rb_app = QRadioButton("App only  (recommended for repairs)")
-        self.rb_full = QRadioButton("Full factory image  (new or completely wiped boards)")
-        self.mode_group = QButtonGroup(self)
-        self.mode_group.addButton(self.rb_app)
-        self.mode_group.addButton(self.rb_full)
-        self.rb_app.setChecked(True)
-        app_note = QLabel("Replaces the firmware only. Keeps the Matter pairing, the OTA registration and the "
-                          "settings stored on the box.", wordWrap=True)
-        full_note = QLabel("Writes everything like the factory. <b>Erases the Matter pairing and the OTA "
-                           "registration</b> - the box must be paired again afterwards.", wordWrap=True)
-        for n in (app_note, full_note):
-            n.setContentsMargins(24, 0, 0, 6)
-            n.setStyleSheet("color:#555")
-        self.confirm_full = QCheckBox("I understand the pairing and OTA registration will be erased")
-        self.backup = QCheckBox("Back up the box's complete flash first (8 MB, about 3 minutes)")
-        ml = QVBoxLayout(modebox)
-        for w in (self.rb_app, app_note, self.rb_full, full_note, self.confirm_full, self.backup):
-            ml.addWidget(w)
-
-        # 4. run
-        runbox = QGroupBox("4. Flash")
-        self.plan_label = QLabel(wordWrap=True)
-        self.start_btn = QPushButton("Start flashing")
-        self.start_btn.setMinimumHeight(36)
-        self.start_btn.clicked.connect(self._start)
-        self.step_label = QLabel()
-        self.bar = QProgressBar()
-        self.result = QLabel(wordWrap=True)
-        self.result.setMargin(8)
-        self.result.setTextFormat(Qt.TextFormat.RichText)
-        self.details_btn = QPushButton("Show esptool output")
-        self.details_btn.setCheckable(True)
-        self.output = QPlainTextEdit(readOnly=True)
-        self.output.setVisible(False)
-        self.details_btn.toggled.connect(self.output.setVisible)
-        rl = QVBoxLayout(runbox)
-        for w in (self.plan_label, self.start_btn, self.step_label, self.bar, self.result, self.details_btn, self.output):
-            rl.addWidget(w)
-        help_lbl = QLabel(HELP, wordWrap=True)
-        help_lbl.setStyleSheet("color:#555")
-        rl.addWidget(help_lbl)
-        rl.addStretch(1)   # keep the run column packed at the top
-
-        left = QVBoxLayout()
-        for w in (box, fwbox, modebox):
-            left.addWidget(w)
-        left.addStretch(1)
-        lay = QHBoxLayout(self)
-        lay.addLayout(left, 1)
-        lay.addWidget(runbox, 1)
-
-        self._bridge = _Bridge()
-        self._bridge.step.connect(self._on_step)
-        self._bridge.progress.connect(self.bar.setValue)
-        self._bridge.output.connect(self.output.appendPlainText)
-        self._bridge.done.connect(self._on_done)
-        self._verify_timer = QTimer(self, interval=500)
-        self._verify_timer.timeout.connect(self._check_verify)
-
-        for sig in (self.rb_app.toggled, self.confirm_full.toggled, self.backup.toggled):
-            sig.connect(self._update)
-        self.rb_full.toggled.connect(lambda on: self.backup.setChecked(on))  # backup default on for Full
-        self.image_combo.currentIndexChanged.connect(self._update)
-        self.port_combo.currentIndexChanged.connect(self._update)
-
-        self._load_images()
-        self.refresh_ports()
-        self._show_result("", None)
-
-    # ------------------------------------------------------------ setup
-    def _load_images(self, select_sha: str | None = None) -> None:
-        self._problems = []
-        try:
-            bundled = bundled_images()
-        except ImageError as exc:
-            bundled = []
-            self._problems.append(f"bundled image: {exc}")
-        factory = [i for i in bundled if not i.is_developer]
-        self._reference = factory[0] if factory else None
-        dev, problems = self._library.images(self._reference)
-        dev += [i for i in bundled if i.is_developer]
-        self._problems += problems
-        # Newest developer builds first, then the factory image.
-        dev.sort(key=lambda i: i.app.built_at or dt.datetime.min, reverse=True)
-        self._images = dev + factory
-        self.image_combo.blockSignals(True)
-        self.image_combo.clear()
-        for img in self._images:
-            self.image_combo.addItem(img.label())
-        if not self._images:
-            self.image_combo.addItem("No firmware image available - import one")
-        idx = next((i for i, im in enumerate(self._images) if im.sha256 == select_sha), None)
-        if idx is None:
-            idx = len(dev) if factory else 0          # default: the factory image
-        self.image_combo.setCurrentIndex(idx)
-        self.image_combo.blockSignals(False)
-        self._update()
-
-    def _import(self) -> None:
-        path, _ = QFileDialog.getOpenFileName(self, "Import firmware from the firmware team", str(Path.home()),
-                                              "Firmware (*.bin);;All files (*)")
-        if not path:
-            return
-        built_by, ok = QInputDialog.getText(self, "Who built this firmware?",
-                                            "Name of the developer who built this image (shown next to it):")
-        if not ok:
-            return
-        try:
-            img = self._library.import_file(Path(path), self._reference, built_by=built_by)
-        except (ImageError, OSError) as exc:
-            QMessageBox.warning(self, "Cannot use this file", f"This file cannot be flashed:\n\n{exc}")
-            return
-        self._load_images(select_sha=img.sha256)
-        kind = "complete image" if img.kind == "merged" else "app only"
-        QMessageBox.information(
-            self, "Firmware imported",
-            f"{img.name}\nbuild {img.app.elf_sha[:9]}, {kind}\n\nFile fingerprint (SHA-256):\n{img.sha256}\n\n"
-            "Compare it with the fingerprint the firmware team sent you before flashing.")
-
-    def _remove(self) -> None:
-        img = self._selected_image()
-        if img and img.is_developer and QMessageBox.question(
-                self, "Remove firmware", f"Remove {img.name} from this computer?") == QMessageBox.StandardButton.Yes:
-            self._library.remove(img.sha256)
-            self._load_images()
-
-    def refresh_ports(self) -> None:
-        current = self.port_combo.currentData()
-        self._ports = list_serial_ports()
-        self.port_combo.clear()
-        for p in self._ports:
-            self.port_combo.addItem(p.label, p.device)
-        if not self._ports:
-            self.port_combo.addItem("No sensorbox found - check USB cable and power switch", None)
-        self.port_combo.setCurrentIndex(max(self.port_combo.findData(current), 0))
-        self._update()
-
-    def showEvent(self, event):  # noqa: N802 - refresh when the tab is opened
-        self.refresh_ports()
-        super().showEvent(event)
-
-    # ------------------------------------------------------------ state
-    def _selected_image(self) -> FirmwareImage | None:
-        i = self.image_combo.currentIndex()
-        return self._images[i] if 0 <= i < len(self._images) else None
-
-    def _selected_port(self) -> PortInfo | None:
-        dev = self.port_combo.currentData()
-        return next((p for p in self._ports if p.device == dev), None)
-
-    def _update(self) -> None:
-        img = self._selected_image()
-        info = ""
-        if img:
-            a = img.app
-            origin = ("<b>Factory image</b> (bundled with the tool)" if not img.is_developer else
-                      "<b style='color:#c77c02'>Developer build</b> - only flash builds you received "
-                      "from the firmware team")
-            kind = "complete image (bootloader + layout + app)" if img.kind == "merged" else "app only"
-            info = (f"{origin}<br>{a.project} {a.version}, built {a.built}, ESP-IDF {a.idf}, {kind}<br>"
-                    f"<small>build {a.elf_sha[:9]} &middot; file SHA-256 {img.sha256[:16]}... "
-                    f"&middot; checksum OK</small>" + (f"<br><small>{img.notes}</small>" if img.notes else ""))
-        if self._problems:
-            info += ("<br><span style='color:#b03a2e'><b>Not offered:</b> "
-                     + "; ".join(self._problems) + "</span>")
-        self.image_info.setText(info)
-        self.remove_btn.setEnabled(bool(img and img.is_developer) and self._runner is None)
-        # An app-only file has no bootloader/layout: Full mode is impossible.
-        full_ok = bool(img and img.kind == "merged")
-        self.rb_full.setEnabled(full_ok and self._runner is None)
-        if not full_ok and self.rb_full.isChecked():
-            self.rb_app.setChecked(True)
-        self.box_fw.setText(self._box_text(img))
-
-        self.confirm_full.setVisible(self.rb_full.isChecked())
-        ok = bool(img and self._selected_port() and self._runner is None
-                  and (self.rb_app.isChecked() or self.confirm_full.isChecked()))
-        self.start_btn.setEnabled(ok)
-        if img and self._selected_port():
-            mode = Mode.APP_ONLY if self.rb_app.isChecked() else Mode.FULL
-            steps = ["Back up the complete flash (~3 min)"] if self.backup.isChecked() else []
-            if mode == Mode.APP_ONLY:
-                steps += ["Check the box has the same partition layout", "Write the firmware app (~20 s)"]
-            else:
-                steps += ["Write the complete factory image (~25 s)"]
-            steps += ["Restart the box and verify the new firmware boots"]
-            self.plan_label.setText("<b>Plan:</b><ol>" + "".join(f"<li>{s}</li>" for s in steps) + "</ol>")
-        else:
-            self.plan_label.setText("Select a sensorbox and a firmware image.")
-
-    def _box_text(self, img: FirmwareImage | None) -> str:
-        fw = self.serial_tab.engine.firmware
-        if not fw.elf_sha:
-            return "Firmware on the box: unknown - connect in the Serial monitor and press Reset & capture to see it."
-        msg = f"Box currently runs: {fw.describe()}" + (f", built {fw.built}" if fw.built else "")
-        if not img:
-            return msg
-        if fw.elf_sha.startswith(img.app.elf_sha[:9]) or img.app.elf_sha.startswith(fw.elf_sha):
-            return msg + "<br><i>It already has this firmware. Re-flash only if you suspect the firmware is damaged.</i>"
-        box_built, img_built = _parse_built(fw.built), img.app.built_at
-        if box_built and img_built and img_built > box_built:
-            return msg + f"<br><b style='color:#2e6da4'>The selected firmware is newer (built {img.app.built}).</b>"
-        if box_built and img_built and img_built < box_built:
-            return msg + ("<br><b style='color:#c77c02'>The selected firmware is OLDER than the box's (the box was "
-                          "probably updated over OTA). The box updates itself again once online.</b>")
-        return msg + "<br><b style='color:#c77c02'>The box runs a different build.</b>"
-
-    # ------------------------------------------------------------ flash
-    def _start(self) -> None:
-        img, port = self._selected_image(), self._selected_port()
-        if not img or not port:
-            return
-        mode = Mode.APP_ONLY if self.rb_app.isChecked() else Mode.FULL
-        what = ("the firmware app (pairing and settings are kept)" if mode == Mode.APP_ONLY
-                else "the COMPLETE factory image (pairing and OTA registration are erased)")
-        if QMessageBox.question(self, "Flash firmware",
-                                f"Write {what}\n\nImage: {img.name}\nBox: {port.label}\n\n"
-                                "Keep the box powered and the USB cable connected until it finishes.",
-                                QMessageBox.StandardButton.Ok | QMessageBox.StandardButton.Cancel
-                                ) != QMessageBox.StandardButton.Ok:
-            return
-        backup_to = None
-        if self.backup.isChecked():
-            BACKUP_DIR.mkdir(parents=True, exist_ok=True)
-            stamp = dt.datetime.now().strftime("%Y%m%d_%H%M%S")
-            backup_to = BACKUP_DIR / f"{(port.mac or port.device).replace(':', '')}_{stamp}.bin"
-        plan = build_plan(img, mode, port.device, Path(tempfile.mkdtemp(prefix="kota_flash_")), backup_to)
-
-        self._port, self._image = port, img
-        self.serial_tab.release_port()          # esptool needs the port exclusively
-        self.output.clear()
-        self.output.appendPlainText("\n".join(plan.summary()))
-        self._show_result("", None)
-        self._runner = FlashRunner(plan, self._bridge.step.emit, self._bridge.progress.emit,
-                                   self._bridge.output.emit, self._bridge.done.emit)
-        self._set_busy(True)
-        self._runner.start()
-
-    def _set_busy(self, busy: bool) -> None:
-        for w in (self.port_combo, self.image_combo, self.rb_app, self.backup, self.confirm_full, self.import_btn):
-            w.setEnabled(not busy)
-        self._update()
-
-    def _on_step(self, i: int, title: str) -> None:
-        n = len(self._runner.plan.steps) if self._runner else 0
-        self.step_label.setText(f"Step {i + 1} of {n + 1}: {title}")
-
-    def _on_done(self, res: Result) -> None:
-        self._runner = None
-        if not res.ok:
-            self._set_busy(False)
-            self.step_label.setText("Stopped.")
-            hint = f"<p>{res.hint}</p>" if res.hint else ""
-            self._show_result(f"<b>Flashing failed.</b> {res.message}{hint}", "error")
-            self.details_btn.setChecked(True)
-            return
-        self.step_label.setText("Final step: restarting the box and checking which firmware it boots...")
-        self.bar.setValue(0)
-        self._show_result("Firmware written. Waiting for the box to start...", "info")
-        self.serial_tab.connect_port(self._port, capture=True)
-        self._verify_ms = 0
-        self._verify_timer.start()
-
-    def _check_verify(self) -> None:
-        self._verify_ms += self._verify_timer.interval()
-        self.bar.setValue(min(100, int(100 * self._verify_ms / VERIFY_TIMEOUT_MS)))
-        fw = self.serial_tab.engine.firmware
-        want = self._image.app.elf_sha[:9]
-        done = fw.elf_sha is not None and fw.elf_sha.startswith(want)
-        if done or self._verify_ms >= VERIFY_TIMEOUT_MS:
-            self._verify_timer.stop()
-            self._set_busy(False)
-            self.bar.setValue(100)
-            if done:
-                self.step_label.setText("Done.")
-                self._show_result(f"<b>Success.</b> The box boots the new firmware (build {want}). "
-                                  "Check the Diagnosis panel in the Serial monitor.", "ok")
-            else:
-                seen = fw.elf_sha[:9] if fw.elf_sha else "no boot seen"
-                self._show_result(f"<b>Written, but not verified.</b> Expected build {want}, saw: {seen}. "
-                                  "Open the Serial monitor and press Reset & capture.", "warning")
-
-    def _show_result(self, html: str, kind: str | None) -> None:
-        colours = {"ok": ("#2e9e44", "#e3f4e7"), "info": ("#2e6da4", "#e3edf7"),
-                   "warning": ("#c77c02", "#fdf0d6"), "error": ("#d9534f", "#f9e0df")}
-        self.result.setVisible(bool(html))
-        if html:
-            border, bg = colours[kind or "info"]
-            self.result.setStyleSheet(f"QLabel {{ border:2px solid {border}; background:{bg}; border-radius:6px; }}")
-            self.result.setText(html)
-
-
-def _parse_built(s: str | None) -> dt.datetime | None:
-    """'Jun 29 2026 11:03:32' (app_init "Compile time") -> datetime."""
-    if not s:
-        return None
-    try:
-        return dt.datetime.strptime(" ".join(s.split()), "%b %d %Y %H:%M:%S")
-    except ValueError:
-        return None
+"""Flash firmware tab: only the .bin files in the tool's firmware/ folder,
+chosen by their compile date; App-only by default."""
+
+from __future__ import annotations
+
+import datetime as dt
+import tempfile
+from pathlib import Path
+
+from PySide6.QtCore import QObject, Qt, QTimer, QUrl, Signal
+from PySide6.QtGui import QDesktopServices
+from PySide6.QtWidgets import (
+    QButtonGroup,
+    QCheckBox,
+    QComboBox,
+    QGroupBox,
+    QHBoxLayout,
+    QLabel,
+    QMessageBox,
+    QPlainTextEdit,
+    QProgressBar,
+    QPushButton,
+    QRadioButton,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ..core.session import SESSIONS_DIR
+from ..diag.firmware import local_build, register_local_build, same_build
+from ..flash.image import FIRMWARE_DIR, FirmwareImage, folder_images
+from ..flash.plan import Mode, build_plan
+from ..flash.runner import FlashRunner, Result
+from ..serialio.ports import PortInfo, list_serial_ports
+
+BACKUP_DIR = SESSIONS_DIR.parent / "backups"
+VERIFY_TIMEOUT_MS = 45_000
+
+HELP = (
+    "<b>If flashing cannot connect:</b> use a data-capable USB cable directly on the laptop, close "
+    "other programs using the port, then retry. Last resort (case must be opened): hold <b>BOOT</b>, "
+    "press and release <b>RESET</b>, release <b>BOOT</b>, and press Start again."
+)
+
+
+class _Bridge(QObject):
+    step = Signal(int, str)
+    progress = Signal(int)
+    output = Signal(str)
+    done = Signal(object)
+
+
+class FlashTab(QWidget):
+    def __init__(self, serial_tab, parent: QWidget | None = None):
+        super().__init__(parent)
+        self.serial_tab = serial_tab
+        self._images: list[FirmwareImage] = []
+        self._ports: list[PortInfo] = []   # before any signal can call _update()
+        self._runner: FlashRunner | None = None
+        self._port: PortInfo | None = None
+        self._image: FirmwareImage | None = None
+
+        # 1. box
+        box = QGroupBox("1. Sensorbox")
+        self.port_combo = QComboBox(minimumWidth=360)
+        refresh = QPushButton("Refresh")
+        refresh.clicked.connect(self.refresh_ports)
+        self.box_fw = QLabel(wordWrap=True)
+        bl = QVBoxLayout(box)
+        row = QHBoxLayout()
+        row.addWidget(self.port_combo)
+        row.addWidget(refresh)
+        row.addStretch(1)
+        bl.addLayout(row)
+        bl.addWidget(self.box_fw)
+
+        # 2. firmware - only files in the tool's firmware/ folder
+        fwbox = QGroupBox("2. Firmware (by compile date)")
+        self.image_combo = QComboBox(minimumWidth=360)
+        self.image_combo.setToolTip(f"Firmware files in {FIRMWARE_DIR}")
+        self.reload_btn = QPushButton("Refresh list")
+        self.reload_btn.setToolTip("Read the firmware folder again (after the firmware team added a file)")
+        self.reload_btn.clicked.connect(lambda: self._load_images(self._selected_sha()))
+        self.folder_btn = QPushButton("Open firmware folder")
+        self.folder_btn.clicked.connect(
+            lambda: QDesktopServices.openUrl(QUrl.fromLocalFile(str(FIRMWARE_DIR))))
+        self.image_info = QLabel(wordWrap=True)
+        self.image_info.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+        fl = QVBoxLayout(fwbox)
+        fl.addWidget(self.image_combo)
+        brow = QHBoxLayout()
+        brow.addWidget(self.reload_btn)
+        brow.addWidget(self.folder_btn)
+        brow.addStretch(1)
+        fl.addLayout(brow)
+        fl.addWidget(self.image_info)
+        self._problems: list[str] = []
+
+        # 3. mode
+        modebox = QGroupBox("3. What to write")
+        self.rb_app = QRadioButton("App only  (recommended for repairs)")
+        self.rb_full = QRadioButton("Full image  (new or completely wiped boards)")
+        self.mode_group = QButtonGroup(self)
+        self.mode_group.addButton(self.rb_app)
+        self.mode_group.addButton(self.rb_full)
+        self.rb_app.setChecked(True)
+        app_note = QLabel("Replaces the firmware only. Keeps the Matter pairing, the OTA registration and the "
+                          "settings stored on the box.", wordWrap=True)
+        full_note = QLabel("Writes everything like the factory. <b>Erases the Matter pairing and the OTA "
+                           "registration</b> - the box must be paired again afterwards.", wordWrap=True)
+        for n in (app_note, full_note):
+            n.setContentsMargins(24, 0, 0, 6)
+            n.setStyleSheet("color:#555")
+        self.confirm_full = QCheckBox("I understand the pairing and OTA registration will be erased")
+        self.backup = QCheckBox("Back up the box's complete flash first (8 MB, about 3 minutes)")
+        ml = QVBoxLayout(modebox)
+        for w in (self.rb_app, app_note, self.rb_full, full_note, self.confirm_full, self.backup):
+            ml.addWidget(w)
+
+        # 4. run
+        runbox = QGroupBox("4. Flash")
+        self.plan_label = QLabel(wordWrap=True)
+        self.start_btn = QPushButton("Start flashing")
+        self.start_btn.setMinimumHeight(36)
+        self.start_btn.clicked.connect(self._start)
+        self.step_label = QLabel()
+        self.bar = QProgressBar()
+        self.result = QLabel(wordWrap=True)
+        self.result.setMargin(8)
+        self.result.setTextFormat(Qt.TextFormat.RichText)
+        self.details_btn = QPushButton("Show esptool output")
+        self.details_btn.setCheckable(True)
+        self.output = QPlainTextEdit(readOnly=True)
+        self.output.setVisible(False)
+        self.details_btn.toggled.connect(self.output.setVisible)
+        rl = QVBoxLayout(runbox)
+        for w in (self.plan_label, self.start_btn, self.step_label, self.bar, self.result, self.details_btn, self.output):
+            rl.addWidget(w)
+        help_lbl = QLabel(HELP, wordWrap=True)
+        help_lbl.setStyleSheet("color:#555")
+        rl.addWidget(help_lbl)
+        rl.addStretch(1)   # keep the run column packed at the top
+
+        left = QVBoxLayout()
+        for w in (box, fwbox, modebox):
+            left.addWidget(w)
+        left.addStretch(1)
+        lay = QHBoxLayout(self)
+        lay.addLayout(left, 1)
+        lay.addWidget(runbox, 1)
+
+        self._bridge = _Bridge()
+        self._bridge.step.connect(self._on_step)
+        self._bridge.progress.connect(self.bar.setValue)
+        self._bridge.output.connect(self.output.appendPlainText)
+        self._bridge.done.connect(self._on_done)
+        self._verify_timer = QTimer(self, interval=500)
+        self._verify_timer.timeout.connect(self._check_verify)
+
+        for sig in (self.rb_app.toggled, self.confirm_full.toggled, self.backup.toggled):
+            sig.connect(self._update)
+        self.rb_full.toggled.connect(lambda on: self.backup.setChecked(on))  # backup default on for Full
+        self.image_combo.currentIndexChanged.connect(self._update)
+        self.port_combo.currentIndexChanged.connect(self._update)
+
+        self._load_images()
+        self.refresh_ports()
+        self._show_result("", None)
+
+    # ------------------------------------------------------------ setup
+    def _load_images(self, select_sha: str | None = None) -> None:
+        self._images, self._problems = folder_images()
+        for img in self._images:     # lets the Serial monitor show a box build's compile date
+            register_local_build(img.app.elf_sha, img.app.version, img.app.built, img.name)
+        self.image_combo.blockSignals(True)
+        self.image_combo.clear()
+        for img in self._images:
+            self.image_combo.addItem(img.label())
+        if not self._images:
+            self.image_combo.addItem("No firmware file in the firmware folder")
+        idx = next((i for i, im in enumerate(self._images) if im.sha256 == select_sha), 0)
+        self.image_combo.setCurrentIndex(idx)             # default: newest compile date
+        self.image_combo.blockSignals(False)
+        self._update()
+
+    def _selected_sha(self) -> str | None:
+        img = self._selected_image()
+        return img.sha256 if img else None
+
+    def refresh_ports(self) -> None:
+        current = self.port_combo.currentData()
+        self._ports = list_serial_ports()
+        self.port_combo.clear()
+        for p in self._ports:
+            self.port_combo.addItem(p.label, p.device)
+        if not self._ports:
+            self.port_combo.addItem("No sensorbox found - check USB cable and power switch", None)
+        self.port_combo.setCurrentIndex(max(self.port_combo.findData(current), 0))
+        self._update()
+
+    def showEvent(self, event):  # noqa: N802 - refresh when the tab is opened
+        self.refresh_ports()
+        super().showEvent(event)
+
+    # ------------------------------------------------------------ state
+    def _selected_image(self) -> FirmwareImage | None:
+        i = self.image_combo.currentIndex()
+        return self._images[i] if 0 <= i < len(self._images) else None
+
+    def _selected_port(self) -> PortInfo | None:
+        dev = self.port_combo.currentData()
+        return next((p for p in self._ports if p.device == dev), None)
+
+    def _update(self) -> None:
+        img = self._selected_image()
+        info = ""
+        if img:
+            a = img.app
+            kind = "complete image (bootloader + layout + app)" if img.kind == "merged" else "app only"
+            info = (f"<b>Compiled {a.built}</b> &middot; {a.project} v{a.version}, ESP-IDF {a.idf}, {kind}<br>"
+                    f"<small>file firmware/{img.name} &middot; build {a.elf_sha[:8]} &middot; "
+                    f"SHA-256 {img.sha256[:16]}... &middot; checksum OK</small>")
+        else:
+            info = (f"Put the firmware .bin file from the firmware team into<br><code>{FIRMWARE_DIR}</code><br>"
+                    "and press <b>Refresh list</b>. Only files in this folder can be flashed.")
+        if self._problems:
+            info += ("<br><span style='color:#b03a2e'><b>Not offered:</b> "
+                     + "; ".join(self._problems) + "</span>")
+        self.image_info.setText(info)
+        # An app-only file has no bootloader/layout: Full mode is impossible.
+        full_ok = bool(img and img.kind == "merged")
+        self.rb_full.setEnabled(full_ok and self._runner is None)
+        if not full_ok and self.rb_full.isChecked():
+            self.rb_app.setChecked(True)
+        self.box_fw.setText(self._box_text(img))
+
+        self.confirm_full.setVisible(self.rb_full.isChecked())
+        ok = bool(img and self._selected_port() and self._runner is None
+                  and (self.rb_app.isChecked() or self.confirm_full.isChecked()))
+        self.start_btn.setEnabled(ok)
+        if img and self._selected_port():
+            mode = Mode.APP_ONLY if self.rb_app.isChecked() else Mode.FULL
+            steps = ["Back up the complete flash (~3 min)"] if self.backup.isChecked() else []
+            if mode == Mode.APP_ONLY:
+                steps += ["Check the box has the same partition layout", "Write the firmware app (~20 s)"]
+            else:
+                steps += ["Write the complete image (~25 s)"]
+            steps += ["Restart the box and verify the new firmware boots"]
+            self.plan_label.setText("<b>Plan:</b><ol>" + "".join(f"<li>{s}</li>" for s in steps) + "</ol>")
+        else:
+            self.plan_label.setText("Select a sensorbox and a firmware image.")
+
+    def _box_text(self, img: FirmwareImage | None) -> str:
+        fw = self.serial_tab.engine.firmware
+        if not fw.elf_sha:
+            return "Firmware on the box: unknown - connect in the Serial monitor and press Reset & capture to see it."
+        msg = f"Box currently runs: {fw.describe()}"
+        if not img:
+            return msg
+        if same_build(fw.elf_sha, img.app.elf_sha):
+            return msg + "<br><i>It already has this firmware. Re-flash only if you suspect the firmware is damaged.</i>"
+        local = local_build(fw.elf_sha)
+        box_built, img_built = _parse_built(fw.built or (local[1] if local else None)), img.app.built_at
+        if box_built and img_built and img_built > box_built:
+            return msg + f"<br><b style='color:#2e6da4'>The selected firmware is newer (built {img.app.built}).</b>"
+        if box_built and img_built and img_built < box_built:
+            return msg + ("<br><b style='color:#c77c02'>The selected firmware is OLDER than the box's (the box was "
+                          "probably updated over OTA). The box updates itself again once online.</b>")
+        return msg + "<br><b style='color:#c77c02'>The box runs a different build.</b>"
+
+    # ------------------------------------------------------------ flash
+    def _start(self) -> None:
+        img, port = self._selected_image(), self._selected_port()
+        if not img or not port:
+            return
+        mode = Mode.APP_ONLY if self.rb_app.isChecked() else Mode.FULL
+        what = ("the firmware app (pairing and settings are kept)" if mode == Mode.APP_ONLY
+                else "the COMPLETE image (pairing and OTA registration are erased)")
+        if QMessageBox.question(self, "Flash firmware",
+                                f"Write {what}\n\nFirmware: v{img.app.version}, compiled {img.app.built}\n"
+                                f"File: firmware/{img.name}\nBox: {port.label}\n\n"
+                                "Keep the box powered and the USB cable connected until it finishes.",
+                                QMessageBox.StandardButton.Ok | QMessageBox.StandardButton.Cancel
+                                ) != QMessageBox.StandardButton.Ok:
+            return
+        backup_to = None
+        if self.backup.isChecked():
+            BACKUP_DIR.mkdir(parents=True, exist_ok=True)
+            stamp = dt.datetime.now().strftime("%Y%m%d_%H%M%S")
+            backup_to = BACKUP_DIR / f"{(port.mac or port.device).replace(':', '')}_{stamp}.bin"
+        plan = build_plan(img, mode, port.device, Path(tempfile.mkdtemp(prefix="kota_flash_")), backup_to)
+
+        self._port, self._image = port, img
+        self.serial_tab.release_port()          # esptool needs the port exclusively
+        self.output.clear()
+        self.output.appendPlainText("\n".join(plan.summary()))
+        self._show_result("", None)
+        self._runner = FlashRunner(plan, self._bridge.step.emit, self._bridge.progress.emit,
+                                   self._bridge.output.emit, self._bridge.done.emit)
+        self._set_busy(True)
+        self._runner.start()
+
+    def _set_busy(self, busy: bool) -> None:
+        for w in (self.port_combo, self.image_combo, self.rb_app, self.backup, self.confirm_full,
+                  self.reload_btn):
+            w.setEnabled(not busy)
+        self._update()
+
+    def _on_step(self, i: int, title: str) -> None:
+        n = len(self._runner.plan.steps) if self._runner else 0
+        self.step_label.setText(f"Step {i + 1} of {n + 1}: {title}")
+
+    def _on_done(self, res: Result) -> None:
+        self._runner = None
+        if not res.ok:
+            self._set_busy(False)
+            self.step_label.setText("Stopped.")
+            hint = f"<p>{res.hint}</p>" if res.hint else ""
+            self._show_result(f"<b>Flashing failed.</b> {res.message}{hint}", "error")
+            self.details_btn.setChecked(True)
+            return
+        self.step_label.setText("Final step: restarting the box and checking which firmware it boots...")
+        self.bar.setValue(0)
+        self._show_result("Firmware written. Waiting for the box to start...", "info")
+        self.serial_tab.connect_port(self._port, capture=True)
+        self._verify_ms = 0
+        self._verify_timer.start()
+
+    def _check_verify(self) -> None:
+        self._verify_ms += self._verify_timer.interval()
+        self.bar.setValue(min(100, int(100 * self._verify_ms / VERIFY_TIMEOUT_MS)))
+        fw = self.serial_tab.engine.firmware
+        want = self._image.app.elf_sha[:8]
+        done = same_build(fw.elf_sha, self._image.app.elf_sha)
+        if done or self._verify_ms >= VERIFY_TIMEOUT_MS:
+            self._verify_timer.stop()
+            self._set_busy(False)
+            self.bar.setValue(100)
+            if done:
+                self.step_label.setText("Done.")
+                self._show_result(f"<b>Success.</b> The box boots the new firmware (build {want}). "
+                                  "Check the Diagnosis panel in the Serial monitor.", "ok")
+            else:
+                seen = fw.elf_sha[:8] if fw.elf_sha else "no boot seen"
+                self._show_result(f"<b>Written, but not verified.</b> Expected build {want}, saw: {seen}. "
+                                  "Open the Serial monitor and press Reset & capture.", "warning")
+
+    def _show_result(self, html: str, kind: str | None) -> None:
+        colours = {"ok": ("#2e9e44", "#e3f4e7"), "info": ("#2e6da4", "#e3edf7"),
+                   "warning": ("#c77c02", "#fdf0d6"), "error": ("#d9534f", "#f9e0df")}
+        self.result.setVisible(bool(html))
+        if html:
+            border, bg = colours[kind or "info"]
+            self.result.setStyleSheet(f"QLabel {{ border:2px solid {border}; background:{bg}; border-radius:6px; }}")
+            self.result.setText(html)
+
+
+def _parse_built(s: str | None) -> dt.datetime | None:
+    """'Jun 29 2026 11:03:32' (app_init "Compile time") -> datetime."""
+    if not s:
+        return None
+    try:
+        return dt.datetime.strptime(" ".join(s.split()), "%b %d %Y %H:%M:%S")
+    except ValueError:
+        return None

kota_tech/ui/main_window.py

@@ -1,415 +1,424 @@
-from __future__ import annotations
-
-from pathlib import Path
-
-from PySide6.QtCore import QCoreApplication, QObject, QSettings, Qt, QTimer, QUrl, Signal
-from PySide6.QtGui import QColor, QDesktopServices, QFont, QGuiApplication, QTextCharFormat, QTextCursor
-from PySide6.QtWidgets import (
-    QCheckBox,
-    QComboBox,
-    QFileDialog,
-    QHBoxLayout,
-    QInputDialog,
-    QLabel,
-    QMainWindow,
-    QMessageBox,
-    QPlainTextEdit,
-    QPushButton,
-    QSplitter,
-    QTabWidget,
-    QTextBrowser,
-    QVBoxLayout,
-    QWidget,
-)
-
-from .. import __version__
-from ..core.logfile import read_log_file
-from ..core.logline import LineKind, LogLine, host_event
-from ..core.session import SessionLog
-from ..diag.engine import DiagnosticsEngine
-from ..diag.guides import GuideRunner
-from ..serialio.manager import SerialManager, State
-from ..serialio.ports import PortInfo, list_serial_ports
-from ..matter.payload import SetupPayload, payload_from_log
-from ..service.report import DEFAULT_BASE, normalize_mac, report_url
-from .cheatsheet import cheatsheet_html
-from .diag_panel import DiagnosticsPanel
-from .flash_tab import FlashTab
-from .matter_qr import MatterQrDialog
-from .guide_panel import GuidePanel
-from .sd_tab import SdTab
-
-MAX_LINES = 20000
-LEVEL_FILTERS = {"All lines": None, "Warnings + errors": {"W", "E"}, "Errors only": {"E"}}
-COLORS = {
-    "E": "#ff6b6b",
-    "W": "#f5c451",
-    "I": "#d4d4d4",
-    LineKind.BOOT: "#6fc3ff",
-    LineKind.RESET: "#6fc3ff",
-    LineKind.PANIC: "#ff4dd2",
-    LineKind.HOST: "#7ee07e",
-    LineKind.RAW: "#a8a8a8",
-}
-
-
-class _Bridge(QObject):
-    """Marshals SerialManager callbacks (reader thread) onto the UI thread."""
-
-    line = Signal(object)
-    state = Signal(object, str)
-
-
-class SerialTab(QWidget):
-    def __init__(self, parent: QWidget | None = None):
-        super().__init__(parent)
-        self._bridge = _Bridge()
-        self._bridge.line.connect(self._on_line)
-        self._bridge.state.connect(self._on_state)
-        self._manager = SerialManager(self._bridge.line.emit, self._bridge.state.emit)
-        self._session = SessionLog()
-        self._ports: list[PortInfo] = []
-        self._counts = {"E": 0, "W": 0, "boots": 0}
-        self._engine = DiagnosticsEngine()
-        self._diag_dirty = True
-        self._runner = GuideRunner(self._engine, on_action=self._guide_action, on_log=self._guide_log)
-
-        # --- controls
-        self.port_combo = QComboBox(minimumWidth=320)
-        self.all_ports = QCheckBox("Show all ports")
-        self.refresh_btn = QPushButton("Refresh")
-        self.connect_btn = QPushButton("Connect")
-        self.reset_btn = QPushButton("Reset && capture")
-        self.reset_btn.setToolTip("Reboot the sensorbox and record the log from the first boot line")
-        self.filter_combo = QComboBox()
-        self.filter_combo.addItems(LEVEL_FILTERS)
-        self.clear_btn = QPushButton("Clear view")
-        self.save_btn = QPushButton("Save view as...")
-        self.folder_btn = QPushButton("Open logs folder")
-        self.analyze_btn = QPushButton("Analyze log file...")
-        self.analyze_btn.setToolTip("Load a saved session log or serial capture and diagnose it")
-        self.copy_btn = QPushButton("Copy report")
-        self.copy_btn.setToolTip("Copy the diagnosis as text (e.g. to send to the firmware team)")
-        self.service_btn = QPushButton("Service report...")
-        self.service_btn.setToolTip("Open this box's page in the KOTA service system with the diagnosis "
-                                    "filled in; check it and press Save there")
-        self._settings = QSettings("KOTA", "TechnicianTool")
-        self.auto_service = QCheckBox("Open service report on disconnect")
-        self.auto_service.setChecked(self._settings.value("service/auto", False, type=bool))
-        self.auto_service.toggled.connect(lambda on: self._settings.setValue("service/auto", on))
-        self._active_port: PortInfo | None = None
-
-        row1 = QHBoxLayout()
-        for w in (QLabel("Port:"), self.port_combo, self.all_ports, self.refresh_btn,
-                  self.connect_btn, self.reset_btn):
-            row1.addWidget(w)
-        row1.addStretch(1)
-        row2 = QHBoxLayout()
-        for w in (QLabel("Show:"), self.filter_combo, self.clear_btn, self.save_btn, self.folder_btn,
-                  self.analyze_btn, self.copy_btn, self.service_btn, self.auto_service):
-            row2.addWidget(w)
-        row2.addStretch(1)
-
-        self.view = QPlainTextEdit(readOnly=True)
-        self.view.setMaximumBlockCount(MAX_LINES)
-        self.view.setLineWrapMode(QPlainTextEdit.LineWrapMode.NoWrap)
-        mono = QFont("Menlo" if QFont("Menlo").exactMatch() else "Consolas")
-        mono.setStyleHint(QFont.StyleHint.Monospace)
-        mono.setPointSize(10)
-        self.view.setFont(mono)
-        self.view.setStyleSheet("QPlainTextEdit { background:#1e1e1e; color:#d4d4d4; }")
-
-        self.diag = DiagnosticsPanel()
-        self.guide = GuidePanel(self._runner, self._engine, matter_payload=self.matter_payload)
-        self.side_tabs = QTabWidget()
-        self.side_tabs.addTab(self.diag, "Diagnosis")
-        self.side_tabs.addTab(self.guide, "Guided troubleshooting")
-        split = QSplitter(Qt.Orientation.Horizontal)
-        split.addWidget(self.view)
-        split.addWidget(self.side_tabs)
-        split.setStretchFactor(0, 3)
-        split.setStretchFactor(1, 2)
-        split.setSizes([700, 480])
-
-        self.status = QLabel()
-        layout = QVBoxLayout(self)
-        layout.addLayout(row1)
-        layout.addLayout(row2)
-        layout.addWidget(split, 1)
-        layout.addWidget(self.status)
-
-        # --- wiring
-        self.refresh_btn.clicked.connect(self.refresh_ports)
-        self.all_ports.toggled.connect(self.refresh_ports)
-        self.connect_btn.clicked.connect(self._toggle_connect)
-        self.reset_btn.clicked.connect(self._manager.reset_board)
-        self.clear_btn.clicked.connect(self.view.clear)
-        self.save_btn.clicked.connect(self._save_view)
-        self.folder_btn.clicked.connect(self._open_folder)
-        self.analyze_btn.clicked.connect(self._analyze_file)
-        self.copy_btn.clicked.connect(self._copy_report)
-        self.service_btn.clicked.connect(lambda: self._open_service_report(auto=False))
-        self.diag.qr_btn.clicked.connect(lambda: MatterQrDialog(self.matter_payload(), self).exec())
-
-        # Report refresh is throttled; lines can arrive at >100/s.
-        self._diag_timer = QTimer(self, interval=400)
-        self._diag_timer.timeout.connect(self._refresh_diag)
-        self._diag_timer.start()
-
-        # Auto-detect a box being plugged in while idle.
-        self._poll = QTimer(self, interval=2000)
-        self._poll.timeout.connect(self._auto_refresh)
-        self._poll.start()
-
-        self.refresh_ports()
-        self._on_state(State.DISCONNECTED, "")
-
-    # ---- ports -------------------------------------------------------
-    def refresh_ports(self) -> None:
-        current = self.port_combo.currentData()
-        self._ports = list_serial_ports(include_all=self.all_ports.isChecked())
-        self.port_combo.clear()
-        for p in self._ports:
-            self.port_combo.addItem(p.label, p.device)
-        if not self._ports:
-            self.port_combo.addItem("No sensorbox found - check USB cable and power switch", None)
-        idx = self.port_combo.findData(current)
-        self.port_combo.setCurrentIndex(max(idx, 0))
-
-    def _auto_refresh(self) -> None:
-        if self._manager.is_running:
-            return
-        devices = [p.device for p in list_serial_ports(self.all_ports.isChecked())]
-        if devices != [p.device for p in self._ports]:
-            self.refresh_ports()
-
-    def _selected_port(self) -> PortInfo | None:
-        dev = self.port_combo.currentData()
-        return next((p for p in self._ports if p.device == dev), None)
-
-    # ---- connection --------------------------------------------------
-    def _toggle_connect(self) -> None:
-        if self._manager.is_running:
-            # Session file is closed in _on_state(DISCONNECTED), after the
-            # reader thread's final queued lines have been written.
-            self._manager.disconnect()
-            return
-        port = self._selected_port()
-        if port is None:
-            return
-        self._connect(port)
-
-    def _connect(self, port: PortInfo) -> None:
-        self._counts = {"E": 0, "W": 0, "boots": 0}
-        self._engine.reset()
-        self._runner.cancel()
-        self._diag_dirty = True
-        self._session.start(port.mac or port.device)
-        self._active_port = port
-        self._manager.connect(port)
-
-    def matter_payload(self) -> SetupPayload:
-        """Pairing payload from this box's log (VID/PID/discriminator), defaults otherwise."""
-        return payload_from_log([self._engine.matter_advert] if self._engine.matter_advert else [])
-
-    # ---- service system -------------------------------------------------
-    def _service_base(self) -> str:
-        return str(self._settings.value("service/base", DEFAULT_BASE))
-
-    def _open_service_report(self, auto: bool) -> None:
-        mac = normalize_mac(self._engine.mac or (self._active_port.mac if self._active_port else "") or "")
-        if len(mac) != 12:
-            if not auto:
-                QMessageBox.information(self, "Service report", "The box's MAC address is not known yet. "
-                                        "Connect to the box and press Reset & capture first.")
-            return
-        url = report_url(mac, self._engine.report(), self._service_base())
-        QDesktopServices.openUrl(QUrl(url))
-        # Log that it happened, not the report itself (it is already in the session log).
-        self._guide_log(f"service report for {mac} opened in the browser - check it and press Save there")
-
-    # ---- hand-off with the flash tab ------------------------------------
-    @property
-    def engine(self) -> DiagnosticsEngine:
-        return self._engine
-
-    def release_port(self) -> None:
-        """Stop monitoring so esptool can open the port exclusively."""
-        if self._manager.is_running:
-            self._no_auto_service = True        # a flash hand-off is not the end of a session
-            self._manager.disconnect()          # joins the reader thread
-            QCoreApplication.processEvents()    # deliver its queued final lines/state now
-            self._no_auto_service = False
-
-    def connect_port(self, port: PortInfo, capture: bool = True) -> None:
-        """Monitor `port`; with capture, restart the box once connected to record its boot."""
-        self.release_port()
-        idx = self.port_combo.findData(port.device)
-        if idx < 0:
-            self.port_combo.addItem(port.label, port.device)
-            self._ports.append(port)
-            idx = self.port_combo.count() - 1
-        self.port_combo.setCurrentIndex(idx)
-        self._reset_on_connect = capture
-        self._connect(port)
-
-    def _on_state(self, state: State, detail: str) -> None:
-        running = state != State.DISCONNECTED
-        if not running and self._manager.is_running:
-            return  # stale event from a session that was already replaced
-        if state == State.CONNECTED and getattr(self, "_reset_on_connect", False):
-            self._reset_on_connect = False
-            QTimer.singleShot(300, self._manager.reset_board)
-        if not running and self._session.path is not None:
-            self._session.write_report(self._engine.report().to_text())
-            if (self.auto_service.isChecked() and self._engine.lines
-                    and not getattr(self, "_no_auto_service", False)):
-                self._open_service_report(auto=True)
-            self._session.stop()
-        self.connect_btn.setText("Disconnect" if running else "Connect")
-        self.reset_btn.setEnabled(state == State.CONNECTED)
-        self.port_combo.setEnabled(not running)
-        self.all_ports.setEnabled(not running)
-        self.refresh_btn.setEnabled(not running)
-        # Offline analysis would mix with the live session; disconnect first.
-        self.analyze_btn.setEnabled(not running)
-        self._state_text = f"{state.value}" + (f" ({detail})" if detail else "")
-        self._update_status()
-
-    def _update_status(self) -> None:
-        sess = f"   |   Session log: {self._session.path}" if self._session.path else ""
-        c = self._counts
-        self.status.setText(
-            f"{getattr(self, '_state_text', '')}   |   boots seen: {c['boots']}   "
-            f"errors: {c['E']}   warnings: {c['W']}{sess}"
-        )
-
-    # ---- lines -------------------------------------------------------
-    def _on_line(self, line: LogLine) -> None:
-        self._session.write(line)
-        self._engine.feed(line)
-        self._runner.feed(line)
-        self._diag_dirty = True
-        if line.kind == LineKind.BOOT:
-            self._counts["boots"] += 1
-        if line.level in ("E", "W"):
-            self._counts[line.level] += 1
-        self._update_status()
-
-        allowed = LEVEL_FILTERS[self.filter_combo.currentText()]
-        if allowed is not None and line.kind != LineKind.HOST and not (
-            line.level in allowed or line.kind in (LineKind.PANIC, LineKind.BOOT, LineKind.RESET)
-        ):
-            return
-        self._append(line)
-
-    def _append(self, line: LogLine) -> None:
-        sb = self.view.verticalScrollBar()
-        at_bottom = sb.value() >= sb.maximum() - 4
-        fmt = QTextCharFormat()
-        fmt.setForeground(QColor(COLORS.get(line.level) or COLORS.get(line.kind, "#d4d4d4")))
-        if line.kind in (LineKind.PANIC, LineKind.BOOT, LineKind.HOST):
-            fmt.setFontWeight(QFont.Weight.Bold)
-        cur = QTextCursor(self.view.document())
-        cur.movePosition(QTextCursor.MoveOperation.End)
-        if not self.view.document().isEmpty():
-            cur.insertBlock()
-        cur.insertText(line.text, fmt)
-        if at_bottom:
-            sb.setValue(sb.maximum())
-
-    # ---- diagnostics -------------------------------------------------
-    def _refresh_diag(self) -> None:
-        if self._diag_dirty:
-            self._diag_dirty = False
-            self.diag.show_report(self._engine.report())
-        self.guide.refresh()   # countdowns and timeouts need a steady tick
-
-    # ---- guided troubleshooting hooks ------------------------------------
-    def _guide_action(self, action: str) -> bool:
-        if action == "reset" and self._manager.state == State.CONNECTED:
-            self._manager.reset_board()
-            return True
-        return False
-
-    def _guide_log(self, text: str) -> None:
-        # Technician answers go into the session log and the log view.
-        line = host_event(text)
-        self._session.write(line)
-        self._append(line)
-        self._diag_dirty = True
-
-    def _copy_report(self) -> None:
-        QGuiApplication.clipboard().setText(self._engine.report().to_text())
-
-    def _analyze_file(self) -> None:
-        path, _ = QFileDialog.getOpenFileName(
-            self, "Analyze log file", str(self._session.root), "Logs (*.log *.txt);;All files (*)")
-        if not path:
-            return
-        lines = read_log_file(Path(path))
-        self.view.clear()
-        self._engine.reset()
-        self._runner.cancel()
-        self._counts = {"E": 0, "W": 0, "boots": 0}
-        for line in lines:
-            self._engine.feed(line)
-            if line.kind == LineKind.BOOT:
-                self._counts["boots"] += 1
-            if line.level in ("E", "W"):
-                self._counts[line.level] += 1
-            self._append(line)
-        self._state_text = f"Analyzed file: {Path(path).name} ({len(lines)} lines)"
-        self._update_status()
-        self._diag_dirty = True
-        self._refresh_diag()
-
-    # ---- misc --------------------------------------------------------
-    def _save_view(self) -> None:
-        path, _ = QFileDialog.getSaveFileName(self, "Save log view", "sensorbox_log.txt", "Text (*.txt)")
-        if path:
-            with open(path, "w", encoding="utf-8") as fh:
-                fh.write(self.view.toPlainText())
-
-    def _open_folder(self) -> None:
-        self._session.root.mkdir(parents=True, exist_ok=True)
-        QDesktopServices.openUrl(QUrl.fromLocalFile(str(self._session.root)))
-
-    def shutdown(self) -> None:
-        self._manager.disconnect()
-        self._session.stop()
-
-
-class MainWindow(QMainWindow):
-    def __init__(self):
-        super().__init__()
-        self.setWindowTitle(f"KOTA Sensorbox Technician Tool  v{__version__}")
-        self.resize(1200, 800)
-        tabs = QTabWidget()
-        guide = QTextBrowser(openExternalLinks=True)
-        guide.setHtml(cheatsheet_html())
-        self.serial_tab = SerialTab()
-        self.flash_tab = FlashTab(self.serial_tab)
-        tabs.addTab(guide, "Quick start")
-        tabs.addTab(self.serial_tab, "Serial monitor")
-        tabs.addTab(self.flash_tab, "Flash firmware")
-        self.sd_tab = SdTab(self.serial_tab)
-        tabs.addTab(self.sd_tab, "SD card")
-        self.setCentralWidget(tabs)
-        settings_menu = self.menuBar().addMenu("Settings")
-        settings_menu.addAction("Service system address...", self._edit_service_base)
-
-    def _edit_service_base(self) -> None:
-        st = self.serial_tab
-        text, ok = QInputDialog.getText(
-            self, "Service system address",
-            "Address of the KOTA service system (the box MAC is added at the end):",
-            text=st._service_base())
-        if ok and text.strip().startswith(("https://", "http://")):
-            st._settings.setValue("service/base", text.strip())
-        elif ok:
-            QMessageBox.warning(self, "Service system address", "The address must start with https://")
-
-    def closeEvent(self, event):  # noqa: N802 (Qt naming)
-        self.serial_tab.shutdown()
-        super().closeEvent(event)
+from __future__ import annotations
+
+from pathlib import Path
+
+from PySide6.QtCore import QCoreApplication, QObject, QSettings, Qt, QTimer, QUrl, Signal
+from PySide6.QtGui import QColor, QDesktopServices, QFont, QGuiApplication, QTextCharFormat, QTextCursor
+from PySide6.QtWidgets import (
+    QCheckBox,
+    QComboBox,
+    QFileDialog,
+    QHBoxLayout,
+    QInputDialog,
+    QLabel,
+    QMainWindow,
+    QMessageBox,
+    QPlainTextEdit,
+    QPushButton,
+    QSplitter,
+    QTabWidget,
+    QTextBrowser,
+    QVBoxLayout,
+    QWidget,
+)
+
+from .. import __version__
+from ..core.logfile import read_log_file
+from ..core.logline import LineKind, LogLine, host_event
+from ..core.session import SessionLog
+from ..diag.engine import DiagnosticsEngine
+from ..diag.guides import GuideRunner
+from ..serialio.manager import SerialManager, State
+from ..serialio.ports import PortInfo, list_serial_ports
+from ..matter.payload import SetupPayload, payload_from_log
+from ..service.report import DEFAULT_BASE, normalize_mac, report_url
+from .cheatsheet import cheatsheet_html
+from .diag_panel import DiagnosticsPanel
+from .flash_tab import FlashTab
+from .matter_qr import MatterQrDialog
+from .guide_panel import GuidePanel
+from .sd_tab import SdTab
+
+MAX_LINES = 20000
+# "KOTA" = the firmware's structured diagnostic lines (1.0.16+) plus errors.
+LEVEL_FILTERS = {"All lines": None, "KOTA diagnostics + errors": "KOTA",
+                 "Warnings + errors": {"W", "E"}, "Errors only": {"E"}}
+COLORS = {
+    "E": "#ff6b6b",
+    "W": "#f5c451",
+    "I": "#d4d4d4",
+    LineKind.BOOT: "#6fc3ff",
+    LineKind.RESET: "#6fc3ff",
+    LineKind.PANIC: "#ff4dd2",
+    LineKind.HOST: "#7ee07e",
+    LineKind.KOTA: "#5fd7e8",
+    LineKind.RAW: "#a8a8a8",
+}
+
+
+class _Bridge(QObject):
+    """Marshals SerialManager callbacks (reader thread) onto the UI thread."""
+
+    line = Signal(object)
+    state = Signal(object, str)
+
+
+class SerialTab(QWidget):
+    def __init__(self, parent: QWidget | None = None):
+        super().__init__(parent)
+        self._bridge = _Bridge()
+        self._bridge.line.connect(self._on_line)
+        self._bridge.state.connect(self._on_state)
+        self._manager = SerialManager(self._bridge.line.emit, self._bridge.state.emit)
+        self._session = SessionLog()
+        self._ports: list[PortInfo] = []
+        self._counts = {"E": 0, "W": 0, "boots": 0}
+        self._engine = DiagnosticsEngine()
+        self._diag_dirty = True
+        self._runner = GuideRunner(self._engine, on_action=self._guide_action, on_log=self._guide_log)
+
+        # --- controls
+        self.port_combo = QComboBox(minimumWidth=320)
+        self.all_ports = QCheckBox("Show all ports")
+        self.refresh_btn = QPushButton("Refresh")
+        self.connect_btn = QPushButton("Connect")
+        self.reset_btn = QPushButton("Reset && capture")
+        self.reset_btn.setToolTip("Reboot the sensorbox and record the log from the first boot line")
+        self.filter_combo = QComboBox()
+        self.filter_combo.addItems(LEVEL_FILTERS)
+        self.clear_btn = QPushButton("Clear view")
+        self.save_btn = QPushButton("Save view as...")
+        self.folder_btn = QPushButton("Open logs folder")
+        self.analyze_btn = QPushButton("Analyze log file...")
+        self.analyze_btn.setToolTip("Load a saved session log or serial capture and diagnose it")
+        self.copy_btn = QPushButton("Copy report")
+        self.copy_btn.setToolTip("Copy the diagnosis as text (e.g. to send to the firmware team)")
+        self.service_btn = QPushButton("Service report...")
+        self.service_btn.setToolTip("Open this box's page in the KOTA service system with the diagnosis "
+                                    "filled in; check it and press Save there")
+        self._settings = QSettings("KOTA", "TechnicianTool")
+        self.auto_service = QCheckBox("Open service report on disconnect")
+        self.auto_service.setChecked(self._settings.value("service/auto", False, type=bool))
+        self.auto_service.toggled.connect(lambda on: self._settings.setValue("service/auto", on))
+        self._active_port: PortInfo | None = None
+
+        row1 = QHBoxLayout()
+        for w in (QLabel("Port:"), self.port_combo, self.all_ports, self.refresh_btn,
+                  self.connect_btn, self.reset_btn):
+            row1.addWidget(w)
+        row1.addStretch(1)
+        row2 = QHBoxLayout()
+        for w in (QLabel("Show:"), self.filter_combo, self.clear_btn, self.save_btn, self.folder_btn,
+                  self.analyze_btn, self.copy_btn, self.service_btn, self.auto_service):
+            row2.addWidget(w)
+        row2.addStretch(1)
+
+        self.view = QPlainTextEdit(readOnly=True)
+        self.view.setMaximumBlockCount(MAX_LINES)
+        self.view.setLineWrapMode(QPlainTextEdit.LineWrapMode.NoWrap)
+        mono = QFont("Menlo" if QFont("Menlo").exactMatch() else "Consolas")
+        mono.setStyleHint(QFont.StyleHint.Monospace)
+        mono.setPointSize(10)
+        self.view.setFont(mono)
+        self.view.setStyleSheet("QPlainTextEdit { background:#1e1e1e; color:#d4d4d4; }")
+
+        self.diag = DiagnosticsPanel()
+        self.guide = GuidePanel(self._runner, self._engine, matter_payload=self.matter_payload)
+        self.side_tabs = QTabWidget()
+        self.side_tabs.addTab(self.diag, "Diagnosis")
+        self.side_tabs.addTab(self.guide, "Guided troubleshooting")
+        split = QSplitter(Qt.Orientation.Horizontal)
+        split.addWidget(self.view)
+        split.addWidget(self.side_tabs)
+        split.setStretchFactor(0, 3)
+        split.setStretchFactor(1, 2)
+        split.setSizes([700, 480])
+
+        self.status = QLabel()
+        layout = QVBoxLayout(self)
+        layout.addLayout(row1)
+        layout.addLayout(row2)
+        layout.addWidget(split, 1)
+        layout.addWidget(self.status)
+
+        # --- wiring
+        self.refresh_btn.clicked.connect(self.refresh_ports)
+        self.all_ports.toggled.connect(self.refresh_ports)
+        self.connect_btn.clicked.connect(self._toggle_connect)
+        self.reset_btn.clicked.connect(self._manager.reset_board)
+        self.clear_btn.clicked.connect(self.view.clear)
+        self.save_btn.clicked.connect(self._save_view)
+        self.folder_btn.clicked.connect(self._open_folder)
+        self.analyze_btn.clicked.connect(self._analyze_file)
+        self.copy_btn.clicked.connect(self._copy_report)
+        self.service_btn.clicked.connect(lambda: self._open_service_report(auto=False))
+        self.diag.qr_btn.clicked.connect(lambda: MatterQrDialog(self.matter_payload(), self).exec())
+
+        # Report refresh is throttled; lines can arrive at >100/s.
+        self._diag_timer = QTimer(self, interval=400)
+        self._diag_timer.timeout.connect(self._refresh_diag)
+        self._diag_timer.start()
+
+        # Auto-detect a box being plugged in while idle.
+        self._poll = QTimer(self, interval=2000)
+        self._poll.timeout.connect(self._auto_refresh)
+        self._poll.start()
+
+        self.refresh_ports()
+        self._on_state(State.DISCONNECTED, "")
+
+    # ---- ports -------------------------------------------------------
+    def refresh_ports(self) -> None:
+        current = self.port_combo.currentData()
+        self._ports = list_serial_ports(include_all=self.all_ports.isChecked())
+        self.port_combo.clear()
+        for p in self._ports:
+            self.port_combo.addItem(p.label, p.device)
+        if not self._ports:
+            self.port_combo.addItem("No sensorbox found - check USB cable and power switch", None)
+        idx = self.port_combo.findData(current)
+        self.port_combo.setCurrentIndex(max(idx, 0))
+
+    def _auto_refresh(self) -> None:
+        if self._manager.is_running:
+            return
+        devices = [p.device for p in list_serial_ports(self.all_ports.isChecked())]
+        if devices != [p.device for p in self._ports]:
+            self.refresh_ports()
+
+    def _selected_port(self) -> PortInfo | None:
+        dev = self.port_combo.currentData()
+        return next((p for p in self._ports if p.device == dev), None)
+
+    # ---- connection --------------------------------------------------
+    def _toggle_connect(self) -> None:
+        if self._manager.is_running:
+            # Session file is closed in _on_state(DISCONNECTED), after the
+            # reader thread's final queued lines have been written.
+            self._manager.disconnect()
+            return
+        port = self._selected_port()
+        if port is None:
+            return
+        self._connect(port)
+
+    def _connect(self, port: PortInfo) -> None:
+        self._counts = {"E": 0, "W": 0, "boots": 0}
+        self._engine.reset()
+        self._runner.cancel()
+        self._diag_dirty = True
+        self._session.start(port.mac or port.device)
+        self._active_port = port
+        self._manager.connect(port)
+
+    def matter_payload(self) -> SetupPayload:
+        """Pairing payload reported by this box (KOTA: matter), from its log, or the defaults."""
+        return payload_from_log([self._engine.matter_advert] if self._engine.matter_advert else [],
+                                self._engine.matter_qr, self._engine.matter_manual)
+
+    # ---- service system -------------------------------------------------
+    def _service_base(self) -> str:
+        return str(self._settings.value("service/base", DEFAULT_BASE))
+
+    def _open_service_report(self, auto: bool) -> None:
+        mac = normalize_mac(self._engine.mac or (self._active_port.mac if self._active_port else "") or "")
+        if len(mac) != 12:
+            if not auto:
+                QMessageBox.information(self, "Service report", "The box's MAC address is not known yet. "
+                                        "Connect to the box and press Reset & capture first.")
+            return
+        url = report_url(mac, self._engine.report(), self._service_base())
+        QDesktopServices.openUrl(QUrl(url))
+        # Log that it happened, not the report itself (it is already in the session log).
+        self._guide_log(f"service report for {mac} opened in the browser - check it and press Save there")
+
+    # ---- hand-off with the flash tab ------------------------------------
+    @property
+    def engine(self) -> DiagnosticsEngine:
+        return self._engine
+
+    def release_port(self) -> None:
+        """Stop monitoring so esptool can open the port exclusively."""
+        if self._manager.is_running:
+            self._no_auto_service = True        # a flash hand-off is not the end of a session
+            self._manager.disconnect()          # joins the reader thread
+            QCoreApplication.processEvents()    # deliver its queued final lines/state now
+            self._no_auto_service = False
+
+    def connect_port(self, port: PortInfo, capture: bool = True) -> None:
+        """Monitor `port`; with capture, restart the box once connected to record its boot."""
+        self.release_port()
+        idx = self.port_combo.findData(port.device)
+        if idx < 0:
+            self.port_combo.addItem(port.label, port.device)
+            self._ports.append(port)
+            idx = self.port_combo.count() - 1
+        self.port_combo.setCurrentIndex(idx)
+        self._reset_on_connect = capture
+        self._connect(port)
+
+    def _on_state(self, state: State, detail: str) -> None:
+        running = state != State.DISCONNECTED
+        if not running and self._manager.is_running:
+            return  # stale event from a session that was already replaced
+        if state == State.CONNECTED and getattr(self, "_reset_on_connect", False):
+            self._reset_on_connect = False
+            QTimer.singleShot(300, self._manager.reset_board)
+        if not running and self._session.path is not None:
+            self._session.write_report(self._engine.report().to_text())
+            if (self.auto_service.isChecked() and self._engine.lines
+                    and not getattr(self, "_no_auto_service", False)):
+                self._open_service_report(auto=True)
+            self._session.stop()
+        self.connect_btn.setText("Disconnect" if running else "Connect")
+        self.reset_btn.setEnabled(state == State.CONNECTED)
+        self.port_combo.setEnabled(not running)
+        self.all_ports.setEnabled(not running)
+        self.refresh_btn.setEnabled(not running)
+        # Offline analysis would mix with the live session; disconnect first.
+        self.analyze_btn.setEnabled(not running)
+        self._state_text = f"{state.value}" + (f" ({detail})" if detail else "")
+        self._update_status()
+
+    def _update_status(self) -> None:
+        sess = f"   |   Session log: {self._session.path}" if self._session.path else ""
+        c = self._counts
+        self.status.setText(
+            f"{getattr(self, '_state_text', '')}   |   boots seen: {c['boots']}   "
+            f"errors: {c['E']}   warnings: {c['W']}{sess}"
+        )
+
+    # ---- lines -------------------------------------------------------
+    def _on_line(self, line: LogLine) -> None:
+        self._session.write(line)
+        self._engine.feed(line)
+        self._runner.feed(line)
+        self._diag_dirty = True
+        if line.kind == LineKind.BOOT:
+            self._counts["boots"] += 1
+        if line.level in ("E", "W"):
+            self._counts[line.level] += 1
+        self._update_status()
+
+        if self._visible(line):
+            self._append(line)
+
+    def _visible(self, line: LogLine) -> bool:
+        allowed = LEVEL_FILTERS[self.filter_combo.currentText()]
+        if allowed is None or line.kind in (LineKind.HOST, LineKind.PANIC, LineKind.BOOT, LineKind.RESET):
+            return True
+        if allowed == "KOTA":
+            return line.kind == LineKind.KOTA or line.level == "E"
+        return line.level in allowed
+
+    def _append(self, line: LogLine) -> None:
+        sb = self.view.verticalScrollBar()
+        at_bottom = sb.value() >= sb.maximum() - 4
+        fmt = QTextCharFormat()
+        colour = COLORS.get(line.kind) if line.kind == LineKind.KOTA and line.level == "I" else None
+        fmt.setForeground(QColor(colour or COLORS.get(line.level) or COLORS.get(line.kind, "#d4d4d4")))
+        if line.kind in (LineKind.PANIC, LineKind.BOOT, LineKind.HOST) or line.record in ("boot", "status"):
+            fmt.setFontWeight(QFont.Weight.Bold)
+        cur = QTextCursor(self.view.document())
+        cur.movePosition(QTextCursor.MoveOperation.End)
+        if not self.view.document().isEmpty():
+            cur.insertBlock()
+        cur.insertText(line.text, fmt)
+        if at_bottom:
+            sb.setValue(sb.maximum())
+
+    # ---- diagnostics -------------------------------------------------
+    def _refresh_diag(self) -> None:
+        if self._diag_dirty:
+            self._diag_dirty = False
+            self.diag.show_report(self._engine.report())
+        self.guide.refresh()   # countdowns and timeouts need a steady tick
+
+    # ---- guided troubleshooting hooks ------------------------------------
+    def _guide_action(self, action: str) -> bool:
+        if action == "reset" and self._manager.state == State.CONNECTED:
+            self._manager.reset_board()
+            return True
+        return False
+
+    def _guide_log(self, text: str) -> None:
+        # Technician answers go into the session log and the log view.
+        line = host_event(text)
+        self._session.write(line)
+        self._append(line)
+        self._diag_dirty = True
+
+    def _copy_report(self) -> None:
+        QGuiApplication.clipboard().setText(self._engine.report().to_text())
+
+    def _analyze_file(self) -> None:
+        path, _ = QFileDialog.getOpenFileName(
+            self, "Analyze log file", str(self._session.root), "Logs (*.log *.txt);;All files (*)")
+        if not path:
+            return
+        lines = read_log_file(Path(path))
+        self.view.clear()
+        self._engine.reset()
+        self._runner.cancel()
+        self._counts = {"E": 0, "W": 0, "boots": 0}
+        for line in lines:
+            self._engine.feed(line)
+            if line.kind == LineKind.BOOT:
+                self._counts["boots"] += 1
+            if line.level in ("E", "W"):
+                self._counts[line.level] += 1
+            self._append(line)
+        self._state_text = f"Analyzed file: {Path(path).name} ({len(lines)} lines)"
+        self._update_status()
+        self._diag_dirty = True
+        self._refresh_diag()
+
+    # ---- misc --------------------------------------------------------
+    def _save_view(self) -> None:
+        path, _ = QFileDialog.getSaveFileName(self, "Save log view", "sensorbox_log.txt", "Text (*.txt)")
+        if path:
+            with open(path, "w", encoding="utf-8") as fh:
+                fh.write(self.view.toPlainText())
+
+    def _open_folder(self) -> None:
+        self._session.root.mkdir(parents=True, exist_ok=True)
+        QDesktopServices.openUrl(QUrl.fromLocalFile(str(self._session.root)))
+
+    def shutdown(self) -> None:
+        self._manager.disconnect()
+        self._session.stop()
+
+
+class MainWindow(QMainWindow):
+    def __init__(self):
+        super().__init__()
+        self.setWindowTitle(f"KOTA Sensorbox Technician Tool  v{__version__}")
+        self.resize(1200, 800)
+        tabs = QTabWidget()
+        guide = QTextBrowser(openExternalLinks=True)
+        guide.setHtml(cheatsheet_html())
+        self.serial_tab = SerialTab()
+        self.flash_tab = FlashTab(self.serial_tab)
+        tabs.addTab(guide, "Quick start")
+        tabs.addTab(self.serial_tab, "Serial monitor")
+        tabs.addTab(self.flash_tab, "Flash firmware")
+        self.sd_tab = SdTab(self.serial_tab)
+        tabs.addTab(self.sd_tab, "SD card")
+        self.setCentralWidget(tabs)
+        settings_menu = self.menuBar().addMenu("Settings")
+        settings_menu.addAction("Service system address...", self._edit_service_base)
+
+    def _edit_service_base(self) -> None:
+        st = self.serial_tab
+        text, ok = QInputDialog.getText(
+            self, "Service system address",
+            "Address of the KOTA service system (the box MAC is added at the end):",
+            text=st._service_base())
+        if ok and text.strip().startswith(("https://", "http://")):
+            st._settings.setValue("service/base", text.strip())
+        elif ok:
+            QMessageBox.warning(self, "Service system address", "The address must start with https://")
+
+    def closeEvent(self, event):  # noqa: N802 (Qt naming)
+        self.serial_tab.shutdown()
+        super().closeEvent(event)

kota_tech/ui/matter_qr.py

@@ -1,72 +1,76 @@
-"""Matter pairing QR code on screen, so the technician can scan it from the laptop."""
-
-from __future__ import annotations
-
-import segno
-from PySide6.QtCore import Qt
-from PySide6.QtGui import QColor, QImage, QPainter, QPixmap
-from PySide6.QtWidgets import QDialog, QDialogButtonBox, QLabel, QVBoxLayout, QWidget
-
-from ..matter.payload import SetupPayload
-
-
-def qr_pixmap(text: str, size: int = 260) -> QPixmap:
-    """Black-on-white QR with the quiet zone phones need (4 modules)."""
-    qr = segno.make(text, error="m")
-    matrix = [list(row) for row in qr.matrix_iter(scale=1, border=4)]
-    n = len(matrix)
-    module = max(1, size // n)
-    img = QImage(n * module, n * module, QImage.Format.Format_RGB32)
-    img.fill(QColor("white"))
-    p = QPainter(img)
-    p.setPen(Qt.PenStyle.NoPen)
-    p.setBrush(QColor("black"))
-    for y, row in enumerate(matrix):
-        for x, dark in enumerate(row):
-            if dark:
-                p.drawRect(x * module, y * module, module, module)
-    p.end()
-    return QPixmap.fromImage(img)
-
-
-class MatterQrWidget(QWidget):
-    def __init__(self, payload: SetupPayload, size: int = 260, parent: QWidget | None = None):
-        super().__init__(parent)
-        self.image = QLabel()
-        self.image.setAlignment(Qt.AlignmentFlag.AlignCenter)
-        self.code = QLabel()
-        self.code.setAlignment(Qt.AlignmentFlag.AlignCenter)
-        self.code.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
-        f = self.code.font()
-        f.setPointSize(f.pointSize() + 4)
-        f.setBold(True)
-        self.code.setFont(f)
-        self.note = QLabel(wordWrap=True)
-        self.note.setAlignment(Qt.AlignmentFlag.AlignCenter)
-        self.note.setStyleSheet("color:#555")
-        lay = QVBoxLayout(self)
-        lay.addWidget(self.image)
-        lay.addWidget(self.code)
-        lay.addWidget(self.note)
-        self._size = size
-        self.set_payload(payload)
-
-    def set_payload(self, payload: SetupPayload) -> None:
-        self.payload = payload
-        self.image.setPixmap(qr_pixmap(payload.qr_text(), self._size))
-        self.code.setText(f"Manual code: {payload.manual_code_pretty()}")
-        src = ("from this box's log" if payload.from_log else
-               "standard code of the v1.0 firmware - connect the box to confirm")
-        self.note.setText(f"Scan with the Matter app (Apple Home, Google Home, ...), or type the manual code. "
-                          f"Discriminator {payload.discriminator} ({src}). Same as the sticker on the box.")
-
-
-class MatterQrDialog(QDialog):
-    def __init__(self, payload: SetupPayload, parent: QWidget | None = None):
-        super().__init__(parent)
-        self.setWindowTitle("Matter pairing code")
-        lay = QVBoxLayout(self)
-        lay.addWidget(MatterQrWidget(payload, 320))
-        buttons = QDialogButtonBox(QDialogButtonBox.StandardButton.Close)
-        buttons.rejected.connect(self.reject)
-        lay.addWidget(buttons)
+"""Matter pairing QR code on screen, so the technician can scan it from the laptop."""
+
+from __future__ import annotations
+
+import segno
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QColor, QImage, QPainter, QPixmap
+from PySide6.QtWidgets import QDialog, QDialogButtonBox, QLabel, QVBoxLayout, QWidget
+
+from ..matter.payload import SetupPayload
+
+
+def qr_pixmap(text: str, size: int = 260) -> QPixmap:
+    """Black-on-white QR with the quiet zone phones need (4 modules)."""
+    qr = segno.make(text, error="m")
+    matrix = [list(row) for row in qr.matrix_iter(scale=1, border=4)]
+    n = len(matrix)
+    module = max(1, size // n)
+    img = QImage(n * module, n * module, QImage.Format.Format_RGB32)
+    img.fill(QColor("white"))
+    p = QPainter(img)
+    p.setPen(Qt.PenStyle.NoPen)
+    p.setBrush(QColor("black"))
+    for y, row in enumerate(matrix):
+        for x, dark in enumerate(row):
+            if dark:
+                p.drawRect(x * module, y * module, module, module)
+    p.end()
+    return QPixmap.fromImage(img)
+
+
+class MatterQrWidget(QWidget):
+    def __init__(self, payload: SetupPayload, size: int = 260, parent: QWidget | None = None):
+        super().__init__(parent)
+        self.image = QLabel()
+        self.image.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.code = QLabel()
+        self.code.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.code.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+        f = self.code.font()
+        f.setPointSize(f.pointSize() + 4)
+        f.setBold(True)
+        self.code.setFont(f)
+        self.note = QLabel(wordWrap=True)
+        self.note.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.note.setStyleSheet("color:#555")
+        lay = QVBoxLayout(self)
+        lay.addWidget(self.image)
+        lay.addWidget(self.code)
+        lay.addWidget(self.note)
+        self._size = size
+        self.set_payload(payload)
+
+    def set_payload(self, payload: SetupPayload) -> None:
+        self.payload = payload
+        self.image.setPixmap(qr_pixmap(payload.qr_text(), self._size))
+        self.code.setText(f"Manual code: {payload.manual_code_pretty()}")
+        if payload.from_box:
+            src = "QR and manual code exactly as reported by the box (KOTA: matter line)"
+        else:
+            src = f"Discriminator {payload.discriminator} " + (
+                "(from this box's log)" if payload.from_log else
+                "(standard code of the v1.0 firmware - connect the box to confirm)")
+        self.note.setText(f"Scan with the Matter app (Apple Home, Google Home, ...), or type the manual code. "
+                          f"{src}. Same as the sticker on the box.")
+
+
+class MatterQrDialog(QDialog):
+    def __init__(self, payload: SetupPayload, parent: QWidget | None = None):
+        super().__init__(parent)
+        self.setWindowTitle("Matter pairing code")
+        lay = QVBoxLayout(self)
+        lay.addWidget(MatterQrWidget(payload, 320))
+        buttons = QDialogButtonBox(QDialogButtonBox.StandardButton.Close)
+        buttons.rejected.connect(self.reject)
+        lay.addWidget(buttons)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kota-technician-tool"
-version = "0.6.0"
+version = "0.8.0"
 description = "KOTA sensorbox technician diagnostic tool (demo)"
 requires-python = ">=3.11,<3.14"
 dependencies = [

run_macos.command

@@ -2,8 +2,10 @@
 # Double-click in Finder, or run:  bash run_macos.command
 cd "$(dirname "$0")" || exit 1
 
+# If Finder refuses to open this file (Google Drive drops the executable bit), run it once as:
+#   bash run_macos.command     (or: chmod +x run_macos.command)
 # Keep the virtual environment out of the (Google Drive) tool folder.
-export UV_PROJECT_ENVIRONMENT="$HOME/Library/Caches/KotaTechnicianTool/venv-0.6"
+export UV_PROJECT_ENVIRONMENT="$HOME/Library/Caches/KotaTechnicianTool/venv-0.8"
 export PATH="$HOME/.local/bin:$PATH"
 
 if ! command -v uv >/dev/null 2>&1; then

run_windows.bat

@@ -3,7 +3,7 @@ setlocal
 cd /d "%~dp0"
 
 rem Keep the virtual environment out of the (Google Drive) tool folder.
-set "UV_PROJECT_ENVIRONMENT=%LOCALAPPDATA%\KotaTechnicianTool\venv-0.6"
+set "UV_PROJECT_ENVIRONMENT=%LOCALAPPDATA%\KotaTechnicianTool\venv-0.8"
 set "PATH=%USERPROFILE%\.local\bin;%PATH%"
 
 where uv >nul 2>nul

tests/fixtures/synthetic_fw1.0.16_healthy.txt

@@ -0,0 +1,22 @@
+ESP-ROM:esp32s3-20210327
+rst:0x15 (USB_UART_CHIP_RESET),boot:0x8 (SPI_FAST_FLASH_BOOT)
+I (1299) app_init: Project name:     kota-sensorboard
+I (1303) app_init: App version:      1.0.16
+I (1307) app_init: Compile time:     Sep 28 2026 15:07:57
+I (1317) app_init: ELF file SHA256:  4f10989e2...
+E (1402) ID: [E-MAIN-04] Device MAC address: A4:CB:8F:C9:46:F8
+I (1480) KOTA: led previous_boot status=CONNECTION_ERROR code=1
+I (1481) KOTA: led color=purple pattern=blink period=1000ms
+I (1790) KOTA: i2c SDA=1 SCL=1 0x39=AS7341 0x68=DS1307 0x6B=SEN66 0x76=BME688
+I (1795) KOTA: rtc running=1 time=2026-09-28T15:20:01
+I (1850) SD_CARD: SD card mounted successfully
+I (1990) KOTA: sd type=SDHC size=7.4GB fs=FAT32 free=7.3GB env_keys=INFLUX_URL,INFLUX_TOKEN buffer_lines=0
+I (2300) MAIN: ESP-Matter started successfully
+I (2310) KOTA: boot fw=1.0.16 build=4f10989e hw=2 mac=A4CB8FC946F8 reset=USB_UART_CHIP_RESET mode=matter commissioned=1 last_restart=none
+I (2315) KOTA: matter fabrics=1 window=closed qr=MT:Y.K9042C00KA0648G00 manual=34970112332
+I (2400) KOTA: mic enabled=1 (GPIO3=0, expected 0)
+I (4481) KOTA: led color=green pattern=solid
+I (5200) WIFI_SERVICE: Got IP address
+I (6100) SNTP: Time synchronized: Mon Sep 28 15:20:06 2026
+I (8100) KOTA: rtc verify running=1 delta=2s ok=1
+I (60010) KOTA: health up=60s status=OK wifi=connected rssi=-58 time_valid=1 sd=ok buffer=0 heap=143220 psram=7.6M last_upload=14s ota=registered

tests/test_engine.py

@@ -43,16 +43,20 @@ APP = ["I (1299) app_init: Project name:     kota-sensorboard",
 # ------------------------------------------------------------------ rules
 
 def test_rules_load_and_have_no_cycles():
-    rules = load_rules()
-    by_id = {r.id: r for r in rules}
-    for r in rules:
-        seen, todo = set(), list(r.explained_by)
+    from kota_tech.diag import kota
+    graph = {r.id: r.explained_by for r in load_rules()}
+    for st in ("ERROR", "OUT_OF_RESOURCES", "CONNECTION_ERROR", "RTC_ERROR", "SD_ERROR", "RESETING", "HTTP_SERVER"):
+        for code in range(7):
+            if sf := kota.status_finding(st, code):
+                graph[sf[0]] = sf[5]
+    for start, explained_by in graph.items():
+        seen, todo = set(), list(explained_by)
         while todo:
             rid = todo.pop()
-            assert rid != r.id, f"explained_by cycle through {r.id}"
+            assert rid != start, f"explained_by cycle through {start}"
             if rid not in seen:
                 seen.add(rid)
-                todo += by_id[rid].explained_by
+                todo += graph.get(rid, ())
 
 
 # --------------------------------------------------------- real captures
@@ -233,3 +237,23 @@ def test_session_log_format(tmp_path):
     for ln in lines:
         e.feed(ln)
     assert e.boot.tool_reset
+
+
+def test_live_brownout_loop_is_a_power_problem():
+    # Real capture (2026-09-28): "E BOD: Brownout detector was triggered" has no
+    # timestamp and the ROM reports RTC_SW_SYS_RST, not a brown-out reset.
+    r = replay("live_brownout_loop_A4CB8FC946F8_fw1.0.txt")
+    top = r.roots[0]
+    assert top.finding.rule_id == "reboot.brownout" and top.finding.count >= 5
+    assert "reboot.loop" in {c.rule_id for c in top.consequences}
+    assert r.verdict.startswith("Problem: Power supply")
+
+
+@pytest.mark.parametrize("line", [
+    "E (2893) wifi:sta is connecting, return error",
+    "E (2892) chip[DL]: esp_wifi_connect() failed: ESP_ERR_WIFI_CONN",
+    "E (5120) chip[DL]: Failed to get configured network when updating network status: Error ESP32:0x0500300F",
+])
+def test_harmless_wifi_start_errors_are_not_reported(line):
+    _, r = run(BOOT + APP + [line])
+    assert r.roots == [] and "Unrecognised" not in r.to_text()

tests/test_flash.py

@@ -1,5 +1,6 @@
-"""Flashing: image validation on the real official image, plan building,
-and the runner against a fake esptool (no hardware)."""
+"""Flashing: image validation on the real image in firmware/, the folder
+catalogue (compile-date order), plan building, and the runner against a fake
+esptool (no hardware)."""
 
 import hashlib
 import sys
@@ -8,31 +9,39 @@ from pathlib import Path
 
 import pytest
 
-from kota_tech.flash.image import ImageError, inspect_image, official_images
+from kota_tech.flash.image import ImageError, app_image_length, folder_images, inspect_image
 from kota_tech.flash.plan import Mode, build_plan, check_partition_table
 from kota_tech.flash.runner import FlashRunner
 
-FW = Path(__file__).resolve().parents[1] / "firmware" / "new_system.bin"
+FW_DIR = Path(__file__).resolve().parents[1] / "firmware"
+FW = sorted(FW_DIR.glob("*.bin"))[0]
 
 
 @pytest.fixture(scope="module")
 def image():
-    imgs = official_images()
-    assert len(imgs) == 1
+    imgs, problems = folder_images()
+    assert imgs and problems == []
     return imgs[0]
 
 
 # ------------------------------------------------------------------ image
 
-def test_official_image_is_the_deployed_v1_build(image):
+def test_folder_image_is_a_kota_build(image):
     assert image.app.project == "kota-sensorboard"
-    assert image.app.elf_sha.startswith("45fa9d5b9")       # same as the live board
+    assert image.kind == "merged"
+    assert image.app.built_at is not None                  # compile date is readable
     assert image.flash_size == "8MB"
     assert image.partition("ota_0").offset == 0x40000
     assert image.partition("otadata").offset == 0x31000
     assert image.partition("nvs").offset == 0x10000
 
 
+def test_label_starts_with_compile_date(image):
+    label = image.label()
+    assert label.startswith(f"Compiled {image.app.built_at:%Y-%m-%d %H:%M}")
+    assert image.app.version in label and image.name in label
+
+
 def test_app_bytes_are_a_complete_app_image(image):
     app = image.app_bytes()
     assert app[0] == 0xE9
@@ -40,17 +49,6 @@ def test_app_bytes_are_a_complete_app_image(image):
     assert len(image.blank_otadata()) == 0x2000 and set(image.blank_otadata()) == {0xFF}
 
 
-def test_modified_image_is_refused(tmp_path):
-    data = bytearray(FW.read_bytes())
-    data[-1] ^= 0xFF
-    bad = tmp_path / "new_system.bin"
-    bad.write_bytes(data)
-    manifest = tmp_path / "firmware.toml"
-    manifest.write_text(f'[[image]]\nfile = "new_system.bin"\nsha256 = "{hashlib.sha256(FW.read_bytes()).hexdigest()}"\n')
-    with pytest.raises(ImageError, match="SHA-256"):
-        official_images(manifest)
-
-
 @pytest.mark.parametrize("patch,msg", [
     ((0, 0x00), "not an ESP32 firmware"),
     ((12, 0x05), "not ESP32-S3"),
@@ -64,6 +62,93 @@ def test_wrong_images_are_rejected(tmp_path, patch, msg):
         inspect_image(p)
 
 
+def test_integrity_check_on_folder_image(image):
+    d = image.data
+    assert app_image_length(d, 0) > 0                          # bootloader
+    assert app_image_length(d, 0x40000) == len(d) - 0x40000    # app ends exactly at file end
+
+
+@pytest.mark.parametrize("damage,msg", [
+    (lambda b: b[:len(b) // 2], "truncated"),
+    (lambda b: b[:0x40000 + 5000] + bytes([b[0x40000 + 5000] ^ 1]) + b[0x40000 + 5001:], "corrupted"),
+])
+def test_corrupted_or_truncated_images_refused(tmp_path, damage, msg):
+    p = tmp_path / "broken.bin"
+    p.write_bytes(damage(FW.read_bytes()))
+    with pytest.raises(ImageError, match=msg):
+        inspect_image(p)
+
+
+# ------------------------------------------------------- firmware folder
+
+def _with_compile_date(data: bytes, date: str, time: str, off: int = 0x40000) -> bytes:
+    """Copy of a merged image whose app claims another compile date, with the
+    segment checksum and appended SHA-256 recomputed (a valid, different build)."""
+    d = bytearray(data)
+    desc = off + 0x20
+    old = bytes(d[desc + 80:desc + 112])
+    new = time.encode().ljust(16, b"\0") + date.encode().ljust(16, b"\0")
+    d[desc + 80:desc + 112] = new
+    end = off + app_image_length(data, off) - 32      # SHA-256 follows the checksum byte
+    xor = 0
+    for a, b in zip(old, new):
+        xor ^= a ^ b
+    d[end - 1] ^= xor
+    d[end:end + 32] = hashlib.sha256(bytes(d[off:end])).digest()
+    return bytes(d)
+
+
+def test_folder_lists_builds_newest_compile_date_first(tmp_path):
+    data = FW.read_bytes()
+    (tmp_path / "a_old.bin").write_bytes(_with_compile_date(data, "Jan  5 2026", "08:00:00"))
+    (tmp_path / "z_new.bin").write_bytes(_with_compile_date(data, "Dec 24 2026", "18:30:00"))
+    (tmp_path / "m_mid.bin").write_bytes(_with_compile_date(data, "Jun 15 2026", "12:00:00"))
+    imgs, problems = folder_images(tmp_path)
+    assert problems == []
+    assert [i.name for i in imgs] == ["z_new.bin", "m_mid.bin", "a_old.bin"]
+    assert imgs[0].label().startswith("Compiled 2026-12-24 18:30")
+    assert imgs[2].label().startswith("Compiled 2026-01-05 08:00")
+
+
+def test_folder_reports_bad_files_and_duplicates(tmp_path):
+    data = FW.read_bytes()
+    (tmp_path / "good.bin").write_bytes(data)
+    (tmp_path / "copy.bin").write_bytes(data)
+    (tmp_path / "notes.bin").write_bytes(b"hello firmware team")
+    (tmp_path / "readme.txt").write_text("ignored: not a .bin")
+    imgs, problems = folder_images(tmp_path)
+    assert len(imgs) == 1
+    assert any("notes.bin" in p and "not an ESP32 firmware" in p for p in problems)
+    assert any("same file as" in p for p in problems)
+    assert not any("readme" in p for p in problems)
+
+
+def test_app_only_file_uses_the_merged_layout(tmp_path, image):
+    (tmp_path / "merged.bin").write_bytes(image.data)
+    (tmp_path / "kota-sensorboard.bin").write_bytes(
+        _with_compile_date(image.data, "Dec  1 2026", "10:00:00")[0x40000:])
+    imgs, problems = folder_images(tmp_path)
+    assert problems == []
+    app = next(i for i in imgs if i.kind == "app")
+    assert imgs[0] is app                                      # newer compile date first
+    assert app.partition("ota_0").offset == 0x40000 and "app only" in app.label()
+    assert [s.kind for s in build_plan(app, Mode.APP_ONLY, "COM5", tmp_path / "w").steps] == ["read_pt", "write"]
+    with pytest.raises(ValueError, match="app only"):
+        build_plan(app, Mode.FULL, "COM5", tmp_path / "w")
+
+
+def test_app_only_file_without_merged_image_is_not_offered(tmp_path, image):
+    (tmp_path / "kota-sensorboard.bin").write_bytes(image.app_bytes())
+    imgs, problems = folder_images(tmp_path)
+    assert imgs == [] and "no complete (merged) image" in problems[0]
+
+
+def test_empty_or_missing_folder(tmp_path):
+    assert folder_images(tmp_path) == ([], [])
+    imgs, problems = folder_images(tmp_path / "nope")
+    assert imgs == [] and "not found" in problems[0]
+
+
 # ------------------------------------------------------------------- plan
 
 def test_app_only_plan_keeps_nvs(image, tmp_path):
@@ -160,115 +245,3 @@ def test_runner_reports_connect_failure_with_hint(image, tmp_path):
     res, *_ = _run(plan, cmd)
     assert not res.ok and res.failed_step == 0
     assert "BOOT" in res.hint
-
-
-# ------------------------------------------------- developer builds (v0.5)
-
-from kota_tech.flash.image import FirmwareLibrary, app_image_length  # noqa: E402
-
-
-def _app_only_file(image, tmp_path, name="kota-sensorboard.bin"):
-    p = tmp_path / name
-    p.write_bytes(image.app_bytes())          # what a developer build/ folder contains
-    return p
-
-
-def test_integrity_check_on_factory_image(image):
-    d = image.data
-    assert app_image_length(d, 0) > 0                          # bootloader
-    assert app_image_length(d, 0x40000) == len(d) - 0x40000    # app ends exactly at file end
-
-
-@pytest.mark.parametrize("damage,msg", [
-    (lambda b: b[:len(b) // 2], "truncated"),
-    (lambda b: b[:0x40000 + 5000] + bytes([b[0x40000 + 5000] ^ 1]) + b[0x40000 + 5001:], "corrupted"),
-])
-def test_corrupted_or_truncated_images_refused(tmp_path, damage, msg):
-    p = tmp_path / "broken.bin"
-    p.write_bytes(damage(FW.read_bytes()))
-    with pytest.raises(ImageError, match=msg):
-        inspect_image(p, origin="developer")
-
-
-def test_import_app_only_developer_build(image, tmp_path):
-    lib = FirmwareLibrary(tmp_path / "lib")
-    src = _app_only_file(image, tmp_path)
-    img = lib.import_file(src, reference=image)
-    assert img.is_developer and img.kind == "app"
-    assert img.partition("ota_0").offset == 0x40000            # layout from the factory image
-    assert img.app_bytes() == image.app_bytes()
-    listed, problems = lib.images(image)
-    assert [i.sha256 for i in listed] == [img.sha256] and problems == []
-    assert lib.import_file(src, reference=image).sha256 == img.sha256   # re-import: no duplicate
-    assert len(lib.images(image)[0]) == 1
-
-
-def test_app_only_build_cannot_be_flashed_full(image, tmp_path):
-    lib = FirmwareLibrary(tmp_path / "lib")
-    img = lib.import_file(_app_only_file(image, tmp_path), reference=image)
-    plan = build_plan(img, Mode.APP_ONLY, "COM5", tmp_path / "w")
-    assert [s.kind for s in plan.steps] == ["read_pt", "write"]
-    with pytest.raises(ValueError, match="app only"):
-        build_plan(img, Mode.FULL, "COM5", tmp_path / "w")
-
-
-def test_import_merged_developer_build(image, tmp_path):
-    lib = FirmwareLibrary(tmp_path / "lib")
-    src = tmp_path / "dev_full.bin"
-    src.write_bytes(image.data)
-    img = lib.import_file(src, reference=image)
-    assert img.kind == "merged" and img.is_developer
-    assert [s.kind for s in build_plan(img, Mode.FULL, "COM5", tmp_path / "w").steps] == ["write"]
-
-
-def test_library_detects_file_changed_after_import(image, tmp_path):
-    lib = FirmwareLibrary(tmp_path / "lib")
-    img = lib.import_file(_app_only_file(image, tmp_path), reference=image)
-    stored = tmp_path / "lib" / img.path.name
-    data = bytearray(stored.read_bytes())
-    data[-40] ^= 1
-    stored.write_bytes(data)
-    listed, problems = lib.images(image)
-    assert listed == [] and problems
-
-
-def test_library_remove(image, tmp_path):
-    lib = FirmwareLibrary(tmp_path / "lib")
-    img = lib.import_file(_app_only_file(image, tmp_path), reference=image)
-    lib.remove(img.sha256)
-    assert lib.images(image) == ([], []) and not img.path.exists()
-
-
-def test_non_firmware_file_refused(tmp_path, image):
-    p = tmp_path / "notes.bin"
-    p.write_bytes(b"hello firmware team")
-    with pytest.raises(ImageError, match="not an ESP32 firmware"):
-        FirmwareLibrary(tmp_path / "lib").import_file(p, reference=image)
-
-
-# ------------------------------------------- bundled developer build (v0.6)
-
-from kota_tech.flash.image import bundled_images  # noqa: E402
-
-
-def test_bundled_developer_build_is_labelled_and_not_default():
-    imgs = bundled_images()
-    assert [i.origin for i in imgs] == ["factory", "developer"]       # factory first
-    dev = imgs[1]
-    assert dev.built_by == "Krzysztof Kallas" and "built by Krzysztof Kallas" in dev.label()
-    assert dev.kind == "merged" and dev.app.elf_sha.startswith("c94ba0e9b")
-    assert dev.partition_table == imgs[0].partition_table            # App-only safe on v1.0 boxes
-    assert [i.origin for i in factory_images_only()] == ["factory"]
-
-
-def factory_images_only():
-    from kota_tech.flash.image import factory_images
-    return factory_images()
-
-
-def test_import_records_who_built_it(image, tmp_path):
-    lib = FirmwareLibrary(tmp_path / "lib")
-    img = lib.import_file(_app_only_file(image, tmp_path), reference=image, built_by="  Anna Nowak ")
-    assert img.built_by == "Anna Nowak" and "built by Anna Nowak" in img.label()
-    again, _ = lib.images(image)
-    assert again[0].built_by == "Anna Nowak"

tests/test_kota.py

@@ -0,0 +1,238 @@
+"""Firmware 1.0.16+ structured "KOTA:" lines and error IDs.
+
+The lines below are built from the exact format strings in the firmware
+source (boot_info.cpp, status.cpp, i2c.cpp, ds1307.cpp, sd_card.cpp,
+main.cpp, microphone.cpp, health.cpp); no hardware capture exists yet.
+"""
+
+from pathlib import Path
+
+from kota_tech.core.logfile import read_log_file
+from kota_tech.core.logline import LineKind, parse_line
+from kota_tech.diag.engine import DiagnosticsEngine, Severity
+from kota_tech.diag.firmware import same_build
+from kota_tech.matter.payload import payload_from_log
+from kota_tech.service.report import CONNECTIVITY, HARDWARE, service_status
+
+FIX = Path(__file__).parent / "fixtures"
+BANNER = ["ESP-ROM:esp32s3-20210327", "rst:0x15 (USB_UART_CHIP_RESET),boot:0x8 (SPI_FAST_FLASH_BOOT)"]
+I2C_OK = "I (1790) KOTA: i2c SDA=1 SCL=1 0x39=AS7341 0x68=DS1307 0x6B=SEN66 0x76=BME688"
+SD_OK = ("I (1990) KOTA: sd type=SDHC size=7.4GB fs=FAT32 free=7.3GB "
+         "env_keys=INFLUX_URL,INFLUX_TOKEN buffer_lines=0")
+BOOT = ("I (2310) KOTA: boot fw=1.0.16 build=4f10989e hw=2 mac=A4CB8FC946F8 reset=USB_UART_CHIP_RESET "
+        "mode=matter commissioned=1 last_restart={last}")
+
+
+def run(lines):
+    e = DiagnosticsEngine()
+    for i, text in enumerate(lines):
+        e.feed(parse_line(text, host_time=i * 0.01))
+    return e, e.report()
+
+
+def roots(report):
+    return {rc.finding.rule_id: rc for rc in report.roots}
+
+
+# ------------------------------------------------------------- parsing
+
+def test_kota_lines_are_parsed_into_fields():
+    ln = parse_line(BOOT.format(last="status_watchdog"))
+    assert ln.kind == LineKind.KOTA and ln.record == "boot" and ln.level == "I"
+    assert ln.fields["fw"] == "1.0.16" and ln.fields["last_restart"] == "status_watchdog"
+    st = parse_line("I (5) KOTA: status OK -> CONNECTION_ERROR code=1 reason=influx_rejected")
+    assert st.words == ("OK", "->", "CONNECTION_ERROR") and st.fields == {"code": "1", "reason": "influx_rejected"}
+    mic = parse_line("I (6) KOTA: mic enabled=0 (GPIO3=1, expected 0)")
+    assert mic.fields["enabled"] == "0" and mic.fields["GPIO3"] == "1"
+    i2c = parse_line("I (7) KOTA: i2c SDA=1 SCL=1 0x39=AS7341 0x68=DS1307(missing) 0x50=?")
+    assert i2c.fields["0x68"] == "DS1307(missing)" and i2c.fields["0x50"] == "?"
+    verify = parse_line("I (8) KOTA: rtc verify running=1 delta=2s ok=1")
+    assert verify.record == "rtc" and "verify" in verify.words and verify.fields["ok"] == "1"
+
+
+def test_error_id_is_split_off_but_kept_in_text():
+    ln = parse_line("E (1200) SD_CARD: [E-SD-03] Failed to initialize the card (ESP_ERR_TIMEOUT).")
+    assert ln.kind == LineKind.LOG and ln.error_id == "E-SD-03"
+    assert ln.message.startswith("Failed to initialize") and "[E-SD-03]" in ln.text
+    assert ln.match_text == "E (1200) SD_CARD: Failed to initialize the card (ESP_ERR_TIMEOUT)."
+
+
+def test_sd_line_with_secret_key_names_is_not_redacted():
+    ln = parse_line("I (9) KOTA: sd type=SDHC size=7.4GB fs=FAT32 free=7.3GB "
+                    "env_keys=INFLUX_URL,INFLUX_TOKEN,SSID,PASSWORD buffer_lines=0")
+    assert ln.fields["env_keys"] == "INFLUX_URL,INFLUX_TOKEN,SSID,PASSWORD"
+
+
+# -------------------------------------------------------------- engine
+
+def test_healthy_box_from_kota_lines():
+    e = DiagnosticsEngine()
+    for ln in read_log_file(FIX / "synthetic_fw1.0.16_healthy.txt"):
+        e.feed(ln)
+    r = e.report()
+    assert r.verdict.startswith("Healthy")
+    assert (r.led, r.led_pattern, r.led_exact, r.led_meaning) == ("GREEN", "solid", True, "OK")
+    assert "v1.0.16" in r.firmware.describe() and "4f10989e" in r.firmware.describe()
+    assert e.mac == "A4:CB:8F:C9:46:F8"
+    reached = {m for m, _, t in r.milestones if t is not None}
+    assert {"i2c_ok", "sd_mounted", "env_loaded", "matter_commissioned", "wifi_connected",
+            "time_synced", "clock_verified", "data_uploaded", "ota_registered"} <= reached
+    topics = {t: st for t, _, st in r.box}
+    assert topics["I2C"] == topics["SD card"] == topics["Health"] == "ok"
+    # The purple state before the tool's reset is shown, but only as information now.
+    prev = [f for f in r.earlier + [rc.finding for rc in r.roots] if f.rule_id == "boot.previous_status"]
+    assert not prev or prev[0].severity == Severity.INFO
+    assert "E-MAIN-04" not in r.to_text()           # MAC line is a benign ESP_LOGE
+
+
+def test_i2c_bus_stuck_is_root_of_blue_led():
+    _, r = run(BANNER + [
+        "I (1480) KOTA: led color=blue pattern=pulses n=2",
+        "I (1790) KOTA: i2c SDA=0 SCL=1 bus=stuck",
+        "I (1791) KOTA: status OK -> RTC_ERROR code=2 reason=i2c_bus_stuck",
+    ])
+    rs = roots(r)
+    assert "kota.i2c_stuck" in rs and rs["kota.i2c_stuck"].finding.severity == Severity.CRITICAL
+    assert "status.rtc.2" in {c.rule_id for c in rs["kota.i2c_stuck"].consequences}
+    assert (r.led, r.led_pattern) == ("BLUE", "2 pulses") and "I2C bus stuck" in r.led_meaning
+    assert service_status(r) == HARDWARE
+
+
+def test_missing_sensor_named_by_i2c_scan_and_red_pulses():
+    _, r = run(BANNER + [
+        "I (1790) KOTA: i2c SDA=1 SCL=1 0x39=AS7341 0x68=DS1307 0x6B=SEN66(missing) 0x76=BME688",
+        SD_OK,
+        "E (2100) MAIN: [E-MAIN-16] Failed to initialize SEN66: ESP_ERR_TIMEOUT",
+        "I (2101) KOTA: status OK -> ERROR code=2 reason=sen66_init_failed",
+        "I (2102) KOTA: led color=red pattern=pulses n=2",
+    ])
+    rs = roots(r)
+    root = rs["kota.sensor_missing"]
+    assert root.finding.title == "SEN66 does not answer on the I2C bus"
+    grouped = {c.rule_id for c in root.consequences}
+    assert {"status.error.2", "sensor.init_failed"} <= grouped
+    init = next(c for c in root.consequences if c.rule_id == "sensor.init_failed")
+    assert "E-MAIN-16" in init.error_ids and "SEN66" in init.error_ids["E-MAIN-16"]
+    assert r.led_meaning == "SEN66 failed"
+    assert "missing: SEN66" in dict((t, x) for t, x, _ in r.box)["I2C"]
+
+
+def test_server_rejected_box_is_purple_blinking():
+    _, r = run(BANNER + [I2C_OK, SD_OK, BOOT.format(last="none"),
+                         "I (70000) KOTA: status OK -> CONNECTION_ERROR code=1 reason=influx_rejected",
+                         "I (70001) KOTA: led color=purple pattern=blink period=1000ms"])
+    assert r.roots[0].finding.rule_id == "status.conn.1"
+    assert r.roots[0].finding.severity == Severity.CRITICAL
+    assert (r.led, r.led_pattern) == ("PURPLE", "blinking (1000 ms)")
+    assert "server rejected" in r.led_meaning
+    assert "influx_rejected" in r.led_reason
+    assert service_status(r) == CONNECTIVITY
+
+
+def test_status_back_to_ok_resolves_the_status_finding():
+    _, r = run(BANNER + [I2C_OK, "I (5000) KOTA: status OK -> CONNECTION_ERROR reason=influx_failed",
+                         "I (9000) KOTA: status CONNECTION_ERROR -> OK reason=influx_ok"])
+    assert "status.conn" not in roots(r)
+    assert any(f.rule_id == "status.conn" and f.resolved_by == "status -> OK" for f in r.resolved)
+
+
+def test_restart_reason_from_the_next_boot_line():
+    _, r = run(BANNER + [I2C_OK, BOOT.format(last="none"),
+                         "I (5000) KOTA: status OK -> ERROR code=3 reason=as7341_failed",
+                         "W (155000) KOTA: restart reason=status_watchdog",
+                         "I (155001) KOTA: led restart_flash color=red",
+                         "ESP-ROM:esp32s3-20210327", "rst:0xc (RTC_SW_CPU_RESET),boot:0x8 (SPI_FAST_FLASH_BOOT)",
+                         "I (1480) KOTA: led previous_boot status=ERROR code=3",
+                         I2C_OK, BOOT.format(last="status_watchdog")])
+    ids = {f.rule_id: f for rc in r.roots for f in [rc.finding, *rc.consequences]}
+    f = ids["reboot.status_watchdog"]
+    assert "150 s" in f.title and "state ERROR code=3" in f.meaning
+
+
+def test_brownout_restart_recorded_by_firmware():
+    _, r = run(BANNER + [I2C_OK, BOOT.format(last="none"), "I (90000) KOTA: health up=90s status=OK "
+                         "wifi=connected rssi=-60 time_valid=1 sd=ok buffer=0 heap=150000 psram=7.6M "
+                         "last_upload=10s ota=registered",
+                         "ESP-ROM:esp32s3-20210327", "rst:0xf (RTCWDT_BROWN_OUT_RESET),boot:0x8",
+                         I2C_OK, BOOT.format(last="brownout")])
+    assert r.roots[0].finding.rule_id == "reboot.brownout"
+
+
+def test_uncaptured_error_id_uses_the_csv_action():
+    _, r = run(BANNER + [I2C_OK, "E (3000) INFLUX_BUFFER: [E-INF-13] Failed to open buffer file for appending"])
+    f = next(f for rc in r.roots for f in [rc.finding, *rc.consequences] if "E-INF-13" in f.error_ids)
+    # A rule already knows this message, so the rule finding carries the code.
+    assert f.rule_id == "sd.write_fail"
+    _, r = run(BANNER + [I2C_OK, "E (3000) SPI: [E-SPI-01] Failed to take SPI mutex"])
+    f = roots(r)["eid.SPI"].finding
+    assert f.title == "SPI bus: Failed to take SPI mutex"
+    assert "firmware team" in f.actions[0] and f.error_ids == {"E-SPI-01": f.actions[0]}
+
+
+def test_legacy_rules_still_match_lines_with_error_ids():
+    _, r = run(BANNER + ["E (1200) MAIN: [E-MAIN-13] Failed to initialize RTC: ESP_ERR_TIMEOUT"])
+    assert "rtc.init_failed" in roots(r)
+
+
+def test_health_line_gives_status_when_connected_mid_run():
+    e, r = run(["I (600000) KOTA: health up=600s status=CONNECTION_ERROR wifi=disconnected rssi=0 "
+                "time_valid=1 sd=ok buffer=120 heap=150000 psram=7.6M last_upload=never ota=registered",
+                "I (660000) KOTA: health up=660s status=CONNECTION_ERROR wifi=disconnected rssi=0 "
+                "time_valid=1 sd=ok buffer=130 heap=150000 psram=7.6M last_upload=never ota=registered"])
+    assert (r.led, r.led_pattern) == ("PURPLE", "solid") and not r.led_exact
+    rs = roots(r)
+    assert "kota.wifi_down" in rs
+    assert "status.conn" in {c.rule_id for c in rs["kota.wifi_down"].consequences}
+    assert r.mid_run
+
+
+def test_sd_and_rtc_self_report():
+    _, r = run(BANNER + [
+        "I (1795) KOTA: rtc running=0 time=2000-01-01T00:00:00",
+        "I (1990) KOTA: sd type=SDHC size=7.4GB fs=FAT32 free=7.3GB env_keys=INFLUX_URL buffer_lines=0",
+        "I (8100) KOTA: rtc verify running=0 delta=0s ok=0",
+    ])
+    ids = {f.key for rc in r.roots for f in [rc.finding, *rc.consequences]}
+    assert {"influx.env_missing:INFLUX_TOKEN", "kota.rtc_stopped", "kota.rtc_not_ticking"} <= ids
+    _, r = run(BANNER + ["I (1990) KOTA: sd mounted=0 err=ESP_ERR_TIMEOUT",
+                         "I (1991) KOTA: status OK -> SD_ERROR reason=sd_mount_failed"])
+    rs = roots(r)
+    assert "kota.sd_unmounted" in rs and "ESP_ERR_TIMEOUT" in rs["kota.sd_unmounted"].finding.title
+    assert "status.sd" in {c.rule_id for c in rs["kota.sd_unmounted"].consequences}
+
+
+def test_matter_and_mic_lines():
+    e, r = run(BANNER + ["I (2315) KOTA: matter fabrics=0 window=open qr=MT:Y.K9042C00KA0648G00 manual=34970112332",
+                         "I (2400) KOTA: mic enabled=0 (GPIO3=1, expected 0)",
+                         "I (4481) KOTA: led color=cyan pattern=breathe period=3000ms"])
+    rs = roots(r)
+    assert "matter.not_commissioned" in rs and "mic.disabled" in rs
+    assert (r.led, r.led_meaning) == ("CYAN", "waiting to be paired in Matter")
+    p = payload_from_log([], e.matter_qr, e.matter_manual)
+    assert p.qr_text() == "MT:Y.K9042C00KA0648G00" and p.manual_code_pretty() == "3497-011-2332"
+    _, r = run(BANNER + ["I (2315) KOTA: matter fabrics=0 window=open qr=MT:Y.K9042C00KA0648G00 manual=34970112332",
+                         "I (90000) KOTA: matter fabrics=1 window=closed qr=MT:Y.K9042C00KA0648G00 manual=34970112332"])
+    assert "matter.not_commissioned" not in roots(r)
+
+
+def test_build_prefixes_of_different_length_match():
+    full = "4f10989e2b40c1d29fb3e8f8faaa50e5555997909c6d6b1db9d4e1e4d04555dc"
+    assert same_build("4f10989e", full) and same_build(full, "4f10989e2")
+    assert not same_build("4f10989f", full) and not same_build(None, full)
+
+
+def test_live_fw1016_uncommissioned_box():
+    # Real capture (2026-09-28) after flashing 1.0.16 App-only: not paired in Matter.
+    e = DiagnosticsEngine()
+    for ln in read_log_file(FIX / "live_boot_A4CB8FC946F8_fw1.0.16_uncommissioned.txt"):
+        e.feed(ln)
+    r = e.report()
+    assert r.firmware.version == "1.0.16" and same_build(r.firmware.elf_sha, "4f10989e")
+    assert (r.led, r.led_pattern, r.led_exact) == ("CYAN", "breathing", True)
+    rs = roots(r)
+    assert r.roots[0].finding.rule_id == "matter.not_commissioned"
+    grouped = {c.rule_id for c in rs["matter.not_commissioned"].consequences}
+    assert {"kota.wifi_down", "net.dns_fail", "status.conn", "kota.buffer_backlog"} <= grouped
+    assert "rtc.clock_not_running" in {c.rule_id for c in rs["kota.rtc_stopped"].consequences}
+    assert e.matter_qr == "MT:Y.K9042C00KA0648G00"
+    assert not any(f.rule_id.startswith("other.") for f in e.findings.values())

tests/test_ports.py

@@ -12,3 +12,15 @@ def test_other_ports_not_sensorbox():
     bt = PortInfo("COM3", "Standard Serial over Bluetooth link", None, None, None)
     assert not bt.is_sensorbox and bt.mac is None
     assert bt.label == "COM3 - Standard Serial over Bluetooth link"
+
+
+def test_macos_lists_only_callout_devices(monkeypatch):
+    from types import SimpleNamespace
+
+    from kota_tech.serialio import ports
+    fake = [SimpleNamespace(device=d, description="USB JTAG/serial debug unit", vid=0x303A, pid=0x1001,
+                            serial_number="A4:CB:8F:C9:46:F8")
+            for d in ("/dev/tty.usbmodem1101", "/dev/cu.usbmodem1101")]
+    monkeypatch.setattr(ports.sys, "platform", "darwin")
+    monkeypatch.setattr(ports.list_ports, "comports", lambda: fake)
+    assert [p.device for p in ports.list_serial_ports()] == ["/dev/cu.usbmodem1101"]

tests/test_sd.py

@@ -170,3 +170,14 @@ def test_elevated_result_folder_is_not_owner_only(tmp_path, monkeypatch):
     assert work.parent == tmp_path / "tmp" and work.is_dir()
     (work / "result.json").write_text('{"ok": true}', encoding="utf-8")
     assert (work / "result.json").read_text(encoding="utf-8")
+
+
+@pytest.mark.parametrize("fs", ["FAT32", "DOS_FAT_32", "Windows_FAT_32", "MS-DOS FAT32"])
+def test_fat32_names_from_windows_and_macos_are_accepted(tmp_path, fs):
+    (tmp_path / "ENV.TXT").write_bytes(b"INFLUX_URL=https://x\nINFLUX_TOKEN=abc\n")
+    assert not any("File system" in p for p in check_card(str(tmp_path), fs).problems)
+
+
+def test_exfat_is_flagged(tmp_path):
+    (tmp_path / "ENV.TXT").write_bytes(b"INFLUX_URL=https://x\nINFLUX_TOKEN=abc\n")
+    assert any("File system" in p for p in check_card(str(tmp_path), "ExFAT").problems)

tests/test_service.py

@@ -33,7 +33,7 @@ def test_bench_box_is_a_connectivity_problem():
     assert service_status(e.report()) == CONNECTIVITY
     note = service_note(e.report())
     assert note.startswith("[KOTA Technician Tool")
-    assert "not commissioned in Matter" in note and "-> No Internet" in note
+    assert "not commissioned in Matter" in note and "↳ [Error] No Internet" in note
     assert "Firmware: v1.0" in note
 
 
@@ -89,3 +89,19 @@ def test_invalid_mac_rejected(bad):
 
 def test_normalize_mac():
     assert normalize_mac("a4:cb:8f:c9:46:f8") == "A4CB8FC946F8"
+
+
+def test_note_mirrors_the_diagnosis_panel():
+    from pathlib import Path
+    from kota_tech.core.logfile import read_log_file
+    e = DiagnosticsEngine()
+    for ln in read_log_file(Path(__file__).parent / "fixtures" / "live_boot_A4CB8FC946F8_fw1.0.16_uncommissioned.txt"):
+        e.feed(ln)
+    note = service_note(e.report())
+    assert len(note) <= 5000
+    for part in ("Status LED should be: Cyan, breathing", "Box self-report (KOTA lines):",
+                 "✔ I2C: found: AS7341, DS1307, SEN66, BME688", "Start-up progress (current boot):",
+                 "✔ SD card mounted (1.7 s)", "○ Connected to Wi-Fi", "What to do:",
+                 "Seen 12x, first at 21.6 s after start, last at 126.8 s",
+                 "↳ [Error] No Internet: server names cannot be resolved"):
+        assert part in note, part

uv.lock

@@ -250,7 +250,7 @@ wheels = [
 
 [[package]]
 name = "kota-technician-tool"
-version = "0.6.0"
+version = "0.8.0"
 source = { virtual = "." }
 dependencies = [
     { name = "esptool" },