Store all text files with LF line endings
Some files had been saved with CRLF on Windows, so a one-line change showed as a whole-file diff. .gitattributes now stores text as LF (.bat stays CRLF for cmd, .command/.sh LF for macOS). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
kkallasandClaude Opus 5.5 committed
1 parent
3fe45fa4d5
commit
0d21c5c205
19 files changed
+8290
-8288
No files matched your search
@@ -1,4 +1,6 @@
|
|||||||
|
* text=auto eol=lf
|
||||||
*.command text eol=lf
|
*.command text eol=lf
|
||||||
*.sh text eol=lf
|
*.sh text eol=lf
|
||||||
*.bat text eol=crlf
|
*.bat text eol=crlf
|
||||||
*.bin binary
|
*.bin binary
|
||||||
|
*.png binary
|
||||||
@@ -1,77 +1,77 @@
|
|||||||
# KOTA Sensorbox Technician Tool
|
# KOTA Sensorbox Technician Tool
|
||||||
|
|
||||||
Diagnoza sensorboxa przez USB, wgrywanie firmware z folderu `firmware/` i przygotowanie karty SD.
|
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.
|
Działa na Windows 10/11 i macOS 13 (Ventura) lub nowszym, na Macach z Intelem i Apple Silicon.
|
||||||
|
|
||||||
Repozytorium: https://gitea.kota-app.com/kkallas/kota-technician-tool (dostęp nadaje właściciel repozytorium).
|
Repozytorium: https://gitea.kota-app.com/kkallas/kota-technician-tool (dostęp nadaje właściciel repozytorium).
|
||||||
|
|
||||||
## Dla technika: dwa pliki
|
## Dla technika: dwa pliki
|
||||||
|
|
||||||
| System | Aktualizacja | Uruchomienie |
|
| System | Aktualizacja | Uruchomienie |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| Windows | `update_windows.bat` | `run_windows.bat` |
|
| Windows | `update_windows.bat` | `run_windows.bat` |
|
||||||
| macOS | `update_macos.command` | `run_macos.command` |
|
| macOS | `update_macos.command` | `run_macos.command` |
|
||||||
|
|
||||||
- **Aktualizacja** sprawdza na Gitea najnowszą wydaną wersję i pobiera tylko to, co się zmieniło
|
- **Aktualizacja** sprawdza na Gitea najnowszą wydaną wersję i pobiera tylko to, co się zmieniło
|
||||||
(pliki programu, firmware i potrzebne biblioteki). Uruchom ją, gdy firmware team ogłosi nową wersję,
|
(pliki programu, firmware i potrzebne biblioteki). Uruchom ją, gdy firmware team ogłosi nową wersję,
|
||||||
albo po prostu przed wyjazdem do klienta. Pokazuje, co się zmieniło.
|
albo po prostu przed wyjazdem do klienta. Pokazuje, co się zmieniło.
|
||||||
- **Uruchomienie** startuje program. Nie łączy się z Gitea, działa też bez internetu (po pierwszej aktualizacji).
|
- **Uruchomienie** startuje program. Nie łączy się z Gitea, działa też bez internetu (po pierwszej aktualizacji).
|
||||||
|
|
||||||
Nie trzymaj folderu narzędzia w Google Drive ani OneDrive.
|
Nie trzymaj folderu narzędzia w Google Drive ani OneDrive.
|
||||||
|
|
||||||
## Pierwsza instalacja (raz na komputer)
|
## Pierwsza instalacja (raz na komputer)
|
||||||
|
|
||||||
1. Na Gitea otwórz **Releases** i przy najnowszej wersji pobierz **Source Code (ZIP)**.
|
1. Na Gitea otwórz **Releases** i przy najnowszej wersji pobierz **Source Code (ZIP)**.
|
||||||
2. Rozpakuj do zwykłego folderu, np. `Dokumenty\KOTA\technician-tool` (macOS: `~/Documents/KOTA/technician-tool`).
|
2. Rozpakuj do zwykłego folderu, np. `Dokumenty\KOTA\technician-tool` (macOS: `~/Documents/KOTA/technician-tool`).
|
||||||
3. Uruchom plik aktualizacji dla swojego systemu. Za pierwszym razem:
|
3. Uruchom plik aktualizacji dla swojego systemu. Za pierwszym razem:
|
||||||
- połączy folder z Gitea i zapyta o login do Gitea (hasło lub token); system je zapamięta,
|
- połączy folder z Gitea i zapyta o login do Gitea (hasło lub token); system je zapamięta,
|
||||||
- zainstaluje brakujące narzędzia za Twoją zgodą: Git (Windows: przez winget; macOS: Apple Command Line Tools
|
- zainstaluje brakujące narzędzia za Twoją zgodą: Git (Windows: przez winget; macOS: Apple Command Line Tools
|
||||||
- po ich instalacji uruchom aktualizację jeszcze raz) oraz `uv` (menedżer Pythona, tylko dla bieżącego
|
- po ich instalacji uruchom aktualizację jeszcze raz) oraz `uv` (menedżer Pythona, tylko dla bieżącego
|
||||||
użytkownika),
|
użytkownika),
|
||||||
- pobierze biblioteki Pythona (1–2 minuty, potrzebny internet).
|
- pobierze biblioteki Pythona (1–2 minuty, potrzebny internet).
|
||||||
4. Uruchom program plikiem `run_...`.
|
4. Uruchom program plikiem `run_...`.
|
||||||
|
|
||||||
**macOS:** jeśli Finder odpowie, że pliku nie można uruchomić (zdarza się po rozpakowaniu zip), otwórz Terminal,
|
**macOS:** jeśli Finder odpowie, że pliku nie można uruchomić (zdarza się po rozpakowaniu zip), otwórz Terminal,
|
||||||
wpisz `bash ` (ze spacją), przeciągnij `update_macos.command` do okna i naciśnij Enter. Po pierwszej aktualizacji
|
wpisz `bash ` (ze spacją), przeciągnij `update_macos.command` do okna i naciśnij Enter. Po pierwszej aktualizacji
|
||||||
oba pliki `.command` dają się już otwierać dwuklikiem.
|
oba pliki `.command` dają się już otwierać dwuklikiem.
|
||||||
|
|
||||||
Zamiast zip można też zrobić `git clone https://gitea.kota-app.com/kkallas/kota-technician-tool.git` i dalej
|
Zamiast zip można też zrobić `git clone https://gitea.kota-app.com/kkallas/kota-technician-tool.git` i dalej
|
||||||
używać tych samych dwóch plików.
|
używać tych samych dwóch plików.
|
||||||
|
|
||||||
Konkretna starsza wersja (np. do serwisu nietypowego boxa): w folderze narzędzia `git switch --detach v0.8`;
|
Konkretna starsza wersja (np. do serwisu nietypowego boxa): w folderze narzędzia `git switch --detach v0.8`;
|
||||||
kolejna aktualizacja wraca do najnowszej.
|
kolejna aktualizacja wraca do najnowszej.
|
||||||
|
|
||||||
Wszystkie wersje używają jednego środowiska Pythona poza folderem narzędzia:
|
Wszystkie wersje używają jednego środowiska Pythona poza folderem narzędzia:
|
||||||
`%LOCALAPPDATA%\KotaTechnicianTool\venv` (Windows), `~/Library/Caches/KotaTechnicianTool/venv` (macOS).
|
`%LOCALAPPDATA%\KotaTechnicianTool\venv` (Windows), `~/Library/Caches/KotaTechnicianTool/venv` (macOS).
|
||||||
Stare środowiska `venv-0.x` z poprzednich wersji można usunąć.
|
Stare środowiska `venv-0.x` z poprzednich wersji można usunąć.
|
||||||
|
|
||||||
Sesje, kopie zapasowe flash i ustawienia są w `~/KotaTechnicianTool` (Windows: `C:\Users\<użytkownik>\KotaTechnicianTool`).
|
Sesje, kopie zapasowe flash i ustawienia są w `~/KotaTechnicianTool` (Windows: `C:\Users\<użytkownik>\KotaTechnicianTool`).
|
||||||
|
|
||||||
## Port sensorboxa
|
## Port sensorboxa
|
||||||
|
|
||||||
- Windows: `COMx - Sensorbox (native USB) [MAC]`
|
- Windows: `COMx - Sensorbox (native USB) [MAC]`
|
||||||
- macOS: `/dev/cu.usbmodemXXXX - 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
|
Kabel USB musi przenosić dane (nie tylko ładowanie). Przy restartach z komunikatem o brownout użyj innego portu
|
||||||
lub zasilacza.
|
lub zasilacza.
|
||||||
|
|
||||||
## Firmware
|
## Firmware
|
||||||
|
|
||||||
Wgrać można tylko pliki `.bin` z folderu `firmware/`. Lista pokazuje datę kompilacji zapisaną w pliku,
|
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**.
|
najnowszy build jest na górze. Nowy build: wrzuć plik do `firmware/` i kliknij **Refresh list**.
|
||||||
|
|
||||||
## Dla zespołu
|
## Dla zespołu
|
||||||
|
|
||||||
- Praca nad zmianą: gałąź (`git switch -c feature/<nazwa>`) → commity z przechodzącymi testami →
|
- Praca nad zmianą: gałąź (`git switch -c feature/<nazwa>`) → commity z przechodzącymi testami →
|
||||||
`git push -u origin feature/<nazwa>` → pull request na Gitea → merge do `main`.
|
`git push -u origin feature/<nazwa>` → pull request na Gitea → merge do `main`.
|
||||||
- Wydanie wersji: numer w `pyproject.toml`, `kota_tech/__init__.py` i `uv.lock`, tag `vX.Y`
|
- Wydanie wersji: numer w `pyproject.toml`, `kota_tech/__init__.py` i `uv.lock`, tag `vX.Y`
|
||||||
(`git tag -a vX.Y -m "Technician tool vX.Y"`, `git push origin vX.Y`), opis w **Releases** na Gitea.
|
(`git tag -a vX.Y -m "Technician tool vX.Y"`, `git push origin vX.Y`), opis w **Releases** na Gitea.
|
||||||
Aktualizacja techników bierze **tylko tagi `v*`** – zmiany w `main` bez tagu do nich nie trafiają.
|
Aktualizacja techników bierze **tylko tagi `v*`** – zmiany w `main` bez tagu do nich nie trafiają.
|
||||||
- Nie commitujemy `ENV.TXT` z prawdziwym tokenem ani haseł Wi-Fi.
|
- Nie commitujemy `ENV.TXT` z prawdziwym tokenem ani haseł Wi-Fi.
|
||||||
- Testy:
|
- Testy:
|
||||||
|
|
||||||
```
|
```
|
||||||
uv run --frozen pytest -q
|
uv run --frozen pytest -q
|
||||||
```
|
```
|
||||||
|
|
||||||
Zmiany w wersjach: `docs/CHANGES-v0.*.md`; historia v0.1–v0.8 jest w tagach gita.
|
Zmiany w wersjach: `docs/CHANGES-v0.*.md`; historia v0.1–v0.8 jest w tagach gita.
|
||||||
+202
-202
@@ -1,202 +1,202 @@
|
|||||||
"""Serial byte stream -> framed, cleaned, parsed log lines.
|
"""Serial byte stream -> framed, cleaned, parsed log lines.
|
||||||
|
|
||||||
ESP-IDF log format: "<L> (<ms since boot>) <TAG>: <message>", optionally
|
ESP-IDF log format: "<L> (<ms since boot>) <TAG>: <message>", optionally
|
||||||
wrapped in ANSI colour codes. ROM/bootloader output (boot banner, reset
|
wrapped in ANSI colour codes. ROM/bootloader output (boot banner, reset
|
||||||
reason) has no level prefix and is classified separately, since a boot
|
reason) has no level prefix and is classified separately, since a boot
|
||||||
banner is the only reliable reboot marker.
|
banner is the only reliable reboot marker.
|
||||||
|
|
||||||
Firmware 1.0.16+ adds structured diagnostic lines logged under the "KOTA"
|
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")
|
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] ").
|
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
|
Both are parsed here so the diagnostics engine reads fields directly
|
||||||
instead of matching message text.
|
instead of matching message text.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
import re
|
import re
|
||||||
import time
|
import time
|
||||||
from dataclasses import dataclass, field
|
from dataclasses import dataclass, field
|
||||||
from enum import Enum
|
from enum import Enum
|
||||||
|
|
||||||
from .redact import redact
|
from .redact import redact
|
||||||
|
|
||||||
ANSI_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
|
ANSI_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
|
||||||
ESP_LOG_RE = re.compile(r"^([EWIDV]) \((\d+)\) ([^:]{1,40}?): ?(.*)$")
|
ESP_LOG_RE = re.compile(r"^([EWIDV]) \((\d+)\) ([^:]{1,40}?): ?(.*)$")
|
||||||
# ESP32-S3 ROM prints e.g. "ESP-ROM:esp32s3-20210327" then
|
# ESP32-S3 ROM prints e.g. "ESP-ROM:esp32s3-20210327" then
|
||||||
# "rst:0x1 (POWERON),boot:0x8 (SPI_FAST_FLASH_BOOT)".
|
# "rst:0x1 (POWERON),boot:0x8 (SPI_FAST_FLASH_BOOT)".
|
||||||
BOOT_BANNER_RE = re.compile(r"^ESP-ROM:")
|
BOOT_BANNER_RE = re.compile(r"^ESP-ROM:")
|
||||||
RESET_REASON_RE = re.compile(r"^rst:0x([0-9a-fA-F]+) \(([A-Z0-9_]+)\)")
|
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).
|
# "[E-SD-03] Failed to initialize the card ..." (firmware error_ids.csv).
|
||||||
ERROR_ID_RE = re.compile(r"^\[(E-[A-Z0-9]+-\d{2,})\] ?")
|
ERROR_ID_RE = re.compile(r"^\[(E-[A-Z0-9]+-\d{2,})\] ?")
|
||||||
KOTA_TAG = "KOTA"
|
KOTA_TAG = "KOTA"
|
||||||
PANIC_RE = re.compile(
|
PANIC_RE = re.compile(
|
||||||
r"Guru Meditation Error|abort\(\) was called|ESP_ERROR_CHECK failed|"
|
r"Guru Meditation Error|abort\(\) was called|ESP_ERROR_CHECK failed|"
|
||||||
r"^Backtrace:|Rebooting\.\.\.$"
|
r"^Backtrace:|Rebooting\.\.\.$"
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|
||||||
class LineKind(str, Enum):
|
class LineKind(str, Enum):
|
||||||
LOG = "log" # ESP_LOGx line
|
LOG = "log" # ESP_LOGx line
|
||||||
BOOT = "boot" # ROM boot banner (start of a new boot)
|
BOOT = "boot" # ROM boot banner (start of a new boot)
|
||||||
RESET = "reset" # ROM reset-reason line
|
RESET = "reset" # ROM reset-reason line
|
||||||
PANIC = "panic" # crash / abort output
|
PANIC = "panic" # crash / abort output
|
||||||
KOTA = "kota" # structured "KOTA: <record> key=value ..." line
|
KOTA = "kota" # structured "KOTA: <record> key=value ..." line
|
||||||
RAW = "raw" # anything else (task list rows, line protocol, ...)
|
RAW = "raw" # anything else (task list rows, line protocol, ...)
|
||||||
HOST = "host" # event generated by this tool (connect, reset, ...)
|
HOST = "host" # event generated by this tool (connect, reset, ...)
|
||||||
|
|
||||||
|
|
||||||
def host_event(text: str) -> LogLine:
|
def host_event(text: str) -> LogLine:
|
||||||
return LogLine(f"--- {text} ---", LineKind.HOST)
|
return LogLine(f"--- {text} ---", LineKind.HOST)
|
||||||
|
|
||||||
|
|
||||||
@dataclass(frozen=True)
|
@dataclass(frozen=True)
|
||||||
class LogLine:
|
class LogLine:
|
||||||
text: str # cleaned + redacted
|
text: str # cleaned + redacted
|
||||||
kind: LineKind
|
kind: LineKind
|
||||||
host_time: float = field(default_factory=time.time)
|
host_time: float = field(default_factory=time.time)
|
||||||
level: str | None = None # E/W/I/D/V for LOG lines
|
level: str | None = None # E/W/I/D/V for LOG lines
|
||||||
uptime_ms: int | None = None
|
uptime_ms: int | None = None
|
||||||
tag: str | None = None
|
tag: str | None = None
|
||||||
message: str | None = None
|
message: str | None = None
|
||||||
reset_reason: str | None = None
|
reset_reason: str | None = None
|
||||||
error_id: str | None = None # "E-SD-03" when the message carries one
|
error_id: str | None = None # "E-SD-03" when the message carries one
|
||||||
record: str | None = None # KOTA lines: "boot", "i2c", "health", ...
|
record: str | None = None # KOTA lines: "boot", "i2c", "health", ...
|
||||||
fields: dict[str, str] = field(default_factory=dict) # KOTA key=value pairs
|
fields: dict[str, str] = field(default_factory=dict) # KOTA key=value pairs
|
||||||
words: tuple[str, ...] = () # KOTA bare words ("verify", "OK", "->", ...)
|
words: tuple[str, ...] = () # KOTA bare words ("verify", "OK", "->", ...)
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def match_text(self) -> str:
|
def match_text(self) -> str:
|
||||||
"""Text for message rules: the error-ID prefix removed, so rules
|
"""Text for message rules: the error-ID prefix removed, so rules
|
||||||
written for older firmware keep matching."""
|
written for older firmware keep matching."""
|
||||||
if self.error_id and self.message is not None and self.tag:
|
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.replace(f"[{self.error_id}] ", "", 1)
|
||||||
return self.text
|
return self.text
|
||||||
|
|
||||||
|
|
||||||
def parse_kota(body: str) -> tuple[str, dict[str, str], tuple[str, ...]]:
|
def parse_kota(body: str) -> tuple[str, dict[str, str], tuple[str, ...]]:
|
||||||
"""'rtc verify running=1 delta=2s ok=1' -> ('rtc', {...}, ('verify',)).
|
"""'rtc verify running=1 delta=2s ok=1' -> ('rtc', {...}, ('verify',)).
|
||||||
|
|
||||||
Values never contain spaces. The mic line has a parenthesised aside
|
Values never contain spaces. The mic line has a parenthesised aside
|
||||||
("(GPIO3=1, expected 1)"): brackets and commas are stripped from keys
|
("(GPIO3=1, expected 1)"): brackets and commas are stripped from keys
|
||||||
and values, and the aside's words are kept as bare words.
|
and values, and the aside's words are kept as bare words.
|
||||||
"""
|
"""
|
||||||
tokens = body.split()
|
tokens = body.split()
|
||||||
if not tokens:
|
if not tokens:
|
||||||
return "", {}, ()
|
return "", {}, ()
|
||||||
fields: dict[str, str] = {}
|
fields: dict[str, str] = {}
|
||||||
words: list[str] = []
|
words: list[str] = []
|
||||||
for tok in tokens[1:]:
|
for tok in tokens[1:]:
|
||||||
key, eq, value = tok.partition("=")
|
key, eq, value = tok.partition("=")
|
||||||
if eq and key.strip("(,"):
|
if eq and key.strip("(,"):
|
||||||
key = key.lstrip("(")
|
key = key.lstrip("(")
|
||||||
# "0x68=DS1307(missing)" keeps its bracket; "(GPIO3=1," loses it.
|
# "0x68=DS1307(missing)" keeps its bracket; "(GPIO3=1," loses it.
|
||||||
value = value.rstrip(",")
|
value = value.rstrip(",")
|
||||||
if tok.startswith("(") or value.endswith(")") and "(" not in value:
|
if tok.startswith("(") or value.endswith(")") and "(" not in value:
|
||||||
value = value.rstrip(")")
|
value = value.rstrip(")")
|
||||||
fields[key] = value
|
fields[key] = value
|
||||||
else:
|
else:
|
||||||
words.append(tok.strip("(),"))
|
words.append(tok.strip("(),"))
|
||||||
return tokens[0], fields, tuple(w for w in words if w)
|
return tokens[0], fields, tuple(w for w in words if w)
|
||||||
|
|
||||||
|
|
||||||
def clean(raw: str) -> str:
|
def clean(raw: str) -> str:
|
||||||
return ANSI_RE.sub("", raw).replace("\r", "").rstrip()
|
return ANSI_RE.sub("", raw).replace("\r", "").rstrip()
|
||||||
|
|
||||||
|
|
||||||
def parse_line(raw: str, host_time: float | None = None) -> LogLine:
|
def parse_line(raw: str, host_time: float | None = None) -> LogLine:
|
||||||
text = redact(clean(raw))
|
text = redact(clean(raw))
|
||||||
t = time.time() if host_time is None else host_time
|
t = time.time() if host_time is None else host_time
|
||||||
if m := ESP_LOG_RE.match(text):
|
if m := ESP_LOG_RE.match(text):
|
||||||
level, ms, tag, msg = m.groups()
|
level, ms, tag, msg = m.groups()
|
||||||
tag = tag.strip()
|
tag = tag.strip()
|
||||||
if tag == KOTA_TAG:
|
if tag == KOTA_TAG:
|
||||||
record, fields, words = parse_kota(msg)
|
record, fields, words = parse_kota(msg)
|
||||||
return LogLine(text, LineKind.KOTA, t, level, int(ms), tag, msg,
|
return LogLine(text, LineKind.KOTA, t, level, int(ms), tag, msg,
|
||||||
record=record, fields=fields, words=words)
|
record=record, fields=fields, words=words)
|
||||||
eid = None
|
eid = None
|
||||||
if em := ERROR_ID_RE.match(msg):
|
if em := ERROR_ID_RE.match(msg):
|
||||||
eid, msg = em.group(1), msg[em.end():]
|
eid, msg = em.group(1), msg[em.end():]
|
||||||
return LogLine(text, LineKind.LOG, t, level, int(ms), tag, msg, error_id=eid)
|
return LogLine(text, LineKind.LOG, t, level, int(ms), tag, msg, error_id=eid)
|
||||||
if BOOT_BANNER_RE.match(text):
|
if BOOT_BANNER_RE.match(text):
|
||||||
return LogLine(text, LineKind.BOOT, t)
|
return LogLine(text, LineKind.BOOT, t)
|
||||||
if m := RESET_REASON_RE.match(text):
|
if m := RESET_REASON_RE.match(text):
|
||||||
return LogLine(text, LineKind.RESET, t, reset_reason=m.group(2))
|
return LogLine(text, LineKind.RESET, t, reset_reason=m.group(2))
|
||||||
if PANIC_RE.search(text):
|
if PANIC_RE.search(text):
|
||||||
return LogLine(text, LineKind.PANIC, t)
|
return LogLine(text, LineKind.PANIC, t)
|
||||||
return LogLine(text, LineKind.RAW, t)
|
return LogLine(text, LineKind.RAW, t)
|
||||||
|
|
||||||
|
|
||||||
class LineFramer:
|
class LineFramer:
|
||||||
"""Accumulates bytes and yields complete lines.
|
"""Accumulates bytes and yields complete lines.
|
||||||
|
|
||||||
A partial line is released after `idle_flush_s` without new bytes so
|
A partial line is released after `idle_flush_s` without new bytes so
|
||||||
prompts / unterminated output are not held back forever.
|
prompts / unterminated output are not held back forever.
|
||||||
|
|
||||||
Lines are also split where a new log line starts in the middle
|
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
|
("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
|
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
|
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
|
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
|
is stale and dropped. Timing cannot identify it, because the FIFO only
|
||||||
flushes when the board next prints, possibly seconds later.
|
flushes when the board next prints, possibly seconds later.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
def __init__(self, idle_flush_s: float = 0.3, max_line: int = 4096,
|
def __init__(self, idle_flush_s: float = 0.3, max_line: int = 4096,
|
||||||
drop_first_partial: bool = False):
|
drop_first_partial: bool = False):
|
||||||
self._buf = bytearray()
|
self._buf = bytearray()
|
||||||
self._last_rx = 0.0
|
self._last_rx = 0.0
|
||||||
self.idle_flush_s = idle_flush_s
|
self.idle_flush_s = idle_flush_s
|
||||||
self.max_line = max_line
|
self.max_line = max_line
|
||||||
self._first_line_pending = drop_first_partial
|
self._first_line_pending = drop_first_partial
|
||||||
|
|
||||||
def cancel_drop(self) -> None:
|
def cancel_drop(self) -> None:
|
||||||
self._first_line_pending = False
|
self._first_line_pending = False
|
||||||
|
|
||||||
def feed(self, data: bytes, now: float | None = None) -> list[str]:
|
def feed(self, data: bytes, now: float | None = None) -> list[str]:
|
||||||
now = time.monotonic() if now is None else now
|
now = time.monotonic() if now is None else now
|
||||||
if data:
|
if data:
|
||||||
self._buf.extend(data)
|
self._buf.extend(data)
|
||||||
self._last_rx = now
|
self._last_rx = now
|
||||||
out: list[str] = []
|
out: list[str] = []
|
||||||
while (i := self._buf.find(b"\n")) >= 0:
|
while (i := self._buf.find(b"\n")) >= 0:
|
||||||
out += self._emit(self._buf[:i])
|
out += self._emit(self._buf[:i])
|
||||||
del self._buf[: i + 1]
|
del self._buf[: i + 1]
|
||||||
if len(self._buf) >= self.max_line:
|
if len(self._buf) >= self.max_line:
|
||||||
out += self._emit(self._buf)
|
out += self._emit(self._buf)
|
||||||
self._buf.clear()
|
self._buf.clear()
|
||||||
return out
|
return out
|
||||||
|
|
||||||
def poll_idle(self, now: float | None = None) -> list[str]:
|
def poll_idle(self, now: float | None = None) -> list[str]:
|
||||||
now = time.monotonic() if now is None else now
|
now = time.monotonic() if now is None else now
|
||||||
if self._buf and now - self._last_rx >= self.idle_flush_s:
|
if self._buf and now - self._last_rx >= self.idle_flush_s:
|
||||||
return self.flush()
|
return self.flush()
|
||||||
return []
|
return []
|
||||||
|
|
||||||
def flush(self) -> list[str]:
|
def flush(self) -> list[str]:
|
||||||
if not self._buf:
|
if not self._buf:
|
||||||
return []
|
return []
|
||||||
out = self._emit(self._buf)
|
out = self._emit(self._buf)
|
||||||
self._buf.clear()
|
self._buf.clear()
|
||||||
return out
|
return out
|
||||||
|
|
||||||
def _emit(self, raw: bytes | bytearray) -> list[str]:
|
def _emit(self, raw: bytes | bytearray) -> list[str]:
|
||||||
parts = split_glued(bytes(raw).decode("utf-8", errors="replace"))
|
parts = split_glued(bytes(raw).decode("utf-8", errors="replace"))
|
||||||
if self._first_line_pending:
|
if self._first_line_pending:
|
||||||
self._first_line_pending = False
|
self._first_line_pending = False
|
||||||
if len(parts) > 1:
|
if len(parts) > 1:
|
||||||
parts = parts[1:] # stale FIFO fragment from before the open
|
parts = parts[1:] # stale FIFO fragment from before the open
|
||||||
return parts
|
return parts
|
||||||
|
|
||||||
|
|
||||||
# Start of a log line (optionally ANSI-coloured) or ROM banner.
|
# 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:)")
|
_LINE_START = re.compile(r"(?:\x1b\[[0-9;]*m)?(?:[EWIDV] \(\d+\) \S|ESP-ROM:)")
|
||||||
|
|
||||||
|
|
||||||
def split_glued(text: str) -> list[str]:
|
def split_glued(text: str) -> list[str]:
|
||||||
# Left-to-right scan so an ANSI colour prefix stays with its line.
|
# 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]
|
cuts = [m.start() for m in _LINE_START.finditer(text) if m.start() > 0]
|
||||||
if not cuts:
|
if not cuts:
|
||||||
return [text]
|
return [text]
|
||||||
bounds = [0, *cuts, len(text)]
|
bounds = [0, *cuts, len(text)]
|
||||||
return [text[a:b] for a, b in zip(bounds, bounds[1:]) if a < b]
|
return [text[a:b] for a, b in zip(bounds, bounds[1:]) if a < b]
|
||||||
+999
-999
File diff suppressed because it is too large.
Load diff
+147
-147
@@ -1,147 +1,147 @@
|
|||||||
"""Firmware identification from the boot log.
|
"""Firmware identification from the boot log.
|
||||||
|
|
||||||
Up to firmware 1.0 the app version string was "1.0" in every build, so
|
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
|
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
|
receive new firmware over OTA; an unknown SHA usually means a box has already
|
||||||
updated.
|
updated.
|
||||||
|
|
||||||
Firmware 1.0.16+ prints "KOTA: boot fw=1.0.16 build=4f10989e ..." (version
|
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
|
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
|
tool's firmware/ folder are registered with `register_local_build` so the
|
||||||
box's build can be shown with its compile date.
|
box's build can be shown with its compile date.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
import re
|
import re
|
||||||
from dataclasses import dataclass, field
|
from dataclasses import dataclass, field
|
||||||
|
|
||||||
|
|
||||||
@dataclass(frozen=True)
|
@dataclass(frozen=True)
|
||||||
class KnownFirmware:
|
class KnownFirmware:
|
||||||
name: str
|
name: str
|
||||||
source: str
|
source: str
|
||||||
sd_wifi: bool # reads SSID/PASSWORD from ENV.TXT
|
sd_wifi: bool # reads SSID/PASSWORD from ENV.TXT
|
||||||
setup_portal: bool # short press -> Wi-Fi setup portal
|
setup_portal: bool # short press -> Wi-Fi setup portal
|
||||||
|
|
||||||
|
|
||||||
KNOWN: dict[str, KnownFirmware] = {
|
KNOWN: dict[str, KnownFirmware] = {
|
||||||
"45fa9d5b9": KnownFirmware(
|
"45fa9d5b9": KnownFirmware(
|
||||||
name="v1.0 (built Jun 29 2026)",
|
name="v1.0 (built Jun 29 2026)",
|
||||||
source="factory image new_system.bin",
|
source="factory image new_system.bin",
|
||||||
sd_wifi=False,
|
sd_wifi=False,
|
||||||
setup_portal=False,
|
setup_portal=False,
|
||||||
),
|
),
|
||||||
"c94ba0e9b": KnownFirmware(
|
"c94ba0e9b": KnownFirmware(
|
||||||
name="v1.0 source build (Sep 26 2026)",
|
name="v1.0 source build (Sep 26 2026)",
|
||||||
source="developer build, built by Krzysztof Kallas",
|
source="developer build, built by Krzysztof Kallas",
|
||||||
sd_wifi=True,
|
sd_wifi=True,
|
||||||
setup_portal=True,
|
setup_portal=True,
|
||||||
),
|
),
|
||||||
}
|
}
|
||||||
|
|
||||||
# elf sha (full or prefix) -> (version, compile time, file name) of builds in firmware/
|
# elf sha (full or prefix) -> (version, compile time, file name) of builds in firmware/
|
||||||
LOCAL_BUILDS: dict[str, tuple[str, str, str]] = {}
|
LOCAL_BUILDS: dict[str, tuple[str, str, str]] = {}
|
||||||
|
|
||||||
|
|
||||||
def register_local_build(elf_sha: str, version: str, built: str, file_name: str) -> None:
|
def register_local_build(elf_sha: str, version: str, built: str, file_name: str) -> None:
|
||||||
LOCAL_BUILDS[elf_sha.lower()] = (version, built, file_name)
|
LOCAL_BUILDS[elf_sha.lower()] = (version, built, file_name)
|
||||||
|
|
||||||
|
|
||||||
def same_build(a: str | None, b: str | None) -> bool:
|
def same_build(a: str | None, b: str | None) -> bool:
|
||||||
"""ELF SHA prefixes of different lengths (8 from KOTA: boot, 9+ from
|
"""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."""
|
app_init, 64 from an image) name the same build if they agree."""
|
||||||
if not a or not b:
|
if not a or not b:
|
||||||
return False
|
return False
|
||||||
n = min(len(a), len(b))
|
n = min(len(a), len(b))
|
||||||
return n >= 6 and a[:n].lower() == b[:n].lower()
|
return n >= 6 and a[:n].lower() == b[:n].lower()
|
||||||
|
|
||||||
|
|
||||||
def local_build(elf_sha: str | None) -> tuple[str, str, str] | None:
|
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)
|
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,})")
|
_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+)")
|
_VER = re.compile(r"app_init: App version:\s+(?P<v>\S+)")
|
||||||
_BUILT = re.compile(r"app_init: Compile time:\s+(?P<t>.+)$")
|
_BUILT = re.compile(r"app_init: Compile time:\s+(?P<t>.+)$")
|
||||||
_IDF = re.compile(r"app_init: ESP-IDF:\s+(?P<v>\S+)")
|
_IDF = re.compile(r"app_init: ESP-IDF:\s+(?P<v>\S+)")
|
||||||
# Evidence of features, for builds not in KNOWN.
|
# Evidence of features, for builds not in KNOWN.
|
||||||
_FEATURE_SD_WIFI = re.compile(r"WIFI_CREDENTIALS: ")
|
_FEATURE_SD_WIFI = re.compile(r"WIFI_CREDENTIALS: ")
|
||||||
_FEATURE_PORTAL = re.compile(r"WIFI_PROVISIONING: |Short press: ")
|
_FEATURE_PORTAL = re.compile(r"WIFI_PROVISIONING: |Short press: ")
|
||||||
# Deployed v1.0 logs the SD mount under the INFLUX_BUFFER tag.
|
# Deployed v1.0 logs the SD mount under the INFLUX_BUFFER tag.
|
||||||
_LEGACY_SD_TAG = re.compile(r"INFLUX_BUFFER: SD card mounted")
|
_LEGACY_SD_TAG = re.compile(r"INFLUX_BUFFER: SD card mounted")
|
||||||
|
|
||||||
|
|
||||||
@dataclass
|
@dataclass
|
||||||
class FirmwareInfo:
|
class FirmwareInfo:
|
||||||
elf_sha: str | None = None
|
elf_sha: str | None = None
|
||||||
version: str | None = None
|
version: str | None = None
|
||||||
built: str | None = None
|
built: str | None = None
|
||||||
idf: str | None = None
|
idf: str | None = None
|
||||||
hw: str | None = None
|
hw: str | None = None
|
||||||
evidence: set[str] = field(default_factory=set)
|
evidence: set[str] = field(default_factory=set)
|
||||||
|
|
||||||
def observe_kota(self, fields: dict[str, str]) -> None:
|
def observe_kota(self, fields: dict[str, str]) -> None:
|
||||||
"""'KOTA: boot fw=1.0.16 build=4f10989e hw=2 ...'"""
|
"""'KOTA: boot fw=1.0.16 build=4f10989e hw=2 ...'"""
|
||||||
if fields.get("fw"):
|
if fields.get("fw"):
|
||||||
self.version = fields["fw"]
|
self.version = fields["fw"]
|
||||||
build = fields.get("build", "")
|
build = fields.get("build", "")
|
||||||
# app_init's longer prefix is kept if it agrees.
|
# app_init's longer prefix is kept if it agrees.
|
||||||
if build and not same_build(self.elf_sha, build):
|
if build and not same_build(self.elf_sha, build):
|
||||||
self.elf_sha = build.lower()
|
self.elf_sha = build.lower()
|
||||||
if fields.get("hw"):
|
if fields.get("hw"):
|
||||||
self.hw = fields["hw"]
|
self.hw = fields["hw"]
|
||||||
self.evidence.add("kota") # 1.0.16+: SD Wi-Fi and setup portal exist
|
self.evidence.add("kota") # 1.0.16+: SD Wi-Fi and setup portal exist
|
||||||
|
|
||||||
def observe(self, text: str) -> None:
|
def observe(self, text: str) -> None:
|
||||||
if m := _ELF.search(text):
|
if m := _ELF.search(text):
|
||||||
self.elf_sha = m.group("sha")
|
self.elf_sha = m.group("sha")
|
||||||
elif m := _VER.search(text):
|
elif m := _VER.search(text):
|
||||||
self.version = m.group("v")
|
self.version = m.group("v")
|
||||||
elif m := _BUILT.search(text):
|
elif m := _BUILT.search(text):
|
||||||
self.built = m.group("t").strip()
|
self.built = m.group("t").strip()
|
||||||
elif m := _IDF.search(text):
|
elif m := _IDF.search(text):
|
||||||
self.idf = m.group("v")
|
self.idf = m.group("v")
|
||||||
if _FEATURE_SD_WIFI.search(text):
|
if _FEATURE_SD_WIFI.search(text):
|
||||||
self.evidence.add("sd_wifi")
|
self.evidence.add("sd_wifi")
|
||||||
if _FEATURE_PORTAL.search(text):
|
if _FEATURE_PORTAL.search(text):
|
||||||
self.evidence.add("setup_portal")
|
self.evidence.add("setup_portal")
|
||||||
if _LEGACY_SD_TAG.search(text):
|
if _LEGACY_SD_TAG.search(text):
|
||||||
self.evidence.add("legacy_v1")
|
self.evidence.add("legacy_v1")
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def known(self) -> KnownFirmware | None:
|
def known(self) -> KnownFirmware | None:
|
||||||
if not self.elf_sha:
|
if not self.elf_sha:
|
||||||
return None
|
return None
|
||||||
return next((k for sha, k in KNOWN.items() if same_build(self.elf_sha, sha)), None)
|
return next((k for sha, k in KNOWN.items() if same_build(self.elf_sha, sha)), None)
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def supports_sd_wifi(self) -> bool | None:
|
def supports_sd_wifi(self) -> bool | None:
|
||||||
"""True/False when determinable, None when unknown (no boot seen)."""
|
"""True/False when determinable, None when unknown (no boot seen)."""
|
||||||
if k := self.known:
|
if k := self.known:
|
||||||
return k.sd_wifi
|
return k.sd_wifi
|
||||||
if "sd_wifi" in self.evidence or "kota" in self.evidence:
|
if "sd_wifi" in self.evidence or "kota" in self.evidence:
|
||||||
return True
|
return True
|
||||||
if "legacy_v1" in self.evidence:
|
if "legacy_v1" in self.evidence:
|
||||||
return False
|
return False
|
||||||
return None
|
return None
|
||||||
|
|
||||||
def describe(self) -> str:
|
def describe(self) -> str:
|
||||||
if k := self.known:
|
if k := self.known:
|
||||||
return f"{k.name} - {k.source}"
|
return f"{k.name} - {k.source}"
|
||||||
if self.elf_sha and (self.version not in (None, "1.0") or local_build(self.elf_sha)):
|
if self.elf_sha and (self.version not in (None, "1.0") or local_build(self.elf_sha)):
|
||||||
local = local_build(self.elf_sha)
|
local = local_build(self.elf_sha)
|
||||||
built = self.built or (local[1] if local else None)
|
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"v{self.version or (local[0] if local else '?')} (build {self.elf_sha[:8]}"
|
||||||
text += f", compiled {built})" if built else ")"
|
text += f", compiled {built})" if built else ")"
|
||||||
if self.hw:
|
if self.hw:
|
||||||
text += f", hardware {self.hw}"
|
text += f", hardware {self.hw}"
|
||||||
if local:
|
if local:
|
||||||
text += f" - same as firmware/{local[2]}"
|
text += f" - same as firmware/{local[2]}"
|
||||||
return text
|
return text
|
||||||
if self.elf_sha:
|
if self.elf_sha:
|
||||||
built = f", built {self.built}" if self.built else ""
|
built = f", built {self.built}" if self.built else ""
|
||||||
return f"Unknown build {self.elf_sha[:9]}{built} (probably updated over OTA)"
|
return f"Unknown build {self.elf_sha[:9]}{built} (probably updated over OTA)"
|
||||||
if "legacy_v1" in self.evidence:
|
if "legacy_v1" in self.evidence:
|
||||||
return "Probably v1.0 factory image (press Reset & capture to confirm)"
|
return "Probably v1.0 factory image (press Reset & capture to confirm)"
|
||||||
return "Not identified yet - press Reset & capture"
|
return "Not identified yet - press Reset & capture"
|
||||||
+401
-401
@@ -1,401 +1,401 @@
|
|||||||
"""Guided troubleshooting: executes the decision trees in guides.toml.
|
"""Guided troubleshooting: executes the decision trees in guides.toml.
|
||||||
|
|
||||||
GUI-independent. The runner is fed the same LogLines as the diagnostics
|
GUI-independent. The runner is fed the same LogLines as the diagnostics
|
||||||
engine, reads the engine's report to route and to skip questions the log
|
engine, reads the engine's report to route and to skip questions the log
|
||||||
already answers, asks the host to perform tool actions (board reset), and
|
already answers, asks the host to perform tool actions (board reset), and
|
||||||
records every answer and conclusion in the engine so they appear in the
|
records every answer and conclusion in the engine so they appear in the
|
||||||
report and the session log.
|
report and the session log.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
import re
|
import re
|
||||||
import time
|
import time
|
||||||
import tomllib
|
import tomllib
|
||||||
from collections.abc import Callable
|
from collections.abc import Callable
|
||||||
from dataclasses import dataclass, field
|
from dataclasses import dataclass, field
|
||||||
from pathlib import Path
|
from pathlib import Path
|
||||||
|
|
||||||
from ..core.logline import LogLine
|
from ..core.logline import LogLine
|
||||||
from .engine import LED, DiagnosticsEngine, Severity
|
from .engine import LED, DiagnosticsEngine, Severity
|
||||||
|
|
||||||
GUIDES_PATH = Path(__file__).with_name("guides.toml")
|
GUIDES_PATH = Path(__file__).with_name("guides.toml")
|
||||||
# LED answers a technician can give (engine colours + a reboot-loop pattern).
|
# LED answers a technician can give (engine colours + a reboot-loop pattern).
|
||||||
LED_ANSWERS = ["GREEN", "PURPLE", "RED", "BLUE", "WHITE", "YELLOW", "ORANGE", "CYAN", "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()},
|
LED_ANSWER_LABELS = {**{k: v[0] for k, v in LED.items()},
|
||||||
"CYCLING": "Keeps changing / goes dark every few seconds"}
|
"CYCLING": "Keeps changing / goes dark every few seconds"}
|
||||||
STEP_TYPES = {"led", "question", "info", "wait", "route"}
|
STEP_TYPES = {"led", "question", "info", "wait", "route"}
|
||||||
END_SEVERITY = {"ok": None, "info": Severity.INFO, "warning": Severity.WARNING,
|
END_SEVERITY = {"ok": None, "info": Severity.INFO, "warning": Severity.WARNING,
|
||||||
"error": Severity.ERROR, "critical": Severity.CRITICAL}
|
"error": Severity.ERROR, "critical": Severity.CRITICAL}
|
||||||
|
|
||||||
|
|
||||||
@dataclass(frozen=True)
|
@dataclass(frozen=True)
|
||||||
class Option:
|
class Option:
|
||||||
label: str
|
label: str
|
||||||
next: str
|
next: str
|
||||||
|
|
||||||
|
|
||||||
@dataclass(frozen=True)
|
@dataclass(frozen=True)
|
||||||
class Step:
|
class Step:
|
||||||
id: str
|
id: str
|
||||||
type: str
|
type: str
|
||||||
text: str = ""
|
text: str = ""
|
||||||
options: tuple[Option, ...] = ()
|
options: tuple[Option, ...] = ()
|
||||||
route: dict[str, str] = field(default_factory=dict) # led colour -> target
|
route: dict[str, str] = field(default_factory=dict) # led colour -> target
|
||||||
routes: dict[str, str] = field(default_factory=dict) # rule id -> target
|
routes: dict[str, str] = field(default_factory=dict) # rule id -> target
|
||||||
default: str | None = None
|
default: str | None = None
|
||||||
next: str | None = None
|
next: str | None = None
|
||||||
tool_action: str | None = None
|
tool_action: str | None = None
|
||||||
until: re.Pattern[str] | None = None
|
until: re.Pattern[str] | None = None
|
||||||
until_milestone: str | None = None
|
until_milestone: str | None = None
|
||||||
fail_on: re.Pattern[str] | None = None
|
fail_on: re.Pattern[str] | None = None
|
||||||
timeout_s: float = 60.0
|
timeout_s: float = 60.0
|
||||||
pass_on_timeout: bool = False
|
pass_on_timeout: bool = False
|
||||||
on_ok: str | None = None
|
on_ok: str | None = None
|
||||||
on_fail: str | None = None
|
on_fail: str | None = None
|
||||||
on_timeout: str | None = None
|
on_timeout: str | None = None
|
||||||
skip_if_finding: str | None = None
|
skip_if_finding: str | None = None
|
||||||
skip_unless_feature: str | None = None
|
skip_unless_feature: str | None = None
|
||||||
skip_to: str | None = None
|
skip_to: str | None = None
|
||||||
show_qr: bool = False # show the Matter pairing QR next to the step text
|
show_qr: bool = False # show the Matter pairing QR next to the step text
|
||||||
|
|
||||||
def targets(self) -> list[str]:
|
def targets(self) -> list[str]:
|
||||||
t = [o.next for o in self.options] + list(self.route.values()) + list(self.routes.values())
|
t = [o.next for o in self.options] + list(self.route.values()) + list(self.routes.values())
|
||||||
t += [x for x in (self.default, self.next, self.on_ok, self.on_fail, self.on_timeout, self.skip_to) if x]
|
t += [x for x in (self.default, self.next, self.on_ok, self.on_fail, self.on_timeout, self.skip_to) if x]
|
||||||
return t
|
return t
|
||||||
|
|
||||||
|
|
||||||
@dataclass(frozen=True)
|
@dataclass(frozen=True)
|
||||||
class End:
|
class End:
|
||||||
id: str
|
id: str
|
||||||
severity: str
|
severity: str
|
||||||
title: str
|
title: str
|
||||||
text: str
|
text: str
|
||||||
actions: tuple[str, ...] = ()
|
actions: tuple[str, ...] = ()
|
||||||
|
|
||||||
|
|
||||||
@dataclass(frozen=True)
|
@dataclass(frozen=True)
|
||||||
class Guide:
|
class Guide:
|
||||||
id: str
|
id: str
|
||||||
title: str
|
title: str
|
||||||
summary: str
|
summary: str
|
||||||
recommend: tuple[str, ...]
|
recommend: tuple[str, ...]
|
||||||
start: str
|
start: str
|
||||||
steps: dict[str, Step]
|
steps: dict[str, Step]
|
||||||
ends: dict[str, End]
|
ends: dict[str, End]
|
||||||
|
|
||||||
|
|
||||||
def load_guides(path: Path = GUIDES_PATH) -> dict[str, Guide]:
|
def load_guides(path: Path = GUIDES_PATH) -> dict[str, Guide]:
|
||||||
data = tomllib.loads(path.read_text(encoding="utf-8"))
|
data = tomllib.loads(path.read_text(encoding="utf-8"))
|
||||||
guides: dict[str, Guide] = {}
|
guides: dict[str, Guide] = {}
|
||||||
for g in data["guide"]:
|
for g in data["guide"]:
|
||||||
steps = {}
|
steps = {}
|
||||||
for s in g.get("step", []):
|
for s in g.get("step", []):
|
||||||
steps[s["id"]] = Step(
|
steps[s["id"]] = Step(
|
||||||
id=s["id"], type=s["type"], text=s.get("text", ""),
|
id=s["id"], type=s["type"], text=s.get("text", ""),
|
||||||
options=tuple(Option(o["label"], o["next"]) for o in s.get("options", ())),
|
options=tuple(Option(o["label"], o["next"]) for o in s.get("options", ())),
|
||||||
route=dict(s.get("route", {})), routes=dict(s.get("routes", {})),
|
route=dict(s.get("route", {})), routes=dict(s.get("routes", {})),
|
||||||
default=s.get("default"), next=s.get("next"), tool_action=s.get("tool_action"),
|
default=s.get("default"), next=s.get("next"), tool_action=s.get("tool_action"),
|
||||||
until=re.compile(s["until"]) if "until" in s else None,
|
until=re.compile(s["until"]) if "until" in s else None,
|
||||||
until_milestone=s.get("until_milestone"),
|
until_milestone=s.get("until_milestone"),
|
||||||
fail_on=re.compile(s["fail_on"]) if "fail_on" in s else None,
|
fail_on=re.compile(s["fail_on"]) if "fail_on" in s else None,
|
||||||
timeout_s=float(s.get("timeout_s", 60)), pass_on_timeout=bool(s.get("pass_on_timeout", False)),
|
timeout_s=float(s.get("timeout_s", 60)), pass_on_timeout=bool(s.get("pass_on_timeout", False)),
|
||||||
on_ok=s.get("on_ok"), on_fail=s.get("on_fail"), on_timeout=s.get("on_timeout"),
|
on_ok=s.get("on_ok"), on_fail=s.get("on_fail"), on_timeout=s.get("on_timeout"),
|
||||||
skip_if_finding=s.get("skip_if_finding"), skip_unless_feature=s.get("skip_unless_feature"),
|
skip_if_finding=s.get("skip_if_finding"), skip_unless_feature=s.get("skip_unless_feature"),
|
||||||
skip_to=s.get("skip_to"), show_qr=bool(s.get("show_qr", False)),
|
skip_to=s.get("skip_to"), show_qr=bool(s.get("show_qr", False)),
|
||||||
)
|
)
|
||||||
ends = {e["id"]: End(e["id"], e["severity"], e["title"], e["text"], tuple(e.get("actions", ())))
|
ends = {e["id"]: End(e["id"], e["severity"], e["title"], e["text"], tuple(e.get("actions", ())))
|
||||||
for e in g.get("end", [])}
|
for e in g.get("end", [])}
|
||||||
guides[g["id"]] = Guide(g["id"], g["title"], g["summary"], tuple(g.get("recommend", ())),
|
guides[g["id"]] = Guide(g["id"], g["title"], g["summary"], tuple(g.get("recommend", ())),
|
||||||
g["start"], steps, ends)
|
g["start"], steps, ends)
|
||||||
_validate(guides)
|
_validate(guides)
|
||||||
return guides
|
return guides
|
||||||
|
|
||||||
|
|
||||||
def _validate(guides: dict[str, Guide]) -> None:
|
def _validate(guides: dict[str, Guide]) -> None:
|
||||||
for g in guides.values():
|
for g in guides.values():
|
||||||
if g.start not in g.steps:
|
if g.start not in g.steps:
|
||||||
raise ValueError(f"guide {g.id}: start step {g.start!r} missing")
|
raise ValueError(f"guide {g.id}: start step {g.start!r} missing")
|
||||||
for s in g.steps.values():
|
for s in g.steps.values():
|
||||||
if s.type not in STEP_TYPES:
|
if s.type not in STEP_TYPES:
|
||||||
raise ValueError(f"{g.id}.{s.id}: unknown step type {s.type!r}")
|
raise ValueError(f"{g.id}.{s.id}: unknown step type {s.type!r}")
|
||||||
if s.type == "led" and set(s.route) - set(LED_ANSWERS):
|
if s.type == "led" and set(s.route) - set(LED_ANSWERS):
|
||||||
raise ValueError(f"{g.id}.{s.id}: unknown LED colours {set(s.route) - set(LED_ANSWERS)}")
|
raise ValueError(f"{g.id}.{s.id}: unknown LED colours {set(s.route) - set(LED_ANSWERS)}")
|
||||||
if s.type == "wait" and not (s.until or s.until_milestone or s.pass_on_timeout):
|
if s.type == "wait" and not (s.until or s.until_milestone or s.pass_on_timeout):
|
||||||
raise ValueError(f"{g.id}.{s.id}: wait step needs until/until_milestone/pass_on_timeout")
|
raise ValueError(f"{g.id}.{s.id}: wait step needs until/until_milestone/pass_on_timeout")
|
||||||
if s.tool_action not in (None, "reset"):
|
if s.tool_action not in (None, "reset"):
|
||||||
raise ValueError(f"{g.id}.{s.id}: unknown tool_action {s.tool_action!r}")
|
raise ValueError(f"{g.id}.{s.id}: unknown tool_action {s.tool_action!r}")
|
||||||
for t in s.targets():
|
for t in s.targets():
|
||||||
kind, _, ref = t.partition(":")
|
kind, _, ref = t.partition(":")
|
||||||
if kind == "end" and ref not in g.ends:
|
if kind == "end" and ref not in g.ends:
|
||||||
raise ValueError(f"{g.id}.{s.id}: unknown end {ref!r}")
|
raise ValueError(f"{g.id}.{s.id}: unknown end {ref!r}")
|
||||||
elif kind == "guide" and ref not in guides:
|
elif kind == "guide" and ref not in guides:
|
||||||
raise ValueError(f"{g.id}.{s.id}: unknown guide {ref!r}")
|
raise ValueError(f"{g.id}.{s.id}: unknown guide {ref!r}")
|
||||||
elif not ref and t not in g.steps:
|
elif not ref and t not in g.steps:
|
||||||
raise ValueError(f"{g.id}.{s.id}: unknown step {t!r}")
|
raise ValueError(f"{g.id}.{s.id}: unknown step {t!r}")
|
||||||
for e in g.ends.values():
|
for e in g.ends.values():
|
||||||
if e.severity not in END_SEVERITY:
|
if e.severity not in END_SEVERITY:
|
||||||
raise ValueError(f"{g.id}.end.{e.id}: unknown severity {e.severity!r}")
|
raise ValueError(f"{g.id}.end.{e.id}: unknown severity {e.severity!r}")
|
||||||
|
|
||||||
|
|
||||||
def recommended(guides: dict[str, Guide], engine: DiagnosticsEngine) -> list[Guide]:
|
def recommended(guides: dict[str, Guide], engine: DiagnosticsEngine) -> list[Guide]:
|
||||||
"""Guides matching the current root findings (in root order), then the LED."""
|
"""Guides matching the current root findings (in root order), then the LED."""
|
||||||
report = engine.report()
|
report = engine.report()
|
||||||
keys: list[str] = []
|
keys: list[str] = []
|
||||||
for rc in report.roots:
|
for rc in report.roots:
|
||||||
keys.append(rc.finding.rule_id)
|
keys.append(rc.finding.rule_id)
|
||||||
keys += [c.rule_id for c in rc.consequences]
|
keys += [c.rule_id for c in rc.consequences]
|
||||||
if report.led not in ("UNKNOWN",):
|
if report.led not in ("UNKNOWN",):
|
||||||
keys.append(f"led:{report.led}")
|
keys.append(f"led:{report.led}")
|
||||||
out: list[Guide] = [g for g in guides.values() if "always" in g.recommend]
|
out: list[Guide] = [g for g in guides.values() if "always" in g.recommend]
|
||||||
for k in keys:
|
for k in keys:
|
||||||
for g in guides.values():
|
for g in guides.values():
|
||||||
if k in g.recommend and g not in out:
|
if k in g.recommend and g not in out:
|
||||||
out.append(g)
|
out.append(g)
|
||||||
return out
|
return out
|
||||||
|
|
||||||
|
|
||||||
@dataclass
|
@dataclass
|
||||||
class View:
|
class View:
|
||||||
"""What the UI should show right now."""
|
"""What the UI should show right now."""
|
||||||
guide: Guide | None = None
|
guide: Guide | None = None
|
||||||
step: Step | None = None
|
step: Step | None = None
|
||||||
text: str = ""
|
text: str = ""
|
||||||
options: list[tuple[str, str]] = field(default_factory=list) # (key, label)
|
options: list[tuple[str, str]] = field(default_factory=list) # (key, label)
|
||||||
waiting: bool = False
|
waiting: bool = False
|
||||||
remaining_s: float = 0.0
|
remaining_s: float = 0.0
|
||||||
note: str = ""
|
note: str = ""
|
||||||
end: End | None = None
|
end: End | None = None
|
||||||
can_back: bool = False
|
can_back: bool = False
|
||||||
|
|
||||||
|
|
||||||
class GuideRunner:
|
class GuideRunner:
|
||||||
def __init__(self, engine: DiagnosticsEngine, guides: dict[str, Guide] | None = None,
|
def __init__(self, engine: DiagnosticsEngine, guides: dict[str, Guide] | None = None,
|
||||||
on_action: Callable[[str], bool] | None = None,
|
on_action: Callable[[str], bool] | None = None,
|
||||||
on_log: Callable[[str], None] | None = None,
|
on_log: Callable[[str], None] | None = None,
|
||||||
clock: Callable[[], float] = time.monotonic):
|
clock: Callable[[], float] = time.monotonic):
|
||||||
self.engine = engine
|
self.engine = engine
|
||||||
self.guides = guides if guides is not None else load_guides()
|
self.guides = guides if guides is not None else load_guides()
|
||||||
self._on_action = on_action or (lambda _a: False)
|
self._on_action = on_action or (lambda _a: False)
|
||||||
self._on_log = on_log or (lambda _t: None)
|
self._on_log = on_log or (lambda _t: None)
|
||||||
self._clock = clock
|
self._clock = clock
|
||||||
self.cancel()
|
self.cancel()
|
||||||
|
|
||||||
# ------------------------------------------------------------ control
|
# ------------------------------------------------------------ control
|
||||||
def cancel(self) -> None:
|
def cancel(self) -> None:
|
||||||
self.guide: Guide | None = None
|
self.guide: Guide | None = None
|
||||||
self.step: Step | None = None
|
self.step: Step | None = None
|
||||||
self.end: End | None = None
|
self.end: End | None = None
|
||||||
self.note = ""
|
self.note = ""
|
||||||
self._stack: list[tuple[str, str]] = [] # (guide id, step id) for Back
|
self._stack: list[tuple[str, str]] = [] # (guide id, step id) for Back
|
||||||
self._wait_started = 0.0
|
self._wait_started = 0.0
|
||||||
self._wait_boot = 0
|
self._wait_boot = 0
|
||||||
self._wait_milestones: set[str] = set()
|
self._wait_milestones: set[str] = set()
|
||||||
|
|
||||||
def start(self, guide_id: str) -> None:
|
def start(self, guide_id: str) -> None:
|
||||||
self.cancel()
|
self.cancel()
|
||||||
self._enter_guide(guide_id)
|
self._enter_guide(guide_id)
|
||||||
|
|
||||||
def answer(self, key: str) -> None:
|
def answer(self, key: str) -> None:
|
||||||
"""Pick an option: LED colour name for led steps, option index otherwise."""
|
"""Pick an option: LED colour name for led steps, option index otherwise."""
|
||||||
s = self.step
|
s = self.step
|
||||||
if s is None:
|
if s is None:
|
||||||
return
|
return
|
||||||
if s.type == "led":
|
if s.type == "led":
|
||||||
label = LED_ANSWER_LABELS.get(key, key)
|
label = LED_ANSWER_LABELS.get(key, key)
|
||||||
self._record(s, label)
|
self._record(s, label)
|
||||||
self._check_led(key)
|
self._check_led(key)
|
||||||
target = s.route.get(key)
|
target = s.route.get(key)
|
||||||
elif s.type == "question":
|
elif s.type == "question":
|
||||||
opt = s.options[int(key)]
|
opt = s.options[int(key)]
|
||||||
self._record(s, opt.label)
|
self._record(s, opt.label)
|
||||||
target = opt.next
|
target = opt.next
|
||||||
else:
|
else:
|
||||||
return
|
return
|
||||||
if target:
|
if target:
|
||||||
self._push()
|
self._push()
|
||||||
self._go(target)
|
self._go(target)
|
||||||
|
|
||||||
def proceed(self) -> None:
|
def proceed(self) -> None:
|
||||||
"""Continue on info steps; 'skip waiting' on wait steps."""
|
"""Continue on info steps; 'skip waiting' on wait steps."""
|
||||||
s = self.step
|
s = self.step
|
||||||
if s is None:
|
if s is None:
|
||||||
return
|
return
|
||||||
if s.type == "info" and s.next:
|
if s.type == "info" and s.next:
|
||||||
self._push()
|
self._push()
|
||||||
self._go(s.next)
|
self._go(s.next)
|
||||||
elif s.type == "wait":
|
elif s.type == "wait":
|
||||||
self._record(s, "technician skipped the wait")
|
self._record(s, "technician skipped the wait")
|
||||||
self._finish_wait("timeout")
|
self._finish_wait("timeout")
|
||||||
|
|
||||||
def back(self) -> None:
|
def back(self) -> None:
|
||||||
# Never step back into a wait: re-entering it could restart the box.
|
# Never step back into a wait: re-entering it could restart the box.
|
||||||
while self._stack:
|
while self._stack:
|
||||||
gid, sid = self._stack.pop()
|
gid, sid = self._stack.pop()
|
||||||
if self.guides[gid].steps[sid].type != "wait":
|
if self.guides[gid].steps[sid].type != "wait":
|
||||||
self.guide, self.end, self.note = self.guides[gid], None, ""
|
self.guide, self.end, self.note = self.guides[gid], None, ""
|
||||||
self._enter_step(sid)
|
self._enter_step(sid)
|
||||||
return
|
return
|
||||||
|
|
||||||
# --------------------------------------------------------------- feed
|
# --------------------------------------------------------------- feed
|
||||||
def feed(self, line: LogLine) -> None:
|
def feed(self, line: LogLine) -> None:
|
||||||
s = self.step
|
s = self.step
|
||||||
if s is None or s.type != "wait":
|
if s is None or s.type != "wait":
|
||||||
return
|
return
|
||||||
if s.fail_on and s.fail_on.search(line.text):
|
if s.fail_on and s.fail_on.search(line.text):
|
||||||
self._record(s, f"log: {line.text}")
|
self._record(s, f"log: {line.text}")
|
||||||
self._finish_wait("fail")
|
self._finish_wait("fail")
|
||||||
elif s.until and s.until.search(line.text):
|
elif s.until and s.until.search(line.text):
|
||||||
self._record(s, f"log: {line.text}")
|
self._record(s, f"log: {line.text}")
|
||||||
self._finish_wait("ok")
|
self._finish_wait("ok")
|
||||||
elif s.until_milestone and self._milestone_new(s.until_milestone):
|
elif s.until_milestone and self._milestone_new(s.until_milestone):
|
||||||
self._record(s, f"milestone reached: {s.until_milestone}")
|
self._record(s, f"milestone reached: {s.until_milestone}")
|
||||||
self._finish_wait("ok")
|
self._finish_wait("ok")
|
||||||
|
|
||||||
def tick(self) -> None:
|
def tick(self) -> None:
|
||||||
s = self.step
|
s = self.step
|
||||||
if s is not None and s.type == "wait" and self._clock() - self._wait_started >= s.timeout_s:
|
if s is not None and s.type == "wait" and self._clock() - self._wait_started >= s.timeout_s:
|
||||||
self._finish_wait("ok" if s.pass_on_timeout else "timeout")
|
self._finish_wait("ok" if s.pass_on_timeout else "timeout")
|
||||||
|
|
||||||
# --------------------------------------------------------------- view
|
# --------------------------------------------------------------- view
|
||||||
def view(self) -> View:
|
def view(self) -> View:
|
||||||
v = View(guide=self.guide, step=self.step, end=self.end, note=self.note, can_back=bool(self._stack))
|
v = View(guide=self.guide, step=self.step, end=self.end, note=self.note, can_back=bool(self._stack))
|
||||||
s = self.step
|
s = self.step
|
||||||
if s is None:
|
if s is None:
|
||||||
return v
|
return v
|
||||||
v.text = self._render(s.text)
|
v.text = self._render(s.text)
|
||||||
if s.type == "led":
|
if s.type == "led":
|
||||||
v.options = [(k, LED_ANSWER_LABELS[k]) for k in LED_ANSWERS if k in s.route]
|
v.options = [(k, LED_ANSWER_LABELS[k]) for k in LED_ANSWERS if k in s.route]
|
||||||
elif s.type == "question":
|
elif s.type == "question":
|
||||||
v.options = [(str(i), o.label) for i, o in enumerate(s.options)]
|
v.options = [(str(i), o.label) for i, o in enumerate(s.options)]
|
||||||
elif s.type == "wait":
|
elif s.type == "wait":
|
||||||
v.waiting = True
|
v.waiting = True
|
||||||
v.remaining_s = max(0.0, s.timeout_s - (self._clock() - self._wait_started))
|
v.remaining_s = max(0.0, s.timeout_s - (self._clock() - self._wait_started))
|
||||||
return v
|
return v
|
||||||
|
|
||||||
# ---------------------------------------------------------- internals
|
# ---------------------------------------------------------- internals
|
||||||
def _push(self) -> None:
|
def _push(self) -> None:
|
||||||
if self.guide and self.step:
|
if self.guide and self.step:
|
||||||
self._stack.append((self.guide.id, self.step.id))
|
self._stack.append((self.guide.id, self.step.id))
|
||||||
|
|
||||||
def _enter_guide(self, guide_id: str) -> None:
|
def _enter_guide(self, guide_id: str) -> None:
|
||||||
self.guide = self.guides[guide_id]
|
self.guide = self.guides[guide_id]
|
||||||
self._on_log(f"technician: started guide '{self.guide.title}'")
|
self._on_log(f"technician: started guide '{self.guide.title}'")
|
||||||
self._enter_step(self.guide.start)
|
self._enter_step(self.guide.start)
|
||||||
|
|
||||||
def _go(self, target: str) -> None:
|
def _go(self, target: str) -> None:
|
||||||
kind, _, ref = target.partition(":")
|
kind, _, ref = target.partition(":")
|
||||||
if kind == "end" and ref:
|
if kind == "end" and ref:
|
||||||
self._conclude(self.guide.ends[ref])
|
self._conclude(self.guide.ends[ref])
|
||||||
elif kind == "guide" and ref:
|
elif kind == "guide" and ref:
|
||||||
self._enter_guide(ref)
|
self._enter_guide(ref)
|
||||||
else:
|
else:
|
||||||
self._enter_step(target)
|
self._enter_step(target)
|
||||||
|
|
||||||
def _enter_step(self, step_id: str) -> None:
|
def _enter_step(self, step_id: str) -> None:
|
||||||
s = self.guide.steps[step_id]
|
s = self.guide.steps[step_id]
|
||||||
self.step, self.note = s, ""
|
self.step, self.note = s, ""
|
||||||
if s.skip_if_finding and self._finding_active(s.skip_if_finding):
|
if s.skip_if_finding and self._finding_active(s.skip_if_finding):
|
||||||
self._auto(s, f"skipped - log already shows {s.skip_if_finding}", s.skip_to)
|
self._auto(s, f"skipped - log already shows {s.skip_if_finding}", s.skip_to)
|
||||||
return
|
return
|
||||||
if s.skip_unless_feature and not self._feature(s.skip_unless_feature):
|
if s.skip_unless_feature and not self._feature(s.skip_unless_feature):
|
||||||
self._auto(s, f"skipped - firmware has no {s.skip_unless_feature}", s.skip_to)
|
self._auto(s, f"skipped - firmware has no {s.skip_unless_feature}", s.skip_to)
|
||||||
return
|
return
|
||||||
if s.type == "route":
|
if s.type == "route":
|
||||||
target = self._route(s)
|
target = self._route(s)
|
||||||
self._auto(s, f"routed by log findings -> {target}", target)
|
self._auto(s, f"routed by log findings -> {target}", target)
|
||||||
return
|
return
|
||||||
if s.type == "wait":
|
if s.type == "wait":
|
||||||
self._wait_started = self._clock()
|
self._wait_started = self._clock()
|
||||||
self._wait_boot = self.engine.boot.index
|
self._wait_boot = self.engine.boot.index
|
||||||
self._wait_milestones = set(self.engine.milestones)
|
self._wait_milestones = set(self.engine.milestones)
|
||||||
if s.tool_action and not self._on_action(s.tool_action):
|
if s.tool_action and not self._on_action(s.tool_action):
|
||||||
self.note = "Could not restart the box from the tool - connect to it first, or switch it off and on."
|
self.note = "Could not restart the box from the tool - connect to it first, or switch it off and on."
|
||||||
# A milestone that is already reached satisfies the wait at once
|
# A milestone that is already reached satisfies the wait at once
|
||||||
# unless the step first restarts the box.
|
# unless the step first restarts the box.
|
||||||
if s.until_milestone and not s.tool_action and s.until_milestone in self.engine.milestones:
|
if s.until_milestone and not s.tool_action and s.until_milestone in self.engine.milestones:
|
||||||
self._record(s, f"already reached: {s.until_milestone}")
|
self._record(s, f"already reached: {s.until_milestone}")
|
||||||
self._finish_wait("ok")
|
self._finish_wait("ok")
|
||||||
|
|
||||||
def _auto(self, s: Step, why: str, target: str | None) -> None:
|
def _auto(self, s: Step, why: str, target: str | None) -> None:
|
||||||
self._on_log(f"technician guide: {s.id}: {why}")
|
self._on_log(f"technician guide: {s.id}: {why}")
|
||||||
if target:
|
if target:
|
||||||
self._go(target)
|
self._go(target)
|
||||||
|
|
||||||
def _finish_wait(self, outcome: str) -> None:
|
def _finish_wait(self, outcome: str) -> None:
|
||||||
s = self.step
|
s = self.step
|
||||||
target = {"ok": s.on_ok, "fail": s.on_fail or s.on_timeout, "timeout": s.on_timeout or s.on_fail}[outcome]
|
target = {"ok": s.on_ok, "fail": s.on_fail or s.on_timeout, "timeout": s.on_timeout or s.on_fail}[outcome]
|
||||||
if target is None:
|
if target is None:
|
||||||
return
|
return
|
||||||
self._push()
|
self._push()
|
||||||
self._go(target)
|
self._go(target)
|
||||||
|
|
||||||
def _milestone_new(self, mid: str) -> bool:
|
def _milestone_new(self, mid: str) -> bool:
|
||||||
if mid not in self.engine.milestones:
|
if mid not in self.engine.milestones:
|
||||||
return False
|
return False
|
||||||
return self.engine.boot.index != self._wait_boot or mid not in self._wait_milestones
|
return self.engine.boot.index != self._wait_boot or mid not in self._wait_milestones
|
||||||
|
|
||||||
def _route(self, s: Step) -> str:
|
def _route(self, s: Step) -> str:
|
||||||
report = self.engine.report()
|
report = self.engine.report()
|
||||||
for rc in report.roots:
|
for rc in report.roots:
|
||||||
for f in (rc.finding, *rc.consequences):
|
for f in (rc.finding, *rc.consequences):
|
||||||
if f.rule_id in s.routes:
|
if f.rule_id in s.routes:
|
||||||
return s.routes[f.rule_id]
|
return s.routes[f.rule_id]
|
||||||
return s.default or "end:" + next(iter(self.guide.ends))
|
return s.default or "end:" + next(iter(self.guide.ends))
|
||||||
|
|
||||||
def _check_led(self, seen: str) -> None:
|
def _check_led(self, seen: str) -> None:
|
||||||
expected = self.engine.led
|
expected = self.engine.led
|
||||||
if expected in ("UNKNOWN", "OFF") or seen == "CYCLING" or seen == expected:
|
if expected in ("UNKNOWN", "OFF") or seen == "CYCLING" or seen == expected:
|
||||||
return
|
return
|
||||||
exp_label, see_label = LED[expected][0], LED_ANSWER_LABELS[seen]
|
exp_label, see_label = LED[expected][0], LED_ANSWER_LABELS[seen]
|
||||||
self.engine.add_confirmed(
|
self.engine.add_confirmed(
|
||||||
"tech.led_mismatch", Severity.WARNING,
|
"tech.led_mismatch", Severity.WARNING,
|
||||||
f"LED shows {see_label}, but the log implies {exp_label}",
|
f"LED shows {see_label}, but the log implies {exp_label}",
|
||||||
f"The firmware state in the log corresponds to {exp_label}, while the technician sees {see_label}. "
|
f"The firmware state in the log corresponds to {exp_label}, while the technician sees {see_label}. "
|
||||||
"Either the LED just changed (check again in a few seconds), the LED/its wiring is faulty, "
|
"Either the LED just changed (check again in a few seconds), the LED/its wiring is faulty, "
|
||||||
"or the box runs different firmware. Trust the log findings.",
|
"or the box runs different firmware. Trust the log findings.",
|
||||||
("Look at the LED again for 10 seconds.", "If it stays different: note it for repair (LED board)."))
|
("Look at the LED again for 10 seconds.", "If it stays different: note it for repair (LED board)."))
|
||||||
|
|
||||||
def _conclude(self, end: End) -> None:
|
def _conclude(self, end: End) -> None:
|
||||||
self.step, self.end = None, end
|
self.step, self.end = None, end
|
||||||
self._on_log(f"technician guide result: {end.title}")
|
self._on_log(f"technician guide result: {end.title}")
|
||||||
sev = END_SEVERITY[end.severity]
|
sev = END_SEVERITY[end.severity]
|
||||||
self.engine.note_technician(f"{self.guide.title}: {end.title}")
|
self.engine.note_technician(f"{self.guide.title}: {end.title}")
|
||||||
if sev is not None:
|
if sev is not None:
|
||||||
self.engine.add_confirmed(f"tech.{self.guide.id}.{end.id}", sev, end.title, end.text, end.actions)
|
self.engine.add_confirmed(f"tech.{self.guide.id}.{end.id}", sev, end.title, end.text, end.actions)
|
||||||
|
|
||||||
def _record(self, s: Step, answer: str) -> None:
|
def _record(self, s: Step, answer: str) -> None:
|
||||||
q = self._render(s.text)
|
q = self._render(s.text)
|
||||||
self.engine.note_technician(f"{q} -> {answer}")
|
self.engine.note_technician(f"{q} -> {answer}")
|
||||||
self._on_log(f"technician: {q[:80]} -> {answer}")
|
self._on_log(f"technician: {q[:80]} -> {answer}")
|
||||||
|
|
||||||
def _finding_active(self, rule_id: str) -> bool:
|
def _finding_active(self, rule_id: str) -> bool:
|
||||||
return any(f.rule_id == rule_id and f.active for f in self.engine.findings.values())
|
return any(f.rule_id == rule_id and f.active for f in self.engine.findings.values())
|
||||||
|
|
||||||
def _feature(self, name: str) -> bool:
|
def _feature(self, name: str) -> bool:
|
||||||
fw = self.engine.firmware
|
fw = self.engine.firmware
|
||||||
if name == "sd_wifi":
|
if name == "sd_wifi":
|
||||||
return fw.supports_sd_wifi is not False
|
return fw.supports_sd_wifi is not False
|
||||||
if name == "setup_portal":
|
if name == "setup_portal":
|
||||||
if fw.known is not None:
|
if fw.known is not None:
|
||||||
return fw.known.setup_portal
|
return fw.known.setup_portal
|
||||||
if "setup_portal" in fw.evidence:
|
if "setup_portal" in fw.evidence:
|
||||||
return True
|
return True
|
||||||
return "legacy_v1" not in fw.evidence # unknown firmware: ask
|
return "legacy_v1" not in fw.evidence # unknown firmware: ask
|
||||||
return False
|
return False
|
||||||
|
|
||||||
def _render(self, text: str) -> str:
|
def _render(self, text: str) -> str:
|
||||||
report = self.engine.report()
|
report = self.engine.report()
|
||||||
sensors = sorted({f.title.removesuffix(" failed to start") for f in self.engine.findings.values()
|
sensors = sorted({f.title.removesuffix(" failed to start") for f in self.engine.findings.values()
|
||||||
if f.rule_id == "sensor.init_failed" and f.active})
|
if f.rule_id == "sensor.init_failed" and f.active})
|
||||||
ctx = {
|
ctx = {
|
||||||
"expected_led": LED[report.led][0],
|
"expected_led": LED[report.led][0],
|
||||||
"failing_sensors": ", ".join(sensors) or "see the Diagnosis tab",
|
"failing_sensors": ", ".join(sensors) or "see the Diagnosis tab",
|
||||||
"top_finding": report.roots[0].finding.title if report.roots else "none",
|
"top_finding": report.roots[0].finding.title if report.roots else "none",
|
||||||
}
|
}
|
||||||
return text.format_map(_Fmt(ctx))
|
return text.format_map(_Fmt(ctx))
|
||||||
|
|
||||||
|
|
||||||
class _Fmt(dict):
|
class _Fmt(dict):
|
||||||
def __missing__(self, key: str) -> str:
|
def __missing__(self, key: str) -> str:
|
||||||
return "{" + key + "}"
|
return "{" + key + "}"
|
||||||
+740
-740
File diff suppressed because it is too large.
Load diff
+732
-732
File diff suppressed because it is too large.
Load diff
+260
-260
@@ -1,260 +1,260 @@
|
|||||||
"""Firmware images: validation, integrity, layout and the firmware folder.
|
"""Firmware images: validation, integrity, layout and the firmware folder.
|
||||||
|
|
||||||
The tool flashes ONLY the .bin files in its own firmware/ folder (next to
|
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,
|
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
|
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
|
compile date stored in the firmware itself (ESP-IDF app descriptor), newest
|
||||||
first, so the file name does not matter.
|
first, so the file name does not matter.
|
||||||
|
|
||||||
Two kinds:
|
Two kinds:
|
||||||
* merged - bootloader at 0x0 + partition table + app (merged-binary.bin);
|
* merged - bootloader at 0x0 + partition table + app (merged-binary.bin);
|
||||||
App-only or Full flashing;
|
App-only or Full flashing;
|
||||||
* app - the application binary only (build/kota-sensorboard.bin);
|
* app - the application binary only (build/kota-sensorboard.bin);
|
||||||
App-only flashing, laid out like a merged image in the folder.
|
App-only flashing, laid out like a merged image in the folder.
|
||||||
|
|
||||||
Every image is checked structurally (ESP32-S3, kota-sensorboard app
|
Every image is checked structurally (ESP32-S3, kota-sensorboard app
|
||||||
descriptor, segment checksum and the appended SHA-256) so a truncated or
|
descriptor, segment checksum and the appended SHA-256) so a truncated or
|
||||||
corrupted file is refused before anything is written.
|
corrupted file is refused before anything is written.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
import datetime as dt
|
import datetime as dt
|
||||||
import hashlib
|
import hashlib
|
||||||
import struct
|
import struct
|
||||||
from dataclasses import dataclass
|
from dataclasses import dataclass
|
||||||
from pathlib import Path
|
from pathlib import Path
|
||||||
|
|
||||||
FIRMWARE_DIR = Path(__file__).resolve().parents[2] / "firmware"
|
FIRMWARE_DIR = Path(__file__).resolve().parents[2] / "firmware"
|
||||||
|
|
||||||
PT_OFFSET = 0x8000
|
PT_OFFSET = 0x8000
|
||||||
PT_SIZE = 0xC00
|
PT_SIZE = 0xC00
|
||||||
ESP32S3_CHIP_ID = 9
|
ESP32S3_CHIP_ID = 9
|
||||||
IMAGE_MAGIC = 0xE9
|
IMAGE_MAGIC = 0xE9
|
||||||
APP_DESC_MAGIC = 0xABCD5432
|
APP_DESC_MAGIC = 0xABCD5432
|
||||||
FLASH_SIZES = {0: "1MB", 1: "2MB", 2: "4MB", 3: "8MB", 4: "16MB", 5: "32MB"}
|
FLASH_SIZES = {0: "1MB", 1: "2MB", 2: "4MB", 3: "8MB", 4: "16MB", 5: "32MB"}
|
||||||
_MONTHS = {m: i for i, m in enumerate(
|
_MONTHS = {m: i for i, m in enumerate(
|
||||||
["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"], 1)}
|
["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"], 1)}
|
||||||
|
|
||||||
|
|
||||||
class ImageError(ValueError):
|
class ImageError(ValueError):
|
||||||
pass
|
pass
|
||||||
|
|
||||||
|
|
||||||
@dataclass(frozen=True)
|
@dataclass(frozen=True)
|
||||||
class Partition:
|
class Partition:
|
||||||
label: str
|
label: str
|
||||||
type: int
|
type: int
|
||||||
subtype: int
|
subtype: int
|
||||||
offset: int
|
offset: int
|
||||||
size: int
|
size: int
|
||||||
|
|
||||||
|
|
||||||
@dataclass(frozen=True)
|
@dataclass(frozen=True)
|
||||||
class AppInfo:
|
class AppInfo:
|
||||||
project: str
|
project: str
|
||||||
version: str
|
version: str
|
||||||
built: str # "Sep 28 2026 15:07:57" as in the app descriptor
|
built: str # "Sep 28 2026 15:07:57" as in the app descriptor
|
||||||
idf: str
|
idf: str
|
||||||
elf_sha: str # hex
|
elf_sha: str # hex
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def built_at(self) -> dt.datetime | None:
|
def built_at(self) -> dt.datetime | None:
|
||||||
try:
|
try:
|
||||||
mon, day, year, hms = self.built.split()
|
mon, day, year, hms = self.built.split()
|
||||||
h, m, s = (int(x) for x in hms.split(":"))
|
h, m, s = (int(x) for x in hms.split(":"))
|
||||||
return dt.datetime(int(year), _MONTHS[mon], int(day), h, m, s)
|
return dt.datetime(int(year), _MONTHS[mon], int(day), h, m, s)
|
||||||
except (ValueError, KeyError):
|
except (ValueError, KeyError):
|
||||||
return None
|
return None
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def compiled(self) -> str:
|
def compiled(self) -> str:
|
||||||
"""'2026-09-28 15:07' (ISO-like, sortable) or the raw descriptor text."""
|
"""'2026-09-28 15:07' (ISO-like, sortable) or the raw descriptor text."""
|
||||||
t = self.built_at
|
t = self.built_at
|
||||||
return t.strftime("%Y-%m-%d %H:%M") if t else self.built
|
return t.strftime("%Y-%m-%d %H:%M") if t else self.built
|
||||||
|
|
||||||
|
|
||||||
@dataclass(frozen=True)
|
@dataclass(frozen=True)
|
||||||
class FirmwareImage:
|
class FirmwareImage:
|
||||||
path: Path
|
path: Path
|
||||||
kind: str # "merged" | "app"
|
kind: str # "merged" | "app"
|
||||||
sha256: str
|
sha256: str
|
||||||
flash_size: str
|
flash_size: str
|
||||||
partitions: tuple[Partition, ...]
|
partitions: tuple[Partition, ...]
|
||||||
partition_table: bytes # expected table on the box
|
partition_table: bytes # expected table on the box
|
||||||
app_offset: int # where the app starts inside the file
|
app_offset: int # where the app starts inside the file
|
||||||
app_length: int # exact app image length (from its structure)
|
app_length: int # exact app image length (from its structure)
|
||||||
app: AppInfo
|
app: AppInfo
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def name(self) -> str:
|
def name(self) -> str:
|
||||||
return self.path.name
|
return self.path.name
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def data(self) -> bytes:
|
def data(self) -> bytes:
|
||||||
return self.path.read_bytes()
|
return self.path.read_bytes()
|
||||||
|
|
||||||
def partition(self, label: str) -> Partition:
|
def partition(self, label: str) -> Partition:
|
||||||
for p in self.partitions:
|
for p in self.partitions:
|
||||||
if p.label == label:
|
if p.label == label:
|
||||||
return p
|
return p
|
||||||
raise ImageError(f"partition {label!r} not in image")
|
raise ImageError(f"partition {label!r} not in image")
|
||||||
|
|
||||||
def app_bytes(self) -> bytes:
|
def app_bytes(self) -> bytes:
|
||||||
return self.data[self.app_offset:self.app_offset + self.app_length]
|
return self.data[self.app_offset:self.app_offset + self.app_length]
|
||||||
|
|
||||||
def blank_otadata(self) -> bytes:
|
def blank_otadata(self) -> bytes:
|
||||||
"""Erased otadata: the bootloader then boots ota_0."""
|
"""Erased otadata: the bootloader then boots ota_0."""
|
||||||
return b"\xff" * self.partition("otadata").size
|
return b"\xff" * self.partition("otadata").size
|
||||||
|
|
||||||
def label(self) -> str:
|
def label(self) -> str:
|
||||||
"""Choice text: compile date first (that is what the technician picks by)."""
|
"""Choice text: compile date first (that is what the technician picks by)."""
|
||||||
kind = "" if self.kind == "merged" else ", app only"
|
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})"
|
return f"Compiled {self.app.compiled} - v{self.app.version} [{self.app.elf_sha[:8]}]{kind} ({self.name})"
|
||||||
|
|
||||||
|
|
||||||
# ---------------------------------------------------------------- parsing
|
# ---------------------------------------------------------------- parsing
|
||||||
|
|
||||||
def parse_partition_table(raw: bytes) -> tuple[Partition, ...]:
|
def parse_partition_table(raw: bytes) -> tuple[Partition, ...]:
|
||||||
parts = []
|
parts = []
|
||||||
for i in range(0, len(raw) - 31, 32):
|
for i in range(0, len(raw) - 31, 32):
|
||||||
entry = raw[i:i + 32]
|
entry = raw[i:i + 32]
|
||||||
magic = entry[:2]
|
magic = entry[:2]
|
||||||
if magic == b"\xaa\x50":
|
if magic == b"\xaa\x50":
|
||||||
_, ptype, sub, off, size = struct.unpack_from("<HBBII", entry)
|
_, ptype, sub, off, size = struct.unpack_from("<HBBII", entry)
|
||||||
label = entry[12:28].split(b"\0")[0].decode("ascii", "replace")
|
label = entry[12:28].split(b"\0")[0].decode("ascii", "replace")
|
||||||
parts.append(Partition(label, ptype, sub, off, size))
|
parts.append(Partition(label, ptype, sub, off, size))
|
||||||
elif magic in (b"\xeb\xeb", b"\xff\xff"): # MD5 entry / end
|
elif magic in (b"\xeb\xeb", b"\xff\xff"): # MD5 entry / end
|
||||||
break
|
break
|
||||||
else:
|
else:
|
||||||
raise ImageError(f"corrupt partition table entry at 0x{PT_OFFSET + i:x}")
|
raise ImageError(f"corrupt partition table entry at 0x{PT_OFFSET + i:x}")
|
||||||
return tuple(parts)
|
return tuple(parts)
|
||||||
|
|
||||||
|
|
||||||
def app_image_length(data: bytes, offset: int = 0) -> int:
|
def app_image_length(data: bytes, offset: int = 0) -> int:
|
||||||
"""Validate an ESP app image at `offset`; return its exact length.
|
"""Validate an ESP app image at `offset`; return its exact length.
|
||||||
|
|
||||||
Checks the segment checksum and, when the header says so, the appended
|
Checks the segment checksum and, when the header says so, the appended
|
||||||
SHA-256 - the same checks the bootloader performs before booting it.
|
SHA-256 - the same checks the bootloader performs before booting it.
|
||||||
"""
|
"""
|
||||||
if len(data) < offset + 24 or data[offset] != IMAGE_MAGIC:
|
if len(data) < offset + 24 or data[offset] != IMAGE_MAGIC:
|
||||||
raise ImageError(f"no firmware image at 0x{offset:x}")
|
raise ImageError(f"no firmware image at 0x{offset:x}")
|
||||||
segments = data[offset + 1]
|
segments = data[offset + 1]
|
||||||
chip_id = struct.unpack_from("<H", data, offset + 12)[0]
|
chip_id = struct.unpack_from("<H", data, offset + 12)[0]
|
||||||
if chip_id != ESP32S3_CHIP_ID:
|
if chip_id != ESP32S3_CHIP_ID:
|
||||||
raise ImageError(f"image is for chip id {chip_id}, not ESP32-S3")
|
raise ImageError(f"image is for chip id {chip_id}, not ESP32-S3")
|
||||||
hash_appended = data[offset + 23] == 1
|
hash_appended = data[offset + 23] == 1
|
||||||
pos, checksum = offset + 24, 0xEF
|
pos, checksum = offset + 24, 0xEF
|
||||||
for _ in range(segments):
|
for _ in range(segments):
|
||||||
if pos + 8 > len(data):
|
if pos + 8 > len(data):
|
||||||
raise ImageError("image is truncated (segment header missing)")
|
raise ImageError("image is truncated (segment header missing)")
|
||||||
_, seg_len = struct.unpack_from("<II", data, pos)
|
_, seg_len = struct.unpack_from("<II", data, pos)
|
||||||
pos += 8
|
pos += 8
|
||||||
if pos + seg_len > len(data):
|
if pos + seg_len > len(data):
|
||||||
raise ImageError("image is truncated (segment data missing)")
|
raise ImageError("image is truncated (segment data missing)")
|
||||||
for b in data[pos:pos + seg_len]:
|
for b in data[pos:pos + seg_len]:
|
||||||
checksum ^= b
|
checksum ^= b
|
||||||
pos += seg_len
|
pos += seg_len
|
||||||
pos += 15 - ((pos - offset) % 16) # pad so the checksum ends a 16-byte block
|
pos += 15 - ((pos - offset) % 16) # pad so the checksum ends a 16-byte block
|
||||||
if pos >= len(data) or data[pos] != checksum:
|
if pos >= len(data) or data[pos] != checksum:
|
||||||
raise ImageError("image checksum is wrong - the file is corrupted")
|
raise ImageError("image checksum is wrong - the file is corrupted")
|
||||||
pos += 1
|
pos += 1
|
||||||
if hash_appended:
|
if hash_appended:
|
||||||
if pos + 32 > len(data):
|
if pos + 32 > len(data):
|
||||||
raise ImageError("image is truncated (SHA-256 missing)")
|
raise ImageError("image is truncated (SHA-256 missing)")
|
||||||
if hashlib.sha256(data[offset:pos]).digest() != data[pos:pos + 32]:
|
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")
|
raise ImageError("image SHA-256 does not match its content - the file is corrupted")
|
||||||
pos += 32
|
pos += 32
|
||||||
return pos - offset
|
return pos - offset
|
||||||
|
|
||||||
|
|
||||||
def _app_info(data: bytes, offset: int) -> AppInfo:
|
def _app_info(data: bytes, offset: int) -> AppInfo:
|
||||||
d = data[offset + 0x20:offset + 0x20 + 256]
|
d = data[offset + 0x20:offset + 0x20 + 256]
|
||||||
if len(d) < 256 or struct.unpack_from("<I", d)[0] != APP_DESC_MAGIC:
|
if len(d) < 256 or struct.unpack_from("<I", d)[0] != APP_DESC_MAGIC:
|
||||||
raise ImageError("firmware has no ESP-IDF app descriptor")
|
raise ImageError("firmware has no ESP-IDF app descriptor")
|
||||||
s = lambda o, n: d[o:o + n].split(b"\0")[0].decode("ascii", "replace")
|
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)}",
|
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())
|
idf=s(112, 32), elf_sha=d[144:176].hex())
|
||||||
if info.project != "kota-sensorboard":
|
if info.project != "kota-sensorboard":
|
||||||
raise ImageError(f"firmware is {info.project!r}, not kota-sensorboard")
|
raise ImageError(f"firmware is {info.project!r}, not kota-sensorboard")
|
||||||
return info
|
return info
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
def inspect_image(path: Path, reference: FirmwareImage | None = None) -> FirmwareImage:
|
def inspect_image(path: Path, reference: FirmwareImage | None = None) -> FirmwareImage:
|
||||||
"""Validate a merged or app-only image. App-only images need a `reference`
|
"""Validate a merged or app-only image. App-only images need a `reference`
|
||||||
(a merged image) that provides the flash layout."""
|
(a merged image) that provides the flash layout."""
|
||||||
data = path.read_bytes()
|
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":
|
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
|
app_image_length(data, 0) # bootloader must be intact
|
||||||
table = data[PT_OFFSET:PT_OFFSET + PT_SIZE]
|
table = data[PT_OFFSET:PT_OFFSET + PT_SIZE]
|
||||||
parts = parse_partition_table(table)
|
parts = parse_partition_table(table)
|
||||||
labels = {p.label for p in parts}
|
labels = {p.label for p in parts}
|
||||||
for need in ("nvs", "otadata", "ota_0"):
|
for need in ("nvs", "otadata", "ota_0"):
|
||||||
if need not in labels:
|
if need not in labels:
|
||||||
raise ImageError(f"partition table has no {need!r} partition")
|
raise ImageError(f"partition table has no {need!r} partition")
|
||||||
ota0 = next(p for p in parts if p.label == "ota_0")
|
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, "?")
|
kind, app_off, flash_size = "merged", ota0.offset, FLASH_SIZES.get(data[3] >> 4, "?")
|
||||||
elif data[:1] == bytes([IMAGE_MAGIC]):
|
elif data[:1] == bytes([IMAGE_MAGIC]):
|
||||||
if reference is None:
|
if reference is None:
|
||||||
raise ImageError("app-only file, but there is no complete (merged) image in the folder "
|
raise ImageError("app-only file, but there is no complete (merged) image in the folder "
|
||||||
"to take the flash layout from")
|
"to take the flash layout from")
|
||||||
kind, app_off = "app", 0
|
kind, app_off = "app", 0
|
||||||
parts, table, flash_size = reference.partitions, reference.partition_table, reference.flash_size
|
parts, table, flash_size = reference.partitions, reference.partition_table, reference.flash_size
|
||||||
ota0 = next(p for p in parts if p.label == "ota_0")
|
ota0 = next(p for p in parts if p.label == "ota_0")
|
||||||
else:
|
else:
|
||||||
raise ImageError("not an ESP32 firmware file")
|
raise ImageError("not an ESP32 firmware file")
|
||||||
length = app_image_length(data, app_off)
|
length = app_image_length(data, app_off)
|
||||||
if length > ota0.size:
|
if length > ota0.size:
|
||||||
raise ImageError(f"firmware ({length} bytes) does not fit the ota_0 partition ({ota0.size} bytes)")
|
raise ImageError(f"firmware ({length} bytes) does not fit the ota_0 partition ({ota0.size} bytes)")
|
||||||
app = _app_info(data, app_off)
|
app = _app_info(data, app_off)
|
||||||
return FirmwareImage(path, kind, hashlib.sha256(data).hexdigest(),
|
return FirmwareImage(path, kind, hashlib.sha256(data).hexdigest(),
|
||||||
flash_size, parts, table, app_off, length, app)
|
flash_size, parts, table, app_off, length, app)
|
||||||
|
|
||||||
|
|
||||||
# ------------------------------------------------------------- catalogue
|
# ------------------------------------------------------------- catalogue
|
||||||
|
|
||||||
def folder_images(folder: Path = FIRMWARE_DIR) -> tuple[list[FirmwareImage], list[str]]:
|
def folder_images(folder: Path = FIRMWARE_DIR) -> tuple[list[FirmwareImage], list[str]]:
|
||||||
"""(valid images newest-compiled first, problems) for the .bin files in `folder`.
|
"""(valid images newest-compiled first, problems) for the .bin files in `folder`.
|
||||||
|
|
||||||
A broken or foreign file is reported, never offered. The same build
|
A broken or foreign file is reported, never offered. The same build
|
||||||
under two file names is offered once.
|
under two file names is offered once.
|
||||||
"""
|
"""
|
||||||
if not folder.is_dir():
|
if not folder.is_dir():
|
||||||
return [], [f"firmware folder not found: {folder}"]
|
return [], [f"firmware folder not found: {folder}"]
|
||||||
files = sorted(p for p in folder.iterdir() if p.is_file() and p.suffix.lower() == ".bin")
|
files = sorted(p for p in folder.iterdir() if p.is_file() and p.suffix.lower() == ".bin")
|
||||||
merged: list[FirmwareImage] = []
|
merged: list[FirmwareImage] = []
|
||||||
app_only: list[Path] = []
|
app_only: list[Path] = []
|
||||||
problems: list[str] = []
|
problems: list[str] = []
|
||||||
for f in files:
|
for f in files:
|
||||||
try:
|
try:
|
||||||
merged.append(inspect_image(f))
|
merged.append(inspect_image(f))
|
||||||
except ImageError as exc:
|
except ImageError as exc:
|
||||||
if "app-only" in str(exc):
|
if "app-only" in str(exc):
|
||||||
app_only.append(f)
|
app_only.append(f)
|
||||||
else:
|
else:
|
||||||
problems.append(f"{f.name}: {exc}")
|
problems.append(f"{f.name}: {exc}")
|
||||||
except OSError as exc:
|
except OSError as exc:
|
||||||
problems.append(f"{f.name}: cannot read ({exc})")
|
problems.append(f"{f.name}: cannot read ({exc})")
|
||||||
merged.sort(key=_newest_first)
|
merged.sort(key=_newest_first)
|
||||||
reference = merged[0] if merged else None
|
reference = merged[0] if merged else None
|
||||||
images = list(merged)
|
images = list(merged)
|
||||||
for f in app_only:
|
for f in app_only:
|
||||||
try:
|
try:
|
||||||
images.append(inspect_image(f, reference))
|
images.append(inspect_image(f, reference))
|
||||||
except (ImageError, OSError) as exc:
|
except (ImageError, OSError) as exc:
|
||||||
problems.append(f"{f.name}: {exc}")
|
problems.append(f"{f.name}: {exc}")
|
||||||
images.sort(key=_newest_first)
|
images.sort(key=_newest_first)
|
||||||
unique: dict[str, FirmwareImage] = {}
|
unique: dict[str, FirmwareImage] = {}
|
||||||
for img in images:
|
for img in images:
|
||||||
if img.sha256 in unique:
|
if img.sha256 in unique:
|
||||||
problems.append(f"{img.name}: same file as {unique[img.sha256].name} (listed once)")
|
problems.append(f"{img.name}: same file as {unique[img.sha256].name} (listed once)")
|
||||||
else:
|
else:
|
||||||
unique[img.sha256] = img
|
unique[img.sha256] = img
|
||||||
return list(unique.values()), problems
|
return list(unique.values()), problems
|
||||||
|
|
||||||
|
|
||||||
def _newest_first(img: FirmwareImage) -> tuple:
|
def _newest_first(img: FirmwareImage) -> tuple:
|
||||||
# Unknown compile dates last; merged before app-only for the same date.
|
# Unknown compile dates last; merged before app-only for the same date.
|
||||||
t = img.app.built_at
|
t = img.app.built_at
|
||||||
return (t is None, -t.timestamp() if t else 0.0, img.kind != "merged", img.name)
|
return (t is None, -t.timestamp() if t else 0.0, img.kind != "merged", img.name)
|
||||||
+113
-113
@@ -1,113 +1,113 @@
|
|||||||
"""Matter onboarding payloads: the "MT:..." QR string and the 11-digit manual code.
|
"""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):
|
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.
|
bit fields packed LSB-first, Base38 in 3-byte chunks, Verhoeff check digit.
|
||||||
|
|
||||||
The sensorbox firmware uses the Matter SDK example commissionable data
|
The sensorbox firmware uses the Matter SDK example commissionable data
|
||||||
(CONFIG_EXAMPLE_COMMISSIONABLE_DATA_PROVIDER): every v1.0 box advertises
|
(CONFIG_EXAMPLE_COMMISSIONABLE_DATA_PROVIDER): every v1.0 box advertises
|
||||||
VID 0xFFF1 / PID 0x8000 / discriminator 3840 with passcode 20202021, which is
|
VID 0xFFF1 / PID 0x8000 / discriminator 3840 with passcode 20202021, which is
|
||||||
exactly the sticker (QR "MT:Y.K9042C00KA0648G00", manual 3497-011-2332).
|
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
|
VID/PID/discriminator are taken from the box's own log when available; the
|
||||||
passcode is never logged, so the known default is used.
|
passcode is never logged, so the known default is used.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
import re
|
import re
|
||||||
from dataclasses import dataclass
|
from dataclasses import dataclass
|
||||||
|
|
||||||
BASE38 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ-."
|
BASE38 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ-."
|
||||||
RENDEZVOUS_BLE = 1 << 1
|
RENDEZVOUS_BLE = 1 << 1
|
||||||
DEFAULT_PASSCODE = 20202021 # Matter SDK test passcode used by the v1.0 firmware
|
DEFAULT_PASSCODE = 20202021 # Matter SDK test passcode used by the v1.0 firmware
|
||||||
DEFAULT = dict(vendor_id=0xFFF1, product_id=0x8000, discriminator=3840)
|
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
|
# 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+)")
|
_ADVERTISE = re.compile(r"vendorID=(\d+) productID=(\d+) discriminator=(\d+)")
|
||||||
|
|
||||||
|
|
||||||
@dataclass(frozen=True)
|
@dataclass(frozen=True)
|
||||||
class SetupPayload:
|
class SetupPayload:
|
||||||
vendor_id: int = DEFAULT["vendor_id"]
|
vendor_id: int = DEFAULT["vendor_id"]
|
||||||
product_id: int = DEFAULT["product_id"]
|
product_id: int = DEFAULT["product_id"]
|
||||||
discriminator: int = DEFAULT["discriminator"]
|
discriminator: int = DEFAULT["discriminator"]
|
||||||
passcode: int = DEFAULT_PASSCODE
|
passcode: int = DEFAULT_PASSCODE
|
||||||
rendezvous: int = RENDEZVOUS_BLE
|
rendezvous: int = RENDEZVOUS_BLE
|
||||||
flow: int = 0 # standard commissioning flow
|
flow: int = 0 # standard commissioning flow
|
||||||
version: int = 0
|
version: int = 0
|
||||||
from_log: bool = False # VID/PID/discriminator read from this box's log
|
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:...")
|
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
|
manual: str | None = None # exact 11-digit manual code reported by the box
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def from_box(self) -> bool:
|
def from_box(self) -> bool:
|
||||||
return self.qr is not None
|
return self.qr is not None
|
||||||
|
|
||||||
def qr_text(self) -> str:
|
def qr_text(self) -> str:
|
||||||
if self.qr:
|
if self.qr:
|
||||||
return self.qr
|
return self.qr
|
||||||
fields = [(self.version, 3), (self.vendor_id, 16), (self.product_id, 16), (self.flow, 2),
|
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)]
|
(self.rendezvous, 8), (self.discriminator, 12), (self.passcode, 27), (0, 4)]
|
||||||
value, shift = 0, 0
|
value, shift = 0, 0
|
||||||
for v, bits in fields:
|
for v, bits in fields:
|
||||||
if not 0 <= v < (1 << bits):
|
if not 0 <= v < (1 << bits):
|
||||||
raise ValueError(f"field value {v} does not fit in {bits} bits")
|
raise ValueError(f"field value {v} does not fit in {bits} bits")
|
||||||
value |= v << shift
|
value |= v << shift
|
||||||
shift += bits
|
shift += bits
|
||||||
return "MT:" + _base38(value.to_bytes(shift // 8, "little"))
|
return "MT:" + _base38(value.to_bytes(shift // 8, "little"))
|
||||||
|
|
||||||
def manual_code(self) -> str:
|
def manual_code(self) -> str:
|
||||||
if self.manual:
|
if self.manual:
|
||||||
return self.manual
|
return self.manual
|
||||||
short = self.discriminator >> 8 # upper 4 bits
|
short = self.discriminator >> 8 # upper 4 bits
|
||||||
chunk1 = short >> 2 # vid_pid_present = 0
|
chunk1 = short >> 2 # vid_pid_present = 0
|
||||||
chunk2 = ((short & 0x3) << 14) | (self.passcode & 0x3FFF)
|
chunk2 = ((short & 0x3) << 14) | (self.passcode & 0x3FFF)
|
||||||
chunk3 = self.passcode >> 14
|
chunk3 = self.passcode >> 14
|
||||||
digits = f"{chunk1}{chunk2:05d}{chunk3:04d}"
|
digits = f"{chunk1}{chunk2:05d}{chunk3:04d}"
|
||||||
return digits + str(verhoeff_check(digits))
|
return digits + str(verhoeff_check(digits))
|
||||||
|
|
||||||
def manual_code_pretty(self) -> str:
|
def manual_code_pretty(self) -> str:
|
||||||
c = self.manual_code()
|
c = self.manual_code()
|
||||||
return f"{c[:4]}-{c[4:7]}-{c[7:]}"
|
return f"{c[:4]}-{c[4:7]}-{c[7:]}"
|
||||||
|
|
||||||
|
|
||||||
def _base38(data: bytes) -> str:
|
def _base38(data: bytes) -> str:
|
||||||
out = []
|
out = []
|
||||||
for i in range(0, len(data), 3):
|
for i in range(0, len(data), 3):
|
||||||
chunk = data[i:i + 3]
|
chunk = data[i:i + 3]
|
||||||
value = int.from_bytes(chunk, "little")
|
value = int.from_bytes(chunk, "little")
|
||||||
for _ in range({3: 5, 2: 4, 1: 2}[len(chunk)]):
|
for _ in range({3: 5, 2: 4, 1: 2}[len(chunk)]):
|
||||||
value, rem = divmod(value, 38)
|
value, rem = divmod(value, 38)
|
||||||
out.append(BASE38[rem])
|
out.append(BASE38[rem])
|
||||||
return "".join(out)
|
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],
|
_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],
|
[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],
|
[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]]
|
[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],
|
_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],
|
[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]]
|
[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]
|
_INV = [0, 4, 3, 2, 1, 5, 6, 7, 8, 9]
|
||||||
|
|
||||||
|
|
||||||
def verhoeff_check(digits: str) -> int:
|
def verhoeff_check(digits: str) -> int:
|
||||||
c = 0
|
c = 0
|
||||||
for i, d in enumerate(reversed(digits)):
|
for i, d in enumerate(reversed(digits)):
|
||||||
c = _D[c][_P[(i + 1) % 8][int(d)]]
|
c = _D[c][_P[(i + 1) % 8][int(d)]]
|
||||||
return _INV[c]
|
return _INV[c]
|
||||||
|
|
||||||
|
|
||||||
def payload_from_log(lines: list[str], qr: str | None = None, manual: str | None = None) -> SetupPayload:
|
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
|
"""Firmware 1.0.16+ reports its exact QR payload and manual code
|
||||||
("KOTA: matter ... qr=MT:... manual=..."); older firmware: use the
|
("KOTA: matter ... qr=MT:... manual=..."); older firmware: use the
|
||||||
advertised VID/PID/discriminator if seen; defaults otherwise."""
|
advertised VID/PID/discriminator if seen; defaults otherwise."""
|
||||||
base = SetupPayload()
|
base = SetupPayload()
|
||||||
for text in reversed(lines):
|
for text in reversed(lines):
|
||||||
if m := _ADVERTISE.search(text):
|
if m := _ADVERTISE.search(text):
|
||||||
base = SetupPayload(int(m.group(1)), int(m.group(2)), int(m.group(3)), from_log=True)
|
base = SetupPayload(int(m.group(1)), int(m.group(2)), int(m.group(3)), from_log=True)
|
||||||
break
|
break
|
||||||
if qr:
|
if qr:
|
||||||
return SetupPayload(base.vendor_id, base.product_id, base.discriminator, from_log=True,
|
return SetupPayload(base.vendor_id, base.product_id, base.discriminator, from_log=True,
|
||||||
qr=qr, manual=manual if manual and manual.isdigit() else None)
|
qr=qr, manual=manual if manual and manual.isdigit() else None)
|
||||||
return base
|
return base
|
||||||
+261
-261
@@ -1,261 +1,261 @@
|
|||||||
"""Format an SD card for the sensorbox and write / check ENV.TXT.
|
"""Format an SD card for the sensorbox and write / check ENV.TXT.
|
||||||
|
|
||||||
Card format required by the firmware: MBR partition table, FAT32 (its FAT
|
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.
|
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
|
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
|
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
|
Windows drive) right before erasing it, so a card swapped after the
|
||||||
technician confirmed is not touched, and it writes MBR + FAT32 itself
|
technician confirmed is not touched, and it writes MBR + FAT32 itself
|
||||||
(no Storage cmdlets, which stalled on empty card-reader slots). Larger cards
|
(no Storage cmdlets, which stalled on empty card-reader slots). Larger cards
|
||||||
get a 32 GB FAT32 partition (Windows convention; plenty for the box).
|
get a 32 GB FAT32 partition (Windows convention; plenty for the box).
|
||||||
macOS: `diskutil eraseDisk FAT32 KOTA MBRFormat` (same as format_sd.sh).
|
macOS: `diskutil eraseDisk FAT32 KOTA MBRFormat` (same as format_sd.sh).
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
import json
|
import json
|
||||||
import os
|
import os
|
||||||
import plistlib
|
import plistlib
|
||||||
import subprocess
|
import subprocess
|
||||||
import sys
|
import sys
|
||||||
import time
|
import time
|
||||||
import uuid
|
import uuid
|
||||||
from dataclasses import dataclass, field
|
from dataclasses import dataclass, field
|
||||||
from pathlib import Path
|
from pathlib import Path
|
||||||
|
|
||||||
from .disks import Disk
|
from .disks import Disk
|
||||||
from .envfile import BUFFER_NAME, ENV_NAME, EnvCheck, EnvConfig, find_case_insensitive, parse_env
|
from .envfile import BUFFER_NAME, ENV_NAME, EnvCheck, EnvConfig, find_case_insensitive, parse_env
|
||||||
|
|
||||||
VOLUME_LABEL = "KOTA"
|
VOLUME_LABEL = "KOTA"
|
||||||
|
|
||||||
|
|
||||||
@dataclass
|
@dataclass
|
||||||
class Outcome:
|
class Outcome:
|
||||||
ok: bool
|
ok: bool
|
||||||
message: str
|
message: str
|
||||||
mount: str = ""
|
mount: str = ""
|
||||||
log: list[str] = field(default_factory=list)
|
log: list[str] = field(default_factory=list)
|
||||||
|
|
||||||
|
|
||||||
@dataclass
|
@dataclass
|
||||||
class CardReport:
|
class CardReport:
|
||||||
mount: str
|
mount: str
|
||||||
filesystem: str
|
filesystem: str
|
||||||
env: EnvCheck | None
|
env: EnvCheck | None
|
||||||
buffered_lines: int | None # measurements waiting on the card for upload
|
buffered_lines: int | None # measurements waiting on the card for upload
|
||||||
problems: list[str]
|
problems: list[str]
|
||||||
|
|
||||||
|
|
||||||
# ----------------------------------------------------------------- Windows
|
# ----------------------------------------------------------------- Windows
|
||||||
|
|
||||||
WORK_ROOT = Path.home() / "KotaTechnicianTool" / "tmp"
|
WORK_ROOT = Path.home() / "KotaTechnicianTool" / "tmp"
|
||||||
|
|
||||||
|
|
||||||
def _workdir() -> Path:
|
def _workdir() -> Path:
|
||||||
# Not tempfile.mkdtemp(): on Windows it creates an owner-only folder, and a
|
# 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
|
# file written there by the ELEVATED script is then unreadable for this
|
||||||
# (non-elevated) process. A normally inherited ACL works for both.
|
# (non-elevated) process. A normally inherited ACL works for both.
|
||||||
work = WORK_ROOT / f"sd_{uuid.uuid4().hex[:10]}"
|
work = WORK_ROOT / f"sd_{uuid.uuid4().hex[:10]}"
|
||||||
work.mkdir(parents=True, exist_ok=False)
|
work.mkdir(parents=True, exist_ok=False)
|
||||||
return work
|
return work
|
||||||
|
|
||||||
|
|
||||||
def win_format_command(disk: Disk, result: Path) -> tuple[str, str, str]:
|
def win_format_command(disk: Disk, result: Path) -> tuple[str, str, str]:
|
||||||
"""(program, parameters, working dir) for the elevated helper."""
|
"""(program, parameters, working dir) for the elevated helper."""
|
||||||
root = Path(__file__).resolve().parents[2] # the version folder holding kota_tech/
|
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)} ' \
|
params = f'-m kota_tech.sd.win_format --disk {int(disk.id)} --size {int(disk.size)} ' \
|
||||||
f'--label {VOLUME_LABEL} --result "{result}"'
|
f'--label {VOLUME_LABEL} --result "{result}"'
|
||||||
return sys.executable, params, str(root)
|
return sys.executable, params, str(root)
|
||||||
|
|
||||||
|
|
||||||
def _run_elevated(program: str, params: str, cwd: str, timeout_s: int = 300) -> int | None:
|
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."""
|
"""ShellExecuteEx 'runas' + wait. None if the technician refused the UAC prompt."""
|
||||||
import ctypes
|
import ctypes
|
||||||
from ctypes import wintypes
|
from ctypes import wintypes
|
||||||
|
|
||||||
class SHELLEXECUTEINFOW(ctypes.Structure):
|
class SHELLEXECUTEINFOW(ctypes.Structure):
|
||||||
_fields_ = [("cbSize", wintypes.DWORD), ("fMask", ctypes.c_ulong), ("hwnd", wintypes.HWND),
|
_fields_ = [("cbSize", wintypes.DWORD), ("fMask", ctypes.c_ulong), ("hwnd", wintypes.HWND),
|
||||||
("lpVerb", wintypes.LPCWSTR), ("lpFile", wintypes.LPCWSTR), ("lpParameters", wintypes.LPCWSTR),
|
("lpVerb", wintypes.LPCWSTR), ("lpFile", wintypes.LPCWSTR), ("lpParameters", wintypes.LPCWSTR),
|
||||||
("lpDirectory", wintypes.LPCWSTR), ("nShow", ctypes.c_int), ("hInstApp", wintypes.HINSTANCE),
|
("lpDirectory", wintypes.LPCWSTR), ("nShow", ctypes.c_int), ("hInstApp", wintypes.HINSTANCE),
|
||||||
("lpIDList", ctypes.c_void_p), ("lpClass", wintypes.LPCWSTR), ("hkeyClass", wintypes.HKEY),
|
("lpIDList", ctypes.c_void_p), ("lpClass", wintypes.LPCWSTR), ("hkeyClass", wintypes.HKEY),
|
||||||
("dwHotKey", wintypes.DWORD), ("hIconOrMonitor", wintypes.HANDLE), ("hProcess", wintypes.HANDLE)]
|
("dwHotKey", wintypes.DWORD), ("hIconOrMonitor", wintypes.HANDLE), ("hProcess", wintypes.HANDLE)]
|
||||||
|
|
||||||
SEE_MASK_NOCLOSEPROCESS, SW_HIDE = 0x40, 0
|
SEE_MASK_NOCLOSEPROCESS, SW_HIDE = 0x40, 0
|
||||||
info = SHELLEXECUTEINFOW(cbSize=ctypes.sizeof(SHELLEXECUTEINFOW), fMask=SEE_MASK_NOCLOSEPROCESS,
|
info = SHELLEXECUTEINFOW(cbSize=ctypes.sizeof(SHELLEXECUTEINFOW), fMask=SEE_MASK_NOCLOSEPROCESS,
|
||||||
lpVerb="runas", lpFile=program, lpParameters=params, lpDirectory=cwd, nShow=SW_HIDE)
|
lpVerb="runas", lpFile=program, lpParameters=params, lpDirectory=cwd, nShow=SW_HIDE)
|
||||||
shell32 = ctypes.WinDLL("shell32", use_last_error=True)
|
shell32 = ctypes.WinDLL("shell32", use_last_error=True)
|
||||||
k32 = ctypes.WinDLL("kernel32", use_last_error=True)
|
k32 = ctypes.WinDLL("kernel32", use_last_error=True)
|
||||||
if not shell32.ShellExecuteExW(ctypes.byref(info)):
|
if not shell32.ShellExecuteExW(ctypes.byref(info)):
|
||||||
return None # ERROR_CANCELLED (1223) or failure
|
return None # ERROR_CANCELLED (1223) or failure
|
||||||
k32.WaitForSingleObject(info.hProcess, timeout_s * 1000)
|
k32.WaitForSingleObject(info.hProcess, timeout_s * 1000)
|
||||||
code = wintypes.DWORD()
|
code = wintypes.DWORD()
|
||||||
k32.GetExitCodeProcess(info.hProcess, ctypes.byref(code))
|
k32.GetExitCodeProcess(info.hProcess, ctypes.byref(code))
|
||||||
k32.CloseHandle(info.hProcess)
|
k32.CloseHandle(info.hProcess)
|
||||||
return code.value
|
return code.value
|
||||||
|
|
||||||
|
|
||||||
def _format_windows(disk: Disk, log: list[str]) -> Outcome:
|
def _format_windows(disk: Disk, log: list[str]) -> Outcome:
|
||||||
result = _workdir() / "result.json"
|
result = _workdir() / "result.json"
|
||||||
log.append("Asking Windows for administrator rights to format the card (UAC prompt)...")
|
log.append("Asking Windows for administrator rights to format the card (UAC prompt)...")
|
||||||
t = time.perf_counter()
|
t = time.perf_counter()
|
||||||
code = _run_elevated(*win_format_command(disk, result))
|
code = _run_elevated(*win_format_command(disk, result))
|
||||||
if code is None:
|
if code is None:
|
||||||
return Outcome(False, "Administrator permission was refused - the card was not formatted.", log=log)
|
return Outcome(False, "Administrator permission was refused - the card was not formatted.", log=log)
|
||||||
try:
|
try:
|
||||||
res = json.loads(result.read_text(encoding="utf-8"))
|
res = json.loads(result.read_text(encoding="utf-8"))
|
||||||
except (OSError, ValueError) as exc:
|
except (OSError, ValueError) as exc:
|
||||||
return Outcome(False, f"The formatter did not report back ({exc.__class__.__name__}, exit {code}). "
|
return Outcome(False, f"The formatter did not report back ({exc.__class__.__name__}, exit {code}). "
|
||||||
"Check the card with 'Check card'.", log=log)
|
"Check the card with 'Check card'.", log=log)
|
||||||
steps = ", ".join(f"{k} {v:.1f} s" for k, v in res.get("timings", {}).items())
|
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})")
|
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)
|
return Outcome(bool(res.get("ok")), res.get("message", ""), res.get("drive", ""), log)
|
||||||
|
|
||||||
|
|
||||||
def _eject_windows(mount: str) -> bool:
|
def _eject_windows(mount: str) -> bool:
|
||||||
"""Flush, lock, dismount and eject the card - what 'Safely Remove' does.
|
"""Flush, lock, dismount and eject the card - what 'Safely Remove' does.
|
||||||
|
|
||||||
Not Shell.Application InvokeVerb('Eject'): it fails silently because the
|
Not Shell.Application InvokeVerb('Eject'): it fails silently because the
|
||||||
verb is named 'E&ject' (and is localised on non-English Windows).
|
verb is named 'E&ject' (and is localised on non-English Windows).
|
||||||
"""
|
"""
|
||||||
import ctypes
|
import ctypes
|
||||||
from ctypes import wintypes
|
from ctypes import wintypes
|
||||||
|
|
||||||
k32 = ctypes.WinDLL("kernel32", use_last_error=True)
|
k32 = ctypes.WinDLL("kernel32", use_last_error=True)
|
||||||
k32.CreateFileW.restype = wintypes.HANDLE
|
k32.CreateFileW.restype = wintypes.HANDLE
|
||||||
k32.CreateFileW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, wintypes.LPVOID,
|
k32.CreateFileW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, wintypes.LPVOID,
|
||||||
wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE]
|
wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE]
|
||||||
k32.DeviceIoControl.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.LPVOID, wintypes.DWORD,
|
k32.DeviceIoControl.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.LPVOID, wintypes.DWORD,
|
||||||
wintypes.LPVOID, wintypes.DWORD, ctypes.POINTER(wintypes.DWORD), wintypes.LPVOID]
|
wintypes.LPVOID, wintypes.DWORD, ctypes.POINTER(wintypes.DWORD), wintypes.LPVOID]
|
||||||
GENERIC_RW, SHARE_RW, OPEN_EXISTING = 0xC0000000, 0x3, 3
|
GENERIC_RW, SHARE_RW, OPEN_EXISTING = 0xC0000000, 0x3, 3
|
||||||
FSCTL_LOCK_VOLUME, FSCTL_DISMOUNT_VOLUME = 0x00090018, 0x00090020
|
FSCTL_LOCK_VOLUME, FSCTL_DISMOUNT_VOLUME = 0x00090018, 0x00090020
|
||||||
IOCTL_STORAGE_MEDIA_REMOVAL, IOCTL_STORAGE_EJECT_MEDIA = 0x002D4804, 0x002D4808
|
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)
|
handle = k32.CreateFileW(f"\\\\.\\{mount[0]}:", GENERIC_RW, SHARE_RW, None, OPEN_EXISTING, 0, None)
|
||||||
if handle in (None, wintypes.HANDLE(-1).value):
|
if handle in (None, wintypes.HANDLE(-1).value):
|
||||||
return False
|
return False
|
||||||
ret = wintypes.DWORD()
|
ret = wintypes.DWORD()
|
||||||
|
|
||||||
def ioctl(code: int, buf=None, size: int = 0) -> bool:
|
def ioctl(code: int, buf=None, size: int = 0) -> bool:
|
||||||
return bool(k32.DeviceIoControl(handle, code, buf, size, None, 0, ctypes.byref(ret), None))
|
return bool(k32.DeviceIoControl(handle, code, buf, size, None, 0, ctypes.byref(ret), None))
|
||||||
|
|
||||||
try:
|
try:
|
||||||
k32.FlushFileBuffers(handle)
|
k32.FlushFileBuffers(handle)
|
||||||
for _ in range(10): # Explorer/indexer may hold it briefly
|
for _ in range(10): # Explorer/indexer may hold it briefly
|
||||||
if ioctl(FSCTL_LOCK_VOLUME):
|
if ioctl(FSCTL_LOCK_VOLUME):
|
||||||
break
|
break
|
||||||
time.sleep(0.5)
|
time.sleep(0.5)
|
||||||
else:
|
else:
|
||||||
return False
|
return False
|
||||||
if not ioctl(FSCTL_DISMOUNT_VOLUME):
|
if not ioctl(FSCTL_DISMOUNT_VOLUME):
|
||||||
return False
|
return False
|
||||||
allow = ctypes.c_bool(False) # PREVENT_MEDIA_REMOVAL{FALSE}
|
allow = ctypes.c_bool(False) # PREVENT_MEDIA_REMOVAL{FALSE}
|
||||||
ioctl(IOCTL_STORAGE_MEDIA_REMOVAL, ctypes.byref(allow), 1)
|
ioctl(IOCTL_STORAGE_MEDIA_REMOVAL, ctypes.byref(allow), 1)
|
||||||
ioctl(IOCTL_STORAGE_EJECT_MEDIA) # card readers may not support it; dismount suffices
|
ioctl(IOCTL_STORAGE_EJECT_MEDIA) # card readers may not support it; dismount suffices
|
||||||
return True
|
return True
|
||||||
finally:
|
finally:
|
||||||
k32.CloseHandle(handle)
|
k32.CloseHandle(handle)
|
||||||
|
|
||||||
|
|
||||||
# ------------------------------------------------------------------- macOS
|
# ------------------------------------------------------------------- macOS
|
||||||
|
|
||||||
def _format_macos(disk: Disk, log: list[str]) -> Outcome:
|
def _format_macos(disk: Disk, log: list[str]) -> Outcome:
|
||||||
log.append(f"diskutil eraseDisk FAT32 {VOLUME_LABEL} MBRFormat {disk.id}")
|
log.append(f"diskutil eraseDisk FAT32 {VOLUME_LABEL} MBRFormat {disk.id}")
|
||||||
proc = subprocess.run(["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)
|
capture_output=True, text=True, timeout=600)
|
||||||
log += [l for l in proc.stdout.splitlines() if l.strip()]
|
log += [l for l in proc.stdout.splitlines() if l.strip()]
|
||||||
if proc.returncode != 0:
|
if proc.returncode != 0:
|
||||||
return Outcome(False, "Formatting failed: " + (proc.stderr.strip() or proc.stdout.strip()[-200:])
|
return Outcome(False, "Formatting failed: " + (proc.stderr.strip() or proc.stdout.strip()[-200:])
|
||||||
+ " (is the card's write-protect switch on?)", log=log)
|
+ " (is the card's write-protect switch on?)", log=log)
|
||||||
part = f"{disk.id}s1"
|
part = f"{disk.id}s1"
|
||||||
for _ in range(20): # wait for the volume to mount
|
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>")
|
info = plistlib.loads(subprocess.run(["diskutil", "info", "-plist", part], capture_output=True).stdout or b"<plist><dict/></plist>")
|
||||||
if info.get("MountPoint"):
|
if info.get("MountPoint"):
|
||||||
return Outcome(True, "Formatted FAT32 (MBR).", info["MountPoint"], log)
|
return Outcome(True, "Formatted FAT32 (MBR).", info["MountPoint"], log)
|
||||||
time.sleep(0.5)
|
time.sleep(0.5)
|
||||||
return Outcome(False, "Formatted, but the card did not mount.", log=log)
|
return Outcome(False, "Formatted, but the card did not mount.", log=log)
|
||||||
|
|
||||||
|
|
||||||
def _eject_macos(disk_id: str) -> bool:
|
def _eject_macos(disk_id: str) -> bool:
|
||||||
return subprocess.run(["diskutil", "eject", disk_id], capture_output=True, timeout=60).returncode == 0
|
return subprocess.run(["diskutil", "eject", disk_id], capture_output=True, timeout=60).returncode == 0
|
||||||
|
|
||||||
|
|
||||||
# ------------------------------------------------------------------ common
|
# ------------------------------------------------------------------ common
|
||||||
|
|
||||||
def write_env(mount: str, env: EnvConfig) -> Outcome:
|
def write_env(mount: str, env: EnvConfig) -> Outcome:
|
||||||
"""Write ENV.TXT (8.3 name, LF, no BOM), keep other files (buffered data), read back."""
|
"""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"]
|
problems = [i.text for i in env.problems() if i.level == "error"]
|
||||||
if problems:
|
if problems:
|
||||||
return Outcome(False, "Settings are not valid: " + " ".join(problems))
|
return Outcome(False, "Settings are not valid: " + " ".join(problems))
|
||||||
root = Path(mount)
|
root = Path(mount)
|
||||||
if not root.is_dir():
|
if not root.is_dir():
|
||||||
return Outcome(False, f"Card not found at {mount}.")
|
return Outcome(False, f"Card not found at {mount}.")
|
||||||
old = find_case_insensitive(root, ENV_NAME)
|
old = find_case_insensitive(root, ENV_NAME)
|
||||||
if old is not None and old.name != ENV_NAME:
|
if old is not None and old.name != ENV_NAME:
|
||||||
old.unlink() # replace env.txt / Env.txt variants
|
old.unlink() # replace env.txt / Env.txt variants
|
||||||
target = root / ENV_NAME
|
target = root / ENV_NAME
|
||||||
data = env.render()
|
data = env.render()
|
||||||
with open(target, "wb") as fh:
|
with open(target, "wb") as fh:
|
||||||
fh.write(data)
|
fh.write(data)
|
||||||
fh.flush()
|
fh.flush()
|
||||||
os.fsync(fh.fileno())
|
os.fsync(fh.fileno())
|
||||||
if target.read_bytes() != data:
|
if target.read_bytes() != data:
|
||||||
return Outcome(False, "ENV.TXT read-back does not match - the card may be faulty.")
|
return Outcome(False, "ENV.TXT read-back does not match - the card may be faulty.")
|
||||||
check = parse_env(target.read_bytes())
|
check = parse_env(target.read_bytes())
|
||||||
if not check.ok:
|
if not check.ok:
|
||||||
return Outcome(False, "ENV.TXT was written but does not validate: "
|
return Outcome(False, "ENV.TXT was written but does not validate: "
|
||||||
+ " ".join(i.text for i in check.issues if i.level == "error"))
|
+ " ".join(i.text for i in check.issues if i.level == "error"))
|
||||||
return Outcome(True, f"ENV.TXT written and verified on {mount}.", mount)
|
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:
|
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"]
|
problems = [i.text for i in env.problems() if i.level == "error"]
|
||||||
if problems:
|
if problems:
|
||||||
return Outcome(False, "Settings are not valid: " + " ".join(problems))
|
return Outcome(False, "Settings are not valid: " + " ".join(problems))
|
||||||
log: list[str] = []
|
log: list[str] = []
|
||||||
if sys.platform == "win32":
|
if sys.platform == "win32":
|
||||||
fmt = _format_windows(disk, log)
|
fmt = _format_windows(disk, log)
|
||||||
elif sys.platform == "darwin":
|
elif sys.platform == "darwin":
|
||||||
fmt = _format_macos(disk, log)
|
fmt = _format_macos(disk, log)
|
||||||
else:
|
else:
|
||||||
return Outcome(False, "SD provisioning is supported on Windows and macOS only.")
|
return Outcome(False, "SD provisioning is supported on Windows and macOS only.")
|
||||||
if not fmt.ok:
|
if not fmt.ok:
|
||||||
return fmt
|
return fmt
|
||||||
wr = write_env(fmt.mount, env)
|
wr = write_env(fmt.mount, env)
|
||||||
log.append(wr.message)
|
log.append(wr.message)
|
||||||
if not wr.ok:
|
if not wr.ok:
|
||||||
return Outcome(False, wr.message, fmt.mount, log)
|
return Outcome(False, wr.message, fmt.mount, log)
|
||||||
if eject_card:
|
if eject_card:
|
||||||
log.append("Card ejected - you can remove it." if eject(fmt.mount, disk) else
|
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.")
|
"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)
|
return Outcome(True, "Card ready: formatted FAT32 and ENV.TXT verified.", fmt.mount, log)
|
||||||
|
|
||||||
|
|
||||||
def eject(mount: str, disk: Disk | None = None) -> bool:
|
def eject(mount: str, disk: Disk | None = None) -> bool:
|
||||||
"""True if the card was dismounted and can be pulled out safely."""
|
"""True if the card was dismounted and can be pulled out safely."""
|
||||||
if sys.platform == "win32":
|
if sys.platform == "win32":
|
||||||
return _eject_windows(mount)
|
return _eject_windows(mount)
|
||||||
if sys.platform == "darwin" and disk is not None:
|
if sys.platform == "darwin" and disk is not None:
|
||||||
return _eject_macos(disk.id)
|
return _eject_macos(disk.id)
|
||||||
return False
|
return False
|
||||||
|
|
||||||
|
|
||||||
def check_card(mount: str, filesystem: str = "") -> CardReport:
|
def check_card(mount: str, filesystem: str = "") -> CardReport:
|
||||||
"""What the box would find on this card (values masked in the UI)."""
|
"""What the box would find on this card (values masked in the UI)."""
|
||||||
root = Path(mount)
|
root = Path(mount)
|
||||||
problems: list[str] = []
|
problems: list[str] = []
|
||||||
# Windows says "FAT32"; macOS diskutil says "DOS_FAT_32" / "Windows_FAT_32" / "MS-DOS FAT32".
|
# Windows says "FAT32"; macOS diskutil says "DOS_FAT_32" / "Windows_FAT_32" / "MS-DOS FAT32".
|
||||||
fs = filesystem.upper().replace("_", "").replace(" ", "")
|
fs = filesystem.upper().replace("_", "").replace(" ", "")
|
||||||
if fs and "FAT32" not in fs and fs not in ("FAT", "MSDOS"):
|
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.")
|
problems.append(f"File system is {filesystem}; the box needs FAT32 - re-format the card.")
|
||||||
env_file = find_case_insensitive(root, ENV_NAME)
|
env_file = find_case_insensitive(root, ENV_NAME)
|
||||||
env = parse_env(env_file.read_bytes()) if env_file else None
|
env = parse_env(env_file.read_bytes()) if env_file else None
|
||||||
if env_file is None:
|
if env_file is None:
|
||||||
problems.append("No ENV.TXT on the card - the box stops at start-up (white LED).")
|
problems.append("No ENV.TXT on the card - the box stops at start-up (white LED).")
|
||||||
elif len(env_file.name.split(".")[0]) > 8:
|
elif len(env_file.name.split(".")[0]) > 8:
|
||||||
problems.append("ENV.TXT has a long name variant; use exactly ENV.TXT.")
|
problems.append("ENV.TXT has a long name variant; use exactly ENV.TXT.")
|
||||||
buf = find_case_insensitive(root, BUFFER_NAME)
|
buf = find_case_insensitive(root, BUFFER_NAME)
|
||||||
lines = None
|
lines = None
|
||||||
if buf is not None:
|
if buf is not None:
|
||||||
with open(buf, "rb") as fh:
|
with open(buf, "rb") as fh:
|
||||||
lines = sum(1 for ln in fh if ln.strip())
|
lines = sum(1 for ln in fh if ln.strip())
|
||||||
return CardReport(mount, filesystem, env, lines, problems)
|
return CardReport(mount, filesystem, env, lines, problems)
|
||||||
+155
-155
@@ -1,155 +1,155 @@
|
|||||||
"""Hand-off of a diagnosis to the KOTA service system (Google Apps Script).
|
"""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:
|
The tool opens the box's service page in the technician's browser:
|
||||||
<base><MAC>#kota-report=<base64url(JSON)>
|
<base><MAC>#kota-report=<base64url(JSON)>
|
||||||
The service page (v1.1.0+) reads the fragment and pre-fills status and note;
|
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
|
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.
|
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).
|
The fragment is never sent to any server (redirect host or Apps Script).
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
import base64
|
import base64
|
||||||
import json
|
import json
|
||||||
import re
|
import re
|
||||||
|
|
||||||
from .. import __version__
|
from .. import __version__
|
||||||
from ..diag.engine import Report, Severity
|
from ..diag.engine import Report, Severity
|
||||||
|
|
||||||
DEFAULT_BASE = "https://service.kota-app.com/"
|
DEFAULT_BASE = "https://service.kota-app.com/"
|
||||||
NOTE_LIMIT = 4800 # the service form and Code.gs accept 5000; leave room for the technician
|
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).
|
# Status names exactly as in the service system (Code.gs STATUSES).
|
||||||
OK = "Działa poprawnie"
|
OK = "Działa poprawnie"
|
||||||
CHECK = "Do sprawdzenia"
|
CHECK = "Do sprawdzenia"
|
||||||
IN_SERVICE = "W trakcie serwisu"
|
IN_SERVICE = "W trakcie serwisu"
|
||||||
HARDWARE = "Błąd hardware"
|
HARDWARE = "Błąd hardware"
|
||||||
SOFTWARE = "Błąd software"
|
SOFTWARE = "Błąd software"
|
||||||
POWER = "Problem z zasilaniem"
|
POWER = "Problem z zasilaniem"
|
||||||
CONNECTIVITY = "Problem z łącznością"
|
CONNECTIVITY = "Problem z łącznością"
|
||||||
|
|
||||||
# Root-finding rule id prefix -> service status (first match wins).
|
# Root-finding rule id prefix -> service status (first match wins).
|
||||||
_STATUS_BY_RULE = [
|
_STATUS_BY_RULE = [
|
||||||
("reboot.brownout", POWER), ("reboot.power", POWER), ("tech.power.", POWER),
|
("reboot.brownout", POWER), ("reboot.power", POWER), ("tech.power.", POWER),
|
||||||
("sys.crash", SOFTWARE), ("reboot.watchdog", SOFTWARE), ("sys.out_of_resources", SOFTWARE),
|
("sys.crash", SOFTWARE), ("reboot.watchdog", SOFTWARE), ("sys.out_of_resources", SOFTWARE),
|
||||||
("influx.bad_request", SOFTWARE), ("ota.selfcheck_failed", SOFTWARE), ("tech.quick.hung", 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),
|
("rtc.init_failed", HARDWARE), ("rtc.lost_after_sync", HARDWARE), ("i2c.", HARDWARE), ("sensor.", HARDWARE),
|
||||||
("sd.", HARDWARE), ("sen66.", HARDWARE), ("bme688.", HARDWARE), ("as7341.", HARDWARE),
|
("sd.", HARDWARE), ("sen66.", HARDWARE), ("bme688.", HARDWARE), ("as7341.", HARDWARE),
|
||||||
("mic.read_fail", HARDWARE), ("mic.silent", HARDWARE), ("tech.rtc_i2c.", HARDWARE), ("tech.sensors.", 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),
|
("tech.mic.mic_faulty", HARDWARE), ("tech.mic.mic_switch_faulty", HARDWARE), ("tech.white.sd_", HARDWARE),
|
||||||
("matter.", CONNECTIVITY), ("net.", CONNECTIVITY), ("wifi.", CONNECTIVITY), ("influx.", CONNECTIVITY),
|
("matter.", CONNECTIVITY), ("net.", CONNECTIVITY), ("wifi.", CONNECTIVITY), ("influx.", CONNECTIVITY),
|
||||||
("ota.", CONNECTIVITY), ("tech.network.", CONNECTIVITY),
|
("ota.", CONNECTIVITY), ("tech.network.", CONNECTIVITY),
|
||||||
# firmware 1.0.16+ (KOTA: lines, status, error IDs)
|
# firmware 1.0.16+ (KOTA: lines, status, error IDs)
|
||||||
("reboot.crash", SOFTWARE), ("reboot.status_oom_watchdog", SOFTWARE), ("status.oom", SOFTWARE),
|
("reboot.crash", SOFTWARE), ("reboot.status_oom_watchdog", SOFTWARE), ("status.oom", SOFTWARE),
|
||||||
("kota.low_heap", SOFTWARE),
|
("kota.low_heap", SOFTWARE),
|
||||||
("kota.i2c_stuck", HARDWARE), ("kota.sensor_missing", HARDWARE), ("kota.rtc_", HARDWARE),
|
("kota.i2c_stuck", HARDWARE), ("kota.sensor_missing", HARDWARE), ("kota.rtc_", HARDWARE),
|
||||||
("kota.sd_", HARDWARE), ("status.error", HARDWARE), ("status.rtc", HARDWARE), ("status.sd", 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.wifi_down", CONNECTIVITY), ("kota.weak_wifi", CONNECTIVITY), ("kota.no_upload", CONNECTIVITY),
|
||||||
("kota.ota_unregistered", CONNECTIVITY), ("kota.buffer_backlog", CONNECTIVITY), ("status.conn", CONNECTIVITY),
|
("kota.ota_unregistered", CONNECTIVITY), ("kota.buffer_backlog", CONNECTIVITY), ("status.conn", CONNECTIVITY),
|
||||||
("kota.time_invalid", CHECK),
|
("kota.time_invalid", CHECK),
|
||||||
*((f"eid.{m}", HARDWARE) for m in ("SD", "ENV", "RTC", "BME", "SEN", "AS", "MIC", "FLK", "SPI")),
|
*((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")),
|
*((f"eid.{m}", CONNECTIVITY) for m in ("INF", "WIFI", "OTA", "PROV")),
|
||||||
("eid.", SOFTWARE),
|
("eid.", SOFTWARE),
|
||||||
("rtc.clock_not_running", CHECK), ("reboot.", CHECK),
|
("rtc.clock_not_running", CHECK), ("reboot.", CHECK),
|
||||||
]
|
]
|
||||||
_MAC = re.compile(r"^[0-9A-F]{12}$")
|
_MAC = re.compile(r"^[0-9A-F]{12}$")
|
||||||
|
|
||||||
|
|
||||||
def normalize_mac(mac: str) -> str:
|
def normalize_mac(mac: str) -> str:
|
||||||
return re.sub(r"[^0-9A-Fa-f]", "", mac or "").upper()
|
return re.sub(r"[^0-9A-Fa-f]", "", mac or "").upper()
|
||||||
|
|
||||||
|
|
||||||
def service_status(report: Report) -> str:
|
def service_status(report: Report) -> str:
|
||||||
"""Suggested status; the technician can change it in the form."""
|
"""Suggested status; the technician can change it in the form."""
|
||||||
problems = [rc for rc in report.roots if rc.severity >= Severity.WARNING]
|
problems = [rc for rc in report.roots if rc.severity >= Severity.WARNING]
|
||||||
if not problems:
|
if not problems:
|
||||||
return OK if any(m == "data_uploaded" and t is not None for m, _, t in report.milestones) else CHECK
|
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
|
rid = problems[0].finding.rule_id
|
||||||
for prefix, status in _STATUS_BY_RULE:
|
for prefix, status in _STATUS_BY_RULE:
|
||||||
if rid.startswith(prefix):
|
if rid.startswith(prefix):
|
||||||
return status
|
return status
|
||||||
return CHECK
|
return CHECK
|
||||||
|
|
||||||
|
|
||||||
BOX_MARK = {"ok": "✔", "warn": "!", "bad": "✖", "info": "i"} # same marks as the Diagnosis panel
|
BOX_MARK = {"ok": "✔", "warn": "!", "bad": "✖", "info": "i"} # same marks as the Diagnosis panel
|
||||||
SD_WIFI = {True: "reads Wi-Fi settings from the SD card",
|
SD_WIFI = {True: "reads Wi-Fi settings from the SD card",
|
||||||
False: "does not read 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"}
|
None: "Wi-Fi-from-SD support unknown"}
|
||||||
|
|
||||||
|
|
||||||
def service_note(report: Report, limit: int = NOTE_LIMIT) -> str:
|
def service_note(report: Report, limit: int = NOTE_LIMIT) -> str:
|
||||||
"""The Diagnosis panel as text: verdict, LED, firmware, box self-report,
|
"""The Diagnosis panel as text: verdict, LED, firmware, box self-report,
|
||||||
start-up progress with times, findings with details and when they were seen.
|
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
|
Falls back to shorter finding details when the full text does not fit the
|
||||||
service form (consequences' explanations first, then all), then truncates.
|
service form (consequences' explanations first, then all), then truncates.
|
||||||
"""
|
"""
|
||||||
for detail in ("all", "roots", "none"):
|
for detail in ("all", "roots", "none"):
|
||||||
text = _note(report, detail)
|
text = _note(report, detail)
|
||||||
if len(text) <= limit:
|
if len(text) <= limit:
|
||||||
return text
|
return text
|
||||||
return text[:limit - 20].rstrip() + "\n...(shortened)"
|
return text[:limit - 20].rstrip() + "\n...(shortened)"
|
||||||
|
|
||||||
|
|
||||||
def _note(report: Report, detail: str) -> str:
|
def _note(report: Report, detail: str) -> str:
|
||||||
fw = report.firmware
|
fw = report.firmware
|
||||||
source = " (reported by the box)" if report.led_exact else ""
|
source = " (reported by the box)" if report.led_exact else ""
|
||||||
lines = [f"[KOTA Technician Tool {__version__}] {report.verdict}", "",
|
lines = [f"[KOTA Technician Tool {__version__}] {report.verdict}", "",
|
||||||
f"Status LED should be: {report.led_text()}{source}"]
|
f"Status LED should be: {report.led_text()}{source}"]
|
||||||
if report.led_reason:
|
if report.led_reason:
|
||||||
lines.append(f" from: {report.led_reason}")
|
lines.append(f" from: {report.led_reason}")
|
||||||
lines += ["", f"Firmware: {fw.describe()}", f" {SD_WIFI[fw.supports_sd_wifi]}"]
|
lines += ["", f"Firmware: {fw.describe()}", f" {SD_WIFI[fw.supports_sd_wifi]}"]
|
||||||
if report.box:
|
if report.box:
|
||||||
lines += ["", "Box self-report (KOTA lines):"]
|
lines += ["", "Box self-report (KOTA lines):"]
|
||||||
lines += [f" {BOX_MARK.get(st, '-')} {topic}: {text}" for topic, text, st in report.box]
|
lines += [f" {BOX_MARK.get(st, '-')} {topic}: {text}" for topic, text, st in report.box]
|
||||||
lines += ["", "Start-up progress (current boot):"]
|
lines += ["", "Start-up progress (current boot):"]
|
||||||
lines += [f" ✔ {label} ({t / 1000:.1f} s)" if t is not None else f" ○ {label}"
|
lines += [f" ✔ {label} ({t / 1000:.1f} s)" if t is not None else f" ○ {label}"
|
||||||
for _, label, t in report.milestones]
|
for _, label, t in report.milestones]
|
||||||
lines += ["", "Findings - root causes first:" if report.roots else "Findings: no problems detected in the log"]
|
lines += ["", "Findings - root causes first:" if report.roots else "Findings: no problems detected in the log"]
|
||||||
for rc in report.roots:
|
for rc in report.roots:
|
||||||
lines += _finding(rc.finding, "", detail in ("all", "roots"))
|
lines += _finding(rc.finding, "", detail in ("all", "roots"))
|
||||||
for c in rc.consequences:
|
for c in rc.consequences:
|
||||||
lines += _finding(c, " ↳ ", detail == "all")
|
lines += _finding(c, " ↳ ", detail == "all")
|
||||||
for title, items in (("Seen in earlier boots only", report.earlier),
|
for title, items in (("Seen in earlier boots only", report.earlier),
|
||||||
("Resolved during this session", report.resolved)):
|
("Resolved during this session", report.resolved)):
|
||||||
if items:
|
if items:
|
||||||
lines += ["", f"{title} ({len(items)}):"]
|
lines += ["", f"{title} ({len(items)}):"]
|
||||||
lines += [f" - [{f.severity.label}] {f.title} - {f.seen_text()}" for f in items]
|
lines += [f" - [{f.severity.label}] {f.title} - {f.seen_text()}" for f in items]
|
||||||
if report.technician:
|
if report.technician:
|
||||||
lines += ["", "Technician checks:"]
|
lines += ["", "Technician checks:"]
|
||||||
lines += [f" * {t}" for t in report.technician[-12:]]
|
lines += [f" * {t}" for t in report.technician[-12:]]
|
||||||
return "\n".join(lines)
|
return "\n".join(lines)
|
||||||
|
|
||||||
|
|
||||||
def _finding(f, prefix: str, detailed: bool) -> list[str]:
|
def _finding(f, prefix: str, detailed: bool) -> list[str]:
|
||||||
ind = " " * len(prefix) + " "
|
ind = " " * len(prefix) + " "
|
||||||
out = [f"{prefix}[{f.severity.label}] {f.title}"]
|
out = [f"{prefix}[{f.severity.label}] {f.title}"]
|
||||||
if detailed:
|
if detailed:
|
||||||
out.append(f"{ind}What it means: {f.meaning}")
|
out.append(f"{ind}What it means: {f.meaning}")
|
||||||
if f.actions:
|
if f.actions:
|
||||||
out.append(f"{ind}What to do:")
|
out.append(f"{ind}What to do:")
|
||||||
out += [f"{ind} {i}. {a}" for i, a in enumerate(f.actions, 1)]
|
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 += [f"{ind}Error {eid}" + (f": {a}" if a else "") for eid, a in f.error_ids.items()]
|
||||||
out.append(f"{ind}{f.seen_text()}")
|
out.append(f"{ind}{f.seen_text()}")
|
||||||
if f.evidence:
|
if f.evidence:
|
||||||
out.append(f"{ind}Log: {f.evidence[-1]}")
|
out.append(f"{ind}Log: {f.evidence[-1]}")
|
||||||
return out
|
return out
|
||||||
|
|
||||||
|
|
||||||
def report_url(mac: str, report: Report, base: str = DEFAULT_BASE) -> str:
|
def report_url(mac: str, report: Report, base: str = DEFAULT_BASE) -> str:
|
||||||
mac = normalize_mac(mac)
|
mac = normalize_mac(mac)
|
||||||
if not _MAC.match(mac):
|
if not _MAC.match(mac):
|
||||||
raise ValueError(f"not a box MAC address: {mac!r}")
|
raise ValueError(f"not a box MAC address: {mac!r}")
|
||||||
payload = {"v": 1, "mac": mac, "status": service_status(report), "note": service_note(report),
|
payload = {"v": 1, "mac": mac, "status": service_status(report), "note": service_note(report),
|
||||||
"tool": f"v{__version__}"}
|
"tool": f"v{__version__}"}
|
||||||
raw = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
|
raw = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
|
||||||
frag = base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
|
frag = base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
|
||||||
base = base if base.endswith("/") else base + "/"
|
base = base if base.endswith("/") else base + "/"
|
||||||
return f"{base}{mac}#kota-report={frag}"
|
return f"{base}{mac}#kota-report={frag}"
|
||||||
|
|
||||||
|
|
||||||
def decode_fragment(url: str) -> dict:
|
def decode_fragment(url: str) -> dict:
|
||||||
"""Inverse of report_url (used by tests and for troubleshooting)."""
|
"""Inverse of report_url (used by tests and for troubleshooting)."""
|
||||||
frag = url.split("#kota-report=", 1)[1]
|
frag = url.split("#kota-report=", 1)[1]
|
||||||
return json.loads(base64.urlsafe_b64decode(frag + "=" * (-len(frag) % 4)).decode("utf-8"))
|
return json.loads(base64.urlsafe_b64decode(frag + "=" * (-len(frag) % 4)).decode("utf-8"))
|
||||||
+87
-87
@@ -1,87 +1,87 @@
|
|||||||
"""Quick-start cheat sheet shown on launch.
|
"""Quick-start cheat sheet shown on launch.
|
||||||
|
|
||||||
LED table for firmware 1.0.16+ (firmware-diagnostics-what-changed.md,
|
LED table for firmware 1.0.16+ (firmware-diagnostics-what-changed.md,
|
||||||
status.cpp Status::pattern_for): colour AND pattern name the fault. Older
|
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.
|
boxes (v1.0, built Jun 29 2026) show the same colours, always solid.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
# (swatch colour, LED name, pattern -> meaning, first action)
|
# (swatch colour, LED name, pattern -> meaning, first action)
|
||||||
LED_TABLE = [
|
LED_TABLE = [
|
||||||
("#2e9e44", "Green", "solid: everything OK.", "Nothing to do."),
|
("#2e9e44", "Green", "solid: everything OK.", "Nothing to do."),
|
||||||
("#1fc8d8", "Cyan",
|
("#1fc8d8", "Cyan",
|
||||||
"breathing: not paired in Matter yet<br>fast blink: a phone is connected for pairing.",
|
"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)."),
|
"Pair the box in the Matter app (QR sticker or the QR code in the tool)."),
|
||||||
("#f4f4f4", "White",
|
("#f4f4f4", "White",
|
||||||
"fast blink: SD card or ENV.TXT error<br>solid: factory reset (Matter button held 5 s)<br>"
|
"fast blink: SD card or ENV.TXT error<br>solid: factory reset (Matter button held 5 s)<br>"
|
||||||
"breathing: Wi-Fi setup portal.",
|
"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."),
|
"SD card is inside the case: re-seat or re-provision it. Setup portal: short-press the button to leave."),
|
||||||
("#d64541", "Red",
|
("#d64541", "Red",
|
||||||
"1-6 pulses: 1 BME688, 2 SEN66, 3 AS7341, 4 microphone, 5 flicker, 6 self-check failed<br>"
|
"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.",
|
"solid: other internal error / out of memory.",
|
||||||
"Count the pulses, then check that sensor's cable. The box restarts itself after 150 s."),
|
"Count the pulses, then check that sensor's cable. The box restarts itself after 150 s."),
|
||||||
("#2f6fd6", "Blue",
|
("#2f6fd6", "Blue",
|
||||||
"1 pulse: clock (RTC) not responding<br>2 pulses: I2C bus stuck (shorted / broken sensor cable).",
|
"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."),
|
"Check the I2C cable between the boards first, then the RTC module."),
|
||||||
("#8e44ad", "Purple",
|
("#8e44ad", "Purple",
|
||||||
"solid: no network<br>blinking: server rejected the box (wrong ENV.TXT credentials).",
|
"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."),
|
"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."),
|
("#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).",
|
("#f08c1a", "Orange", "solid: self-check after an update (~2.5 min).",
|
||||||
"Wait; should turn green (or red on failure)."),
|
"Wait; should turn green (or red on failure)."),
|
||||||
("#444444", "Off", "Firmware did not start (or crashed very early).",
|
("#444444", "Off", "Firmware did not start (or crashed very early).",
|
||||||
"Check power switch & USB cable. If the small LED is also dark: re-flash."),
|
"Check power switch & USB cable. If the small LED is also dark: re-flash."),
|
||||||
]
|
]
|
||||||
|
|
||||||
HINTS = [
|
HINTS = [
|
||||||
"<b>Before a self-restart</b> the LED flashes the error colour 3 times; <b>after the restart</b> it "
|
"<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 "
|
"shows the previous error for 3 s. So a reboot loop shows its cause. Connect serial and press "
|
||||||
"<i>Reset & capture</i>: the tool reads the restart reason from the box.",
|
"<i>Reset & 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, "
|
"<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.",
|
"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, "
|
"<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 "
|
"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 "
|
"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>[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 "
|
"<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 "
|
"(off = no noise measurements), and the Matter button. Holding the "
|
||||||
"Matter button <b>5 s</b> factory-resets the box (it forgets its Matter "
|
"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).",
|
"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. "
|
"<b>Inside the case</b> (unscrew): RESET and BOOT buttons and the SD card. "
|
||||||
"Normally not needed - the tool resets the board over USB.",
|
"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 "
|
"<b>Flashing</b> uses only the firmware files in the tool's <b>firmware</b> folder; choose the build "
|
||||||
"by its compile date.",
|
"by its compile date.",
|
||||||
]
|
]
|
||||||
|
|
||||||
STEPS = [
|
STEPS = [
|
||||||
"Switch the sensorbox <b>power switch ON</b>.",
|
"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.",
|
"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 "
|
"Open the <b>Serial monitor</b> tab, choose the sensorbox port, press "
|
||||||
"<b>Connect</b>.",
|
"<b>Connect</b>.",
|
||||||
"Press <b>Reset & capture</b> to record a full boot log from the first line.",
|
"Press <b>Reset & 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> "
|
"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.",
|
"and start <b>Quick check</b>: the tool asks what you see and checks the log live.",
|
||||||
]
|
]
|
||||||
|
|
||||||
|
|
||||||
def cheatsheet_html() -> str:
|
def cheatsheet_html() -> str:
|
||||||
rows = "".join(
|
rows = "".join(
|
||||||
f"<tr><td style='padding:6px'><span style='background:{c};"
|
f"<tr><td style='padding:6px'><span style='background:{c};"
|
||||||
f"border:1px solid #888'> </span> <b>{name}</b></td>"
|
f"border:1px solid #888'> </span> <b>{name}</b></td>"
|
||||||
f"<td style='padding:6px'>{meaning}</td><td style='padding:6px'>{action}</td></tr>"
|
f"<td style='padding:6px'>{meaning}</td><td style='padding:6px'>{action}</td></tr>"
|
||||||
for c, name, meaning, action in LED_TABLE
|
for c, name, meaning, action in LED_TABLE
|
||||||
)
|
)
|
||||||
steps = "".join(f"<li>{s}</li>" for s in STEPS)
|
steps = "".join(f"<li>{s}</li>" for s in STEPS)
|
||||||
hints = "".join(f"<li>{h}</li>" for h in HINTS)
|
hints = "".join(f"<li>{h}</li>" for h in HINTS)
|
||||||
return f"""
|
return f"""
|
||||||
<h2>Sensorbox quick start</h2>
|
<h2>Sensorbox quick start</h2>
|
||||||
<ol>{steps}</ol>
|
<ol>{steps}</ol>
|
||||||
<h3>RGB status LED - colour and pattern</h3>
|
<h3>RGB status LED - colour and pattern</h3>
|
||||||
<table border='1' cellspacing='0' cellpadding='0' width='100%'>
|
<table border='1' cellspacing='0' cellpadding='0' width='100%'>
|
||||||
<tr><th align='left' style='padding:6px'>LED</th>
|
<tr><th align='left' style='padding:6px'>LED</th>
|
||||||
<th align='left' style='padding:6px'>Pattern: meaning</th>
|
<th align='left' style='padding:6px'>Pattern: meaning</th>
|
||||||
<th align='left' style='padding:6px'>First action</th></tr>
|
<th align='left' style='padding:6px'>First action</th></tr>
|
||||||
{rows}
|
{rows}
|
||||||
</table>
|
</table>
|
||||||
<h3>Good to know</h3>
|
<h3>Good to know</h3>
|
||||||
<ul>{hints}</ul>
|
<ul>{hints}</ul>
|
||||||
"""
|
"""
|
||||||
+252
-252
@@ -1,252 +1,252 @@
|
|||||||
"""Diagnostics side panel: renders a diag.engine.Report.
|
"""Diagnostics side panel: renders a diag.engine.Report.
|
||||||
|
|
||||||
Layout: verdict banner, expected LED (colour + pattern + meaning when the
|
Layout: verdict banner, expected LED (colour + pattern + meaning when the
|
||||||
box reports it), firmware, the box's own self-report (KOTA lines), start-up
|
box reports it), firmware, the box's own self-report (KOTA lines), start-up
|
||||||
milestones, a findings tree (root causes; their consequences as children;
|
milestones, a findings tree (root causes; their consequences as children;
|
||||||
titles only) and a wrapped detail pane for the selected finding.
|
titles only) and a wrapped detail pane for the selected finding.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
from PySide6.QtCore import Qt
|
from PySide6.QtCore import Qt
|
||||||
from PySide6.QtGui import QBrush, QColor
|
from PySide6.QtGui import QBrush, QColor
|
||||||
from PySide6.QtWidgets import (
|
from PySide6.QtWidgets import (
|
||||||
QFrame,
|
QFrame,
|
||||||
QHBoxLayout,
|
QHBoxLayout,
|
||||||
QLabel,
|
QLabel,
|
||||||
QListWidget,
|
QListWidget,
|
||||||
QListWidgetItem,
|
QListWidgetItem,
|
||||||
QPushButton,
|
QPushButton,
|
||||||
QSizePolicy,
|
QSizePolicy,
|
||||||
QSplitter,
|
QSplitter,
|
||||||
QTextBrowser,
|
QTextBrowser,
|
||||||
QTreeWidget,
|
QTreeWidget,
|
||||||
QTreeWidgetItem,
|
QTreeWidgetItem,
|
||||||
QVBoxLayout,
|
QVBoxLayout,
|
||||||
QWidget,
|
QWidget,
|
||||||
)
|
)
|
||||||
|
|
||||||
from ..diag.engine import LED, Finding, Report, Severity
|
from ..diag.engine import LED, Finding, Report, Severity
|
||||||
|
|
||||||
SEV_COLOR = {
|
SEV_COLOR = {
|
||||||
Severity.CRITICAL: "#b03a2e",
|
Severity.CRITICAL: "#b03a2e",
|
||||||
Severity.ERROR: "#d9534f",
|
Severity.ERROR: "#d9534f",
|
||||||
Severity.WARNING: "#c77c02",
|
Severity.WARNING: "#c77c02",
|
||||||
Severity.INFO: "#2e6da4",
|
Severity.INFO: "#2e6da4",
|
||||||
}
|
}
|
||||||
# verdict banner (background, text) by verdict severity; None = healthy
|
# verdict banner (background, text) by verdict severity; None = healthy
|
||||||
BANNER = {
|
BANNER = {
|
||||||
Severity.CRITICAL: ("#f6d5d1", "#7b1e14"),
|
Severity.CRITICAL: ("#f6d5d1", "#7b1e14"),
|
||||||
Severity.ERROR: ("#f9dedc", "#8a2019"),
|
Severity.ERROR: ("#f9dedc", "#8a2019"),
|
||||||
Severity.WARNING: ("#fdebc8", "#6b4400"),
|
Severity.WARNING: ("#fdebc8", "#6b4400"),
|
||||||
None: ("#d8f0dd", "#1b5e2a"),
|
None: ("#d8f0dd", "#1b5e2a"),
|
||||||
}
|
}
|
||||||
_KEY = Qt.ItemDataRole.UserRole
|
_KEY = Qt.ItemDataRole.UserRole
|
||||||
BOX_STATE = {"ok": ("#1b7a33", "✔"), "warn": ("#c77c02", "!"), "bad": ("#b03a2e", "✖"), "info": ("#2e6da4", "i")}
|
BOX_STATE = {"ok": ("#1b7a33", "✔"), "warn": ("#c77c02", "!"), "bad": ("#b03a2e", "✖"), "info": ("#2e6da4", "i")}
|
||||||
|
|
||||||
|
|
||||||
def _heading(text: str) -> QLabel:
|
def _heading(text: str) -> QLabel:
|
||||||
lbl = QLabel(text)
|
lbl = QLabel(text)
|
||||||
f = lbl.font()
|
f = lbl.font()
|
||||||
f.setBold(True)
|
f.setBold(True)
|
||||||
lbl.setFont(f)
|
lbl.setFont(f)
|
||||||
return lbl
|
return lbl
|
||||||
|
|
||||||
|
|
||||||
def _esc(s: str) -> str:
|
def _esc(s: str) -> str:
|
||||||
return s.replace("&", "&").replace("<", "<").replace(">", ">")
|
return s.replace("&", "&").replace("<", "<").replace(">", ">")
|
||||||
|
|
||||||
|
|
||||||
class DiagnosticsPanel(QWidget):
|
class DiagnosticsPanel(QWidget):
|
||||||
def __init__(self, parent: QWidget | None = None):
|
def __init__(self, parent: QWidget | None = None):
|
||||||
super().__init__(parent)
|
super().__init__(parent)
|
||||||
self.setMinimumWidth(380)
|
self.setMinimumWidth(380)
|
||||||
|
|
||||||
self.verdict = QLabel(wordWrap=True)
|
self.verdict = QLabel(wordWrap=True)
|
||||||
self.verdict.setMargin(10)
|
self.verdict.setMargin(10)
|
||||||
vf = self.verdict.font()
|
vf = self.verdict.font()
|
||||||
vf.setPointSize(vf.pointSize() + 2)
|
vf.setPointSize(vf.pointSize() + 2)
|
||||||
vf.setBold(True)
|
vf.setBold(True)
|
||||||
self.verdict.setFont(vf)
|
self.verdict.setFont(vf)
|
||||||
|
|
||||||
self.led_swatch = QLabel()
|
self.led_swatch = QLabel()
|
||||||
self.led_swatch.setFixedSize(22, 22)
|
self.led_swatch.setFixedSize(22, 22)
|
||||||
self.led_text = QLabel(wordWrap=True)
|
self.led_text = QLabel(wordWrap=True)
|
||||||
led_row = QHBoxLayout()
|
led_row = QHBoxLayout()
|
||||||
led_row.addWidget(self.led_swatch, 0, Qt.AlignmentFlag.AlignTop)
|
led_row.addWidget(self.led_swatch, 0, Qt.AlignmentFlag.AlignTop)
|
||||||
led_row.addWidget(self.led_text, 1)
|
led_row.addWidget(self.led_text, 1)
|
||||||
|
|
||||||
self.firmware = QLabel(wordWrap=True)
|
self.firmware = QLabel(wordWrap=True)
|
||||||
self.firmware.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
|
self.firmware.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
|
||||||
|
|
||||||
self.box_title = _heading("Box self-report (KOTA lines)")
|
self.box_title = _heading("Box self-report (KOTA lines)")
|
||||||
self.box = QLabel(wordWrap=True)
|
self.box = QLabel(wordWrap=True)
|
||||||
self.box.setTextFormat(Qt.TextFormat.RichText)
|
self.box.setTextFormat(Qt.TextFormat.RichText)
|
||||||
self.box.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
|
self.box.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
|
||||||
|
|
||||||
self.milestones = QListWidget()
|
self.milestones = QListWidget()
|
||||||
self.milestones.setFrameShape(QFrame.Shape.NoFrame)
|
self.milestones.setFrameShape(QFrame.Shape.NoFrame)
|
||||||
self.milestones.setSelectionMode(QListWidget.SelectionMode.NoSelection)
|
self.milestones.setSelectionMode(QListWidget.SelectionMode.NoSelection)
|
||||||
self.milestones.setSizePolicy(QSizePolicy.Policy.Preferred, QSizePolicy.Policy.Maximum)
|
self.milestones.setSizePolicy(QSizePolicy.Policy.Preferred, QSizePolicy.Policy.Maximum)
|
||||||
|
|
||||||
self.tree = QTreeWidget()
|
self.tree = QTreeWidget()
|
||||||
self.tree.setHeaderHidden(True)
|
self.tree.setHeaderHidden(True)
|
||||||
self.tree.setIndentation(16)
|
self.tree.setIndentation(16)
|
||||||
self.tree.setTextElideMode(Qt.TextElideMode.ElideRight)
|
self.tree.setTextElideMode(Qt.TextElideMode.ElideRight)
|
||||||
self.detail = QTextBrowser()
|
self.detail = QTextBrowser()
|
||||||
self.detail.setOpenExternalLinks(False)
|
self.detail.setOpenExternalLinks(False)
|
||||||
findings = QSplitter(Qt.Orientation.Vertical)
|
findings = QSplitter(Qt.Orientation.Vertical)
|
||||||
findings.addWidget(self.tree)
|
findings.addWidget(self.tree)
|
||||||
findings.addWidget(self.detail)
|
findings.addWidget(self.detail)
|
||||||
findings.setSizes([220, 260])
|
findings.setSizes([220, 260])
|
||||||
|
|
||||||
lay = QVBoxLayout(self)
|
lay = QVBoxLayout(self)
|
||||||
lay.setContentsMargins(4, 0, 0, 0)
|
lay.setContentsMargins(4, 0, 0, 0)
|
||||||
lay.addWidget(self.verdict)
|
lay.addWidget(self.verdict)
|
||||||
lay.addWidget(_heading("Status LED should be"))
|
lay.addWidget(_heading("Status LED should be"))
|
||||||
lay.addLayout(led_row)
|
lay.addLayout(led_row)
|
||||||
lay.addWidget(_heading("Firmware"))
|
lay.addWidget(_heading("Firmware"))
|
||||||
lay.addWidget(self.firmware)
|
lay.addWidget(self.firmware)
|
||||||
self.qr_btn = QPushButton("Matter pairing QR code...")
|
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")
|
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.qr_btn, 0, Qt.AlignmentFlag.AlignLeft)
|
||||||
lay.addWidget(self.box_title)
|
lay.addWidget(self.box_title)
|
||||||
lay.addWidget(self.box)
|
lay.addWidget(self.box)
|
||||||
lay.addWidget(_heading("Start-up progress (current boot)"))
|
lay.addWidget(_heading("Start-up progress (current boot)"))
|
||||||
lay.addWidget(self.milestones)
|
lay.addWidget(self.milestones)
|
||||||
lay.addWidget(_heading("Findings - root causes first; click one for details"))
|
lay.addWidget(_heading("Findings - root causes first; click one for details"))
|
||||||
lay.addWidget(findings, 1)
|
lay.addWidget(findings, 1)
|
||||||
|
|
||||||
self._findings: dict[str, Finding] = {}
|
self._findings: dict[str, Finding] = {}
|
||||||
self._selected: str | None = None
|
self._selected: str | None = None
|
||||||
# key -> expanded, chosen by the user; survives the rebuild on refresh.
|
# key -> expanded, chosen by the user; survives the rebuild on refresh.
|
||||||
self._expanded: dict[str, bool] = {}
|
self._expanded: dict[str, bool] = {}
|
||||||
self.tree.currentItemChanged.connect(self._on_select)
|
self.tree.currentItemChanged.connect(self._on_select)
|
||||||
self.tree.itemCollapsed.connect(lambda it: self._remember(it, False))
|
self.tree.itemCollapsed.connect(lambda it: self._remember(it, False))
|
||||||
self.tree.itemExpanded.connect(lambda it: self._remember(it, True))
|
self.tree.itemExpanded.connect(lambda it: self._remember(it, True))
|
||||||
|
|
||||||
# ------------------------------------------------------------------
|
# ------------------------------------------------------------------
|
||||||
def show_report(self, r: Report) -> None:
|
def show_report(self, r: Report) -> None:
|
||||||
bg, fg = BANNER.get(r.verdict_severity, BANNER[Severity.WARNING])
|
bg, fg = BANNER.get(r.verdict_severity, BANNER[Severity.WARNING])
|
||||||
if r.lines == 0:
|
if r.lines == 0:
|
||||||
bg, fg = "#e6e6e6", "#333333"
|
bg, fg = "#e6e6e6", "#333333"
|
||||||
self.verdict.setText(r.verdict)
|
self.verdict.setText(r.verdict)
|
||||||
self.verdict.setStyleSheet(f"QLabel {{ background:{bg}; color:{fg}; border-radius:6px; }}")
|
self.verdict.setStyleSheet(f"QLabel {{ background:{bg}; color:{fg}; border-radius:6px; }}")
|
||||||
|
|
||||||
name, colour = LED[r.led]
|
name, colour = LED[r.led]
|
||||||
self.led_swatch.setStyleSheet(
|
self.led_swatch.setStyleSheet(
|
||||||
f"QLabel {{ background:{colour}; border:1px solid #777; border-radius:11px; }}")
|
f"QLabel {{ background:{colour}; border:1px solid #777; border-radius:11px; }}")
|
||||||
ask = "" if r.led == "UNKNOWN" else " - <i>check it matches the box</i>"
|
ask = "" if r.led == "UNKNOWN" else " - <i>check it matches the box</i>"
|
||||||
pattern = f", {_esc(r.led_pattern)}" if r.led_pattern else ""
|
pattern = f", {_esc(r.led_pattern)}" if r.led_pattern else ""
|
||||||
meaning = f" = {_esc(r.led_meaning)}" if r.led_meaning 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 ""
|
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 ""
|
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}")
|
self.led_text.setText(f"<b>{name}{pattern}</b>{meaning}{source}{ask}{reason}")
|
||||||
|
|
||||||
fw = r.firmware
|
fw = r.firmware
|
||||||
sd = {True: "reads Wi-Fi settings from the SD card",
|
sd = {True: "reads Wi-Fi settings from the SD card",
|
||||||
False: "does not read 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"}
|
None: "Wi-Fi-from-SD support unknown"}
|
||||||
self.firmware.setText(f"{_esc(fw.describe())}<br><small>{sd[fw.supports_sd_wifi]}</small>")
|
self.firmware.setText(f"{_esc(fw.describe())}<br><small>{sd[fw.supports_sd_wifi]}</small>")
|
||||||
|
|
||||||
self.box_title.setVisible(bool(r.box))
|
self.box_title.setVisible(bool(r.box))
|
||||||
self.box.setVisible(bool(r.box))
|
self.box.setVisible(bool(r.box))
|
||||||
self.box.setText("<table cellspacing='0' cellpadding='1'>" + "".join(
|
self.box.setText("<table cellspacing='0' cellpadding='1'>" + "".join(
|
||||||
f"<tr><td style='color:{BOX_STATE[st][0]}'><b>{BOX_STATE[st][1]}</b> </td>"
|
f"<tr><td style='color:{BOX_STATE[st][0]}'><b>{BOX_STATE[st][1]}</b> </td>"
|
||||||
f"<td><b>{_esc(topic)}</b> </td><td>{_esc(text)}</td></tr>"
|
f"<td><b>{_esc(topic)}</b> </td><td>{_esc(text)}</td></tr>"
|
||||||
for topic, text, st in r.box) + "</table>")
|
for topic, text, st in r.box) + "</table>")
|
||||||
|
|
||||||
self.milestones.clear()
|
self.milestones.clear()
|
||||||
for _, label, t in r.milestones:
|
for _, label, t in r.milestones:
|
||||||
done = t is not None
|
done = t is not None
|
||||||
it = QListWidgetItem(("✔ " if done else "○ ") + label
|
it = QListWidgetItem(("✔ " if done else "○ ") + label
|
||||||
+ (f" ({t / 1000:.1f} s)" if done else ""))
|
+ (f" ({t / 1000:.1f} s)" if done else ""))
|
||||||
it.setForeground(QBrush(QColor("#1b7a33" if done else "#8a8a8a")))
|
it.setForeground(QBrush(QColor("#1b7a33" if done else "#8a8a8a")))
|
||||||
self.milestones.addItem(it)
|
self.milestones.addItem(it)
|
||||||
rows = min(max(self.milestones.count(), 1), 15)
|
rows = min(max(self.milestones.count(), 1), 15)
|
||||||
self.milestones.setFixedHeight(rows * max(self.milestones.sizeHintForRow(0), 16) + 6)
|
self.milestones.setFixedHeight(rows * max(self.milestones.sizeHintForRow(0), 16) + 6)
|
||||||
|
|
||||||
self._fill_tree(r)
|
self._fill_tree(r)
|
||||||
|
|
||||||
def _fill_tree(self, r: Report) -> None:
|
def _fill_tree(self, r: Report) -> None:
|
||||||
self.tree.blockSignals(True)
|
self.tree.blockSignals(True)
|
||||||
self.tree.clear()
|
self.tree.clear()
|
||||||
self._findings = {}
|
self._findings = {}
|
||||||
if not r.roots:
|
if not r.roots:
|
||||||
it = QTreeWidgetItem(["No problems detected in the log so far."])
|
it = QTreeWidgetItem(["No problems detected in the log so far."])
|
||||||
it.setForeground(0, QBrush(QColor("#1b7a33")))
|
it.setForeground(0, QBrush(QColor("#1b7a33")))
|
||||||
self.tree.addTopLevelItem(it)
|
self.tree.addTopLevelItem(it)
|
||||||
for rc in r.roots:
|
for rc in r.roots:
|
||||||
top = self._item(rc.finding, bold=True)
|
top = self._item(rc.finding, bold=True)
|
||||||
self.tree.addTopLevelItem(top)
|
self.tree.addTopLevelItem(top)
|
||||||
for c in rc.consequences:
|
for c in rc.consequences:
|
||||||
top.addChild(self._item(c, prefix="↳ "))
|
top.addChild(self._item(c, prefix="↳ "))
|
||||||
top.setExpanded(self._expanded.get(rc.finding.key, True))
|
top.setExpanded(self._expanded.get(rc.finding.key, True))
|
||||||
for title, key, items in (("Seen in earlier boots only", "grp:earlier", r.earlier),
|
for title, key, items in (("Seen in earlier boots only", "grp:earlier", r.earlier),
|
||||||
("Resolved during this session", "grp:resolved", r.resolved)):
|
("Resolved during this session", "grp:resolved", r.resolved)):
|
||||||
if not items:
|
if not items:
|
||||||
continue
|
continue
|
||||||
grp = QTreeWidgetItem([f"{title} ({len(items)})"])
|
grp = QTreeWidgetItem([f"{title} ({len(items)})"])
|
||||||
grp.setData(0, _KEY, key)
|
grp.setData(0, _KEY, key)
|
||||||
grp.setForeground(0, QBrush(QColor("#666666")))
|
grp.setForeground(0, QBrush(QColor("#666666")))
|
||||||
self.tree.addTopLevelItem(grp)
|
self.tree.addTopLevelItem(grp)
|
||||||
for f in items:
|
for f in items:
|
||||||
grp.addChild(self._item(f, prefix="✔ " if key == "grp:resolved" else ""))
|
grp.addChild(self._item(f, prefix="✔ " if key == "grp:resolved" else ""))
|
||||||
grp.setExpanded(self._expanded.get(key, False))
|
grp.setExpanded(self._expanded.get(key, False))
|
||||||
# Keep the selection across refreshes; default to the top root cause.
|
# Keep the selection across refreshes; default to the top root cause.
|
||||||
target = self._selected if self._selected in self._findings else (
|
target = self._selected if self._selected in self._findings else (
|
||||||
r.roots[0].finding.key if r.roots else None)
|
r.roots[0].finding.key if r.roots else None)
|
||||||
self.tree.blockSignals(False)
|
self.tree.blockSignals(False)
|
||||||
self._select(target)
|
self._select(target)
|
||||||
|
|
||||||
def _remember(self, item: QTreeWidgetItem, expanded: bool) -> None:
|
def _remember(self, item: QTreeWidgetItem, expanded: bool) -> None:
|
||||||
if key := item.data(0, _KEY):
|
if key := item.data(0, _KEY):
|
||||||
self._expanded[key] = expanded
|
self._expanded[key] = expanded
|
||||||
|
|
||||||
def _item(self, f: Finding, prefix: str = "", bold: bool = False) -> QTreeWidgetItem:
|
def _item(self, f: Finding, prefix: str = "", bold: bool = False) -> QTreeWidgetItem:
|
||||||
it = QTreeWidgetItem([f"{prefix}[{f.severity.label}] {f.title}"])
|
it = QTreeWidgetItem([f"{prefix}[{f.severity.label}] {f.title}"])
|
||||||
it.setData(0, _KEY, f.key)
|
it.setData(0, _KEY, f.key)
|
||||||
it.setForeground(0, QBrush(QColor(SEV_COLOR.get(f.severity, "#333333"))))
|
it.setForeground(0, QBrush(QColor(SEV_COLOR.get(f.severity, "#333333"))))
|
||||||
it.setToolTip(0, f.title)
|
it.setToolTip(0, f.title)
|
||||||
if bold:
|
if bold:
|
||||||
font = it.font(0)
|
font = it.font(0)
|
||||||
font.setBold(True)
|
font.setBold(True)
|
||||||
it.setFont(0, font)
|
it.setFont(0, font)
|
||||||
self._findings[f.key] = f
|
self._findings[f.key] = f
|
||||||
return it
|
return it
|
||||||
|
|
||||||
def _select(self, key: str | None) -> None:
|
def _select(self, key: str | None) -> None:
|
||||||
if key is None:
|
if key is None:
|
||||||
self.detail.setHtml("<p style='color:#666'>Nothing to show yet.</p>")
|
self.detail.setHtml("<p style='color:#666'>Nothing to show yet.</p>")
|
||||||
return
|
return
|
||||||
match = self.tree.findItems("*", Qt.MatchFlag.MatchWildcard | Qt.MatchFlag.MatchRecursive)
|
match = self.tree.findItems("*", Qt.MatchFlag.MatchWildcard | Qt.MatchFlag.MatchRecursive)
|
||||||
for it in match:
|
for it in match:
|
||||||
if it.data(0, _KEY) == key:
|
if it.data(0, _KEY) == key:
|
||||||
self.tree.setCurrentItem(it)
|
self.tree.setCurrentItem(it)
|
||||||
return
|
return
|
||||||
|
|
||||||
def _on_select(self, cur: QTreeWidgetItem | None, _prev) -> None:
|
def _on_select(self, cur: QTreeWidgetItem | None, _prev) -> None:
|
||||||
key = cur.data(0, _KEY) if cur else None
|
key = cur.data(0, _KEY) if cur else None
|
||||||
f = self._findings.get(key or "")
|
f = self._findings.get(key or "")
|
||||||
if f is None:
|
if f is None:
|
||||||
return
|
return
|
||||||
self._selected = key
|
self._selected = key
|
||||||
self.detail.setHtml(_detail_html(f))
|
self.detail.setHtml(_detail_html(f))
|
||||||
|
|
||||||
|
|
||||||
def _detail_html(f: Finding) -> str:
|
def _detail_html(f: Finding) -> str:
|
||||||
colour = SEV_COLOR.get(f.severity, "#333")
|
colour = SEV_COLOR.get(f.severity, "#333")
|
||||||
actions = "".join(f"<li>{_esc(a)}</li>" for a in f.actions)
|
actions = "".join(f"<li>{_esc(a)}</li>" for a in f.actions)
|
||||||
seen = _esc(f.seen_text())
|
seen = _esc(f.seen_text())
|
||||||
evidence = "<br>".join(_esc(e) for e in f.evidence)
|
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>"
|
codes = "".join(f"<li><b>{_esc(eid)}</b>" + (f" - {_esc(a)}" if a else "") + "</li>"
|
||||||
for eid, a in f.error_ids.items())
|
for eid, a in f.error_ids.items())
|
||||||
return (
|
return (
|
||||||
f"<h3 style='color:{colour}; margin:0'>{_esc(f.title)}</h3>"
|
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 it means:</b> {_esc(f.meaning)}</p>"
|
||||||
+ (f"<p><b>What to do:</b></p><ol>{actions}</ol>" if actions else "")
|
+ (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><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:#666'>{seen}</p>"
|
||||||
+ (f"<p style='color:#555; font-family:Consolas,Menlo,monospace; font-size:9pt'>{evidence}</p>"
|
+ (f"<p style='color:#555; font-family:Consolas,Menlo,monospace; font-size:9pt'>{evidence}</p>"
|
||||||
if evidence else "")
|
if evidence else "")
|
||||||
)
|
)
|
||||||
+364
-364
@@ -1,364 +1,364 @@
|
|||||||
"""Flash firmware tab: only the .bin files in the tool's firmware/ folder,
|
"""Flash firmware tab: only the .bin files in the tool's firmware/ folder,
|
||||||
chosen by their compile date; App-only by default."""
|
chosen by their compile date; App-only by default."""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
import datetime as dt
|
import datetime as dt
|
||||||
import tempfile
|
import tempfile
|
||||||
from pathlib import Path
|
from pathlib import Path
|
||||||
|
|
||||||
from PySide6.QtCore import QObject, Qt, QTimer, QUrl, Signal
|
from PySide6.QtCore import QObject, Qt, QTimer, QUrl, Signal
|
||||||
from PySide6.QtGui import QDesktopServices
|
from PySide6.QtGui import QDesktopServices
|
||||||
from PySide6.QtWidgets import (
|
from PySide6.QtWidgets import (
|
||||||
QButtonGroup,
|
QButtonGroup,
|
||||||
QCheckBox,
|
QCheckBox,
|
||||||
QComboBox,
|
QComboBox,
|
||||||
QGroupBox,
|
QGroupBox,
|
||||||
QHBoxLayout,
|
QHBoxLayout,
|
||||||
QLabel,
|
QLabel,
|
||||||
QMessageBox,
|
QMessageBox,
|
||||||
QPlainTextEdit,
|
QPlainTextEdit,
|
||||||
QProgressBar,
|
QProgressBar,
|
||||||
QPushButton,
|
QPushButton,
|
||||||
QRadioButton,
|
QRadioButton,
|
||||||
QVBoxLayout,
|
QVBoxLayout,
|
||||||
QWidget,
|
QWidget,
|
||||||
)
|
)
|
||||||
|
|
||||||
from ..core.session import SESSIONS_DIR
|
from ..core.session import SESSIONS_DIR
|
||||||
from ..diag.firmware import local_build, register_local_build, same_build
|
from ..diag.firmware import local_build, register_local_build, same_build
|
||||||
from ..flash.image import FIRMWARE_DIR, FirmwareImage, folder_images
|
from ..flash.image import FIRMWARE_DIR, FirmwareImage, folder_images
|
||||||
from ..flash.plan import Mode, build_plan
|
from ..flash.plan import Mode, build_plan
|
||||||
from ..flash.runner import FlashRunner, Result
|
from ..flash.runner import FlashRunner, Result
|
||||||
from ..serialio.ports import PortInfo, list_serial_ports
|
from ..serialio.ports import PortInfo, list_serial_ports
|
||||||
|
|
||||||
BACKUP_DIR = SESSIONS_DIR.parent / "backups"
|
BACKUP_DIR = SESSIONS_DIR.parent / "backups"
|
||||||
VERIFY_TIMEOUT_MS = 45_000
|
VERIFY_TIMEOUT_MS = 45_000
|
||||||
|
|
||||||
HELP = (
|
HELP = (
|
||||||
"<b>If flashing cannot connect:</b> use a data-capable USB cable directly on the laptop, close "
|
"<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>, "
|
"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."
|
"press and release <b>RESET</b>, release <b>BOOT</b>, and press Start again."
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|
||||||
class _Bridge(QObject):
|
class _Bridge(QObject):
|
||||||
step = Signal(int, str)
|
step = Signal(int, str)
|
||||||
progress = Signal(int)
|
progress = Signal(int)
|
||||||
output = Signal(str)
|
output = Signal(str)
|
||||||
done = Signal(object)
|
done = Signal(object)
|
||||||
|
|
||||||
|
|
||||||
class FlashTab(QWidget):
|
class FlashTab(QWidget):
|
||||||
def __init__(self, serial_tab, parent: QWidget | None = None):
|
def __init__(self, serial_tab, parent: QWidget | None = None):
|
||||||
super().__init__(parent)
|
super().__init__(parent)
|
||||||
self.serial_tab = serial_tab
|
self.serial_tab = serial_tab
|
||||||
self._images: list[FirmwareImage] = []
|
self._images: list[FirmwareImage] = []
|
||||||
self._ports: list[PortInfo] = [] # before any signal can call _update()
|
self._ports: list[PortInfo] = [] # before any signal can call _update()
|
||||||
self._runner: FlashRunner | None = None
|
self._runner: FlashRunner | None = None
|
||||||
self._port: PortInfo | None = None
|
self._port: PortInfo | None = None
|
||||||
self._image: FirmwareImage | None = None
|
self._image: FirmwareImage | None = None
|
||||||
|
|
||||||
# 1. box
|
# 1. box
|
||||||
box = QGroupBox("1. Sensorbox")
|
box = QGroupBox("1. Sensorbox")
|
||||||
self.port_combo = QComboBox(minimumWidth=360)
|
self.port_combo = QComboBox(minimumWidth=360)
|
||||||
refresh = QPushButton("Refresh")
|
refresh = QPushButton("Refresh")
|
||||||
refresh.clicked.connect(self.refresh_ports)
|
refresh.clicked.connect(self.refresh_ports)
|
||||||
self.box_fw = QLabel(wordWrap=True)
|
self.box_fw = QLabel(wordWrap=True)
|
||||||
bl = QVBoxLayout(box)
|
bl = QVBoxLayout(box)
|
||||||
row = QHBoxLayout()
|
row = QHBoxLayout()
|
||||||
row.addWidget(self.port_combo)
|
row.addWidget(self.port_combo)
|
||||||
row.addWidget(refresh)
|
row.addWidget(refresh)
|
||||||
row.addStretch(1)
|
row.addStretch(1)
|
||||||
bl.addLayout(row)
|
bl.addLayout(row)
|
||||||
bl.addWidget(self.box_fw)
|
bl.addWidget(self.box_fw)
|
||||||
|
|
||||||
# 2. firmware - only files in the tool's firmware/ folder
|
# 2. firmware - only files in the tool's firmware/ folder
|
||||||
fwbox = QGroupBox("2. Firmware (by compile date)")
|
fwbox = QGroupBox("2. Firmware (by compile date)")
|
||||||
self.image_combo = QComboBox(minimumWidth=360)
|
self.image_combo = QComboBox(minimumWidth=360)
|
||||||
self.image_combo.setToolTip(f"Firmware files in {FIRMWARE_DIR}")
|
self.image_combo.setToolTip(f"Firmware files in {FIRMWARE_DIR}")
|
||||||
self.reload_btn = QPushButton("Refresh list")
|
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.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.reload_btn.clicked.connect(lambda: self._load_images(self._selected_sha()))
|
||||||
self.folder_btn = QPushButton("Open firmware folder")
|
self.folder_btn = QPushButton("Open firmware folder")
|
||||||
self.folder_btn.clicked.connect(
|
self.folder_btn.clicked.connect(
|
||||||
lambda: QDesktopServices.openUrl(QUrl.fromLocalFile(str(FIRMWARE_DIR))))
|
lambda: QDesktopServices.openUrl(QUrl.fromLocalFile(str(FIRMWARE_DIR))))
|
||||||
self.image_info = QLabel(wordWrap=True)
|
self.image_info = QLabel(wordWrap=True)
|
||||||
self.image_info.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
|
self.image_info.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
|
||||||
fl = QVBoxLayout(fwbox)
|
fl = QVBoxLayout(fwbox)
|
||||||
fl.addWidget(self.image_combo)
|
fl.addWidget(self.image_combo)
|
||||||
brow = QHBoxLayout()
|
brow = QHBoxLayout()
|
||||||
brow.addWidget(self.reload_btn)
|
brow.addWidget(self.reload_btn)
|
||||||
brow.addWidget(self.folder_btn)
|
brow.addWidget(self.folder_btn)
|
||||||
brow.addStretch(1)
|
brow.addStretch(1)
|
||||||
fl.addLayout(brow)
|
fl.addLayout(brow)
|
||||||
fl.addWidget(self.image_info)
|
fl.addWidget(self.image_info)
|
||||||
self._problems: list[str] = []
|
self._problems: list[str] = []
|
||||||
|
|
||||||
# 3. mode
|
# 3. mode
|
||||||
modebox = QGroupBox("3. What to write")
|
modebox = QGroupBox("3. What to write")
|
||||||
self.rb_app = QRadioButton("App only (recommended for repairs)")
|
self.rb_app = QRadioButton("App only (recommended for repairs)")
|
||||||
self.rb_full = QRadioButton("Full image (new or completely wiped boards)")
|
self.rb_full = QRadioButton("Full image (new or completely wiped boards)")
|
||||||
self.mode_group = QButtonGroup(self)
|
self.mode_group = QButtonGroup(self)
|
||||||
self.mode_group.addButton(self.rb_app)
|
self.mode_group.addButton(self.rb_app)
|
||||||
self.mode_group.addButton(self.rb_full)
|
self.mode_group.addButton(self.rb_full)
|
||||||
self.rb_app.setChecked(True)
|
self.rb_app.setChecked(True)
|
||||||
app_note = QLabel("Replaces the firmware only. Keeps the Matter pairing, the OTA registration and the "
|
app_note = QLabel("Replaces the firmware only. Keeps the Matter pairing, the OTA registration and the "
|
||||||
"settings stored on the box.", wordWrap=True)
|
"settings stored on the box.", wordWrap=True)
|
||||||
full_note = QLabel("Writes everything like the factory. <b>Erases the Matter pairing and the OTA "
|
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)
|
"registration</b> - the box must be paired again afterwards.", wordWrap=True)
|
||||||
for n in (app_note, full_note):
|
for n in (app_note, full_note):
|
||||||
n.setContentsMargins(24, 0, 0, 6)
|
n.setContentsMargins(24, 0, 0, 6)
|
||||||
n.setStyleSheet("color:#555")
|
n.setStyleSheet("color:#555")
|
||||||
self.confirm_full = QCheckBox("I understand the pairing and OTA registration will be erased")
|
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)")
|
self.backup = QCheckBox("Back up the box's complete flash first (8 MB, about 3 minutes)")
|
||||||
ml = QVBoxLayout(modebox)
|
ml = QVBoxLayout(modebox)
|
||||||
for w in (self.rb_app, app_note, self.rb_full, full_note, self.confirm_full, self.backup):
|
for w in (self.rb_app, app_note, self.rb_full, full_note, self.confirm_full, self.backup):
|
||||||
ml.addWidget(w)
|
ml.addWidget(w)
|
||||||
|
|
||||||
# 4. run
|
# 4. run
|
||||||
runbox = QGroupBox("4. Flash")
|
runbox = QGroupBox("4. Flash")
|
||||||
self.plan_label = QLabel(wordWrap=True)
|
self.plan_label = QLabel(wordWrap=True)
|
||||||
self.start_btn = QPushButton("Start flashing")
|
self.start_btn = QPushButton("Start flashing")
|
||||||
self.start_btn.setMinimumHeight(36)
|
self.start_btn.setMinimumHeight(36)
|
||||||
self.start_btn.clicked.connect(self._start)
|
self.start_btn.clicked.connect(self._start)
|
||||||
self.step_label = QLabel()
|
self.step_label = QLabel()
|
||||||
self.bar = QProgressBar()
|
self.bar = QProgressBar()
|
||||||
self.result = QLabel(wordWrap=True)
|
self.result = QLabel(wordWrap=True)
|
||||||
self.result.setMargin(8)
|
self.result.setMargin(8)
|
||||||
self.result.setTextFormat(Qt.TextFormat.RichText)
|
self.result.setTextFormat(Qt.TextFormat.RichText)
|
||||||
self.details_btn = QPushButton("Show esptool output")
|
self.details_btn = QPushButton("Show esptool output")
|
||||||
self.details_btn.setCheckable(True)
|
self.details_btn.setCheckable(True)
|
||||||
self.output = QPlainTextEdit(readOnly=True)
|
self.output = QPlainTextEdit(readOnly=True)
|
||||||
self.output.setVisible(False)
|
self.output.setVisible(False)
|
||||||
self.details_btn.toggled.connect(self.output.setVisible)
|
self.details_btn.toggled.connect(self.output.setVisible)
|
||||||
rl = QVBoxLayout(runbox)
|
rl = QVBoxLayout(runbox)
|
||||||
for w in (self.plan_label, self.start_btn, self.step_label, self.bar, self.result, self.details_btn, self.output):
|
for w in (self.plan_label, self.start_btn, self.step_label, self.bar, self.result, self.details_btn, self.output):
|
||||||
rl.addWidget(w)
|
rl.addWidget(w)
|
||||||
help_lbl = QLabel(HELP, wordWrap=True)
|
help_lbl = QLabel(HELP, wordWrap=True)
|
||||||
help_lbl.setStyleSheet("color:#555")
|
help_lbl.setStyleSheet("color:#555")
|
||||||
rl.addWidget(help_lbl)
|
rl.addWidget(help_lbl)
|
||||||
rl.addStretch(1) # keep the run column packed at the top
|
rl.addStretch(1) # keep the run column packed at the top
|
||||||
|
|
||||||
left = QVBoxLayout()
|
left = QVBoxLayout()
|
||||||
for w in (box, fwbox, modebox):
|
for w in (box, fwbox, modebox):
|
||||||
left.addWidget(w)
|
left.addWidget(w)
|
||||||
left.addStretch(1)
|
left.addStretch(1)
|
||||||
lay = QHBoxLayout(self)
|
lay = QHBoxLayout(self)
|
||||||
lay.addLayout(left, 1)
|
lay.addLayout(left, 1)
|
||||||
lay.addWidget(runbox, 1)
|
lay.addWidget(runbox, 1)
|
||||||
|
|
||||||
self._bridge = _Bridge()
|
self._bridge = _Bridge()
|
||||||
self._bridge.step.connect(self._on_step)
|
self._bridge.step.connect(self._on_step)
|
||||||
self._bridge.progress.connect(self.bar.setValue)
|
self._bridge.progress.connect(self.bar.setValue)
|
||||||
self._bridge.output.connect(self.output.appendPlainText)
|
self._bridge.output.connect(self.output.appendPlainText)
|
||||||
self._bridge.done.connect(self._on_done)
|
self._bridge.done.connect(self._on_done)
|
||||||
self._verify_timer = QTimer(self, interval=500)
|
self._verify_timer = QTimer(self, interval=500)
|
||||||
self._verify_timer.timeout.connect(self._check_verify)
|
self._verify_timer.timeout.connect(self._check_verify)
|
||||||
|
|
||||||
for sig in (self.rb_app.toggled, self.confirm_full.toggled, self.backup.toggled):
|
for sig in (self.rb_app.toggled, self.confirm_full.toggled, self.backup.toggled):
|
||||||
sig.connect(self._update)
|
sig.connect(self._update)
|
||||||
self.rb_full.toggled.connect(lambda on: self.backup.setChecked(on)) # backup default on for Full
|
self.rb_full.toggled.connect(lambda on: self.backup.setChecked(on)) # backup default on for Full
|
||||||
self.image_combo.currentIndexChanged.connect(self._update)
|
self.image_combo.currentIndexChanged.connect(self._update)
|
||||||
self.port_combo.currentIndexChanged.connect(self._update)
|
self.port_combo.currentIndexChanged.connect(self._update)
|
||||||
|
|
||||||
self._load_images()
|
self._load_images()
|
||||||
self.refresh_ports()
|
self.refresh_ports()
|
||||||
self._show_result("", None)
|
self._show_result("", None)
|
||||||
|
|
||||||
# ------------------------------------------------------------ setup
|
# ------------------------------------------------------------ setup
|
||||||
def _load_images(self, select_sha: str | None = None) -> None:
|
def _load_images(self, select_sha: str | None = None) -> None:
|
||||||
self._images, self._problems = folder_images()
|
self._images, self._problems = folder_images()
|
||||||
for img in self._images: # lets the Serial monitor show a box build's compile date
|
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)
|
register_local_build(img.app.elf_sha, img.app.version, img.app.built, img.name)
|
||||||
self.image_combo.blockSignals(True)
|
self.image_combo.blockSignals(True)
|
||||||
self.image_combo.clear()
|
self.image_combo.clear()
|
||||||
for img in self._images:
|
for img in self._images:
|
||||||
self.image_combo.addItem(img.label())
|
self.image_combo.addItem(img.label())
|
||||||
if not self._images:
|
if not self._images:
|
||||||
self.image_combo.addItem("No firmware file in the firmware folder")
|
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)
|
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.setCurrentIndex(idx) # default: newest compile date
|
||||||
self.image_combo.blockSignals(False)
|
self.image_combo.blockSignals(False)
|
||||||
self._update()
|
self._update()
|
||||||
|
|
||||||
def _selected_sha(self) -> str | None:
|
def _selected_sha(self) -> str | None:
|
||||||
img = self._selected_image()
|
img = self._selected_image()
|
||||||
return img.sha256 if img else None
|
return img.sha256 if img else None
|
||||||
|
|
||||||
def refresh_ports(self) -> None:
|
def refresh_ports(self) -> None:
|
||||||
current = self.port_combo.currentData()
|
current = self.port_combo.currentData()
|
||||||
self._ports = list_serial_ports()
|
self._ports = list_serial_ports()
|
||||||
self.port_combo.clear()
|
self.port_combo.clear()
|
||||||
for p in self._ports:
|
for p in self._ports:
|
||||||
self.port_combo.addItem(p.label, p.device)
|
self.port_combo.addItem(p.label, p.device)
|
||||||
if not self._ports:
|
if not self._ports:
|
||||||
self.port_combo.addItem("No sensorbox found - check USB cable and power switch", None)
|
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.port_combo.setCurrentIndex(max(self.port_combo.findData(current), 0))
|
||||||
self._update()
|
self._update()
|
||||||
|
|
||||||
def showEvent(self, event): # noqa: N802 - refresh when the tab is opened
|
def showEvent(self, event): # noqa: N802 - refresh when the tab is opened
|
||||||
self.refresh_ports()
|
self.refresh_ports()
|
||||||
super().showEvent(event)
|
super().showEvent(event)
|
||||||
|
|
||||||
# ------------------------------------------------------------ state
|
# ------------------------------------------------------------ state
|
||||||
def _selected_image(self) -> FirmwareImage | None:
|
def _selected_image(self) -> FirmwareImage | None:
|
||||||
i = self.image_combo.currentIndex()
|
i = self.image_combo.currentIndex()
|
||||||
return self._images[i] if 0 <= i < len(self._images) else None
|
return self._images[i] if 0 <= i < len(self._images) else None
|
||||||
|
|
||||||
def _selected_port(self) -> PortInfo | None:
|
def _selected_port(self) -> PortInfo | None:
|
||||||
dev = self.port_combo.currentData()
|
dev = self.port_combo.currentData()
|
||||||
return next((p for p in self._ports if p.device == dev), None)
|
return next((p for p in self._ports if p.device == dev), None)
|
||||||
|
|
||||||
def _update(self) -> None:
|
def _update(self) -> None:
|
||||||
img = self._selected_image()
|
img = self._selected_image()
|
||||||
info = ""
|
info = ""
|
||||||
if img:
|
if img:
|
||||||
a = img.app
|
a = img.app
|
||||||
kind = "complete image (bootloader + layout + app)" if img.kind == "merged" else "app only"
|
kind = "complete image (bootloader + layout + app)" if img.kind == "merged" else "app only"
|
||||||
info = (f"<b>Compiled {a.built}</b> · {a.project} v{a.version}, ESP-IDF {a.idf}, {kind}<br>"
|
info = (f"<b>Compiled {a.built}</b> · {a.project} v{a.version}, ESP-IDF {a.idf}, {kind}<br>"
|
||||||
f"<small>file firmware/{img.name} · build {a.elf_sha[:8]} · "
|
f"<small>file firmware/{img.name} · build {a.elf_sha[:8]} · "
|
||||||
f"SHA-256 {img.sha256[:16]}... · checksum OK</small>")
|
f"SHA-256 {img.sha256[:16]}... · checksum OK</small>")
|
||||||
else:
|
else:
|
||||||
info = (f"Put the firmware .bin file from the firmware team into<br><code>{FIRMWARE_DIR}</code><br>"
|
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.")
|
"and press <b>Refresh list</b>. Only files in this folder can be flashed.")
|
||||||
if self._problems:
|
if self._problems:
|
||||||
info += ("<br><span style='color:#b03a2e'><b>Not offered:</b> "
|
info += ("<br><span style='color:#b03a2e'><b>Not offered:</b> "
|
||||||
+ "; ".join(self._problems) + "</span>")
|
+ "; ".join(self._problems) + "</span>")
|
||||||
self.image_info.setText(info)
|
self.image_info.setText(info)
|
||||||
# An app-only file has no bootloader/layout: Full mode is impossible.
|
# An app-only file has no bootloader/layout: Full mode is impossible.
|
||||||
full_ok = bool(img and img.kind == "merged")
|
full_ok = bool(img and img.kind == "merged")
|
||||||
self.rb_full.setEnabled(full_ok and self._runner is None)
|
self.rb_full.setEnabled(full_ok and self._runner is None)
|
||||||
if not full_ok and self.rb_full.isChecked():
|
if not full_ok and self.rb_full.isChecked():
|
||||||
self.rb_app.setChecked(True)
|
self.rb_app.setChecked(True)
|
||||||
self.box_fw.setText(self._box_text(img))
|
self.box_fw.setText(self._box_text(img))
|
||||||
|
|
||||||
self.confirm_full.setVisible(self.rb_full.isChecked())
|
self.confirm_full.setVisible(self.rb_full.isChecked())
|
||||||
ok = bool(img and self._selected_port() and self._runner is None
|
ok = bool(img and self._selected_port() and self._runner is None
|
||||||
and (self.rb_app.isChecked() or self.confirm_full.isChecked()))
|
and (self.rb_app.isChecked() or self.confirm_full.isChecked()))
|
||||||
self.start_btn.setEnabled(ok)
|
self.start_btn.setEnabled(ok)
|
||||||
if img and self._selected_port():
|
if img and self._selected_port():
|
||||||
mode = Mode.APP_ONLY if self.rb_app.isChecked() else Mode.FULL
|
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 []
|
steps = ["Back up the complete flash (~3 min)"] if self.backup.isChecked() else []
|
||||||
if mode == Mode.APP_ONLY:
|
if mode == Mode.APP_ONLY:
|
||||||
steps += ["Check the box has the same partition layout", "Write the firmware app (~20 s)"]
|
steps += ["Check the box has the same partition layout", "Write the firmware app (~20 s)"]
|
||||||
else:
|
else:
|
||||||
steps += ["Write the complete image (~25 s)"]
|
steps += ["Write the complete image (~25 s)"]
|
||||||
steps += ["Restart the box and verify the new firmware boots"]
|
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>")
|
self.plan_label.setText("<b>Plan:</b><ol>" + "".join(f"<li>{s}</li>" for s in steps) + "</ol>")
|
||||||
else:
|
else:
|
||||||
self.plan_label.setText("Select a sensorbox and a firmware image.")
|
self.plan_label.setText("Select a sensorbox and a firmware image.")
|
||||||
|
|
||||||
def _box_text(self, img: FirmwareImage | None) -> str:
|
def _box_text(self, img: FirmwareImage | None) -> str:
|
||||||
fw = self.serial_tab.engine.firmware
|
fw = self.serial_tab.engine.firmware
|
||||||
if not fw.elf_sha:
|
if not fw.elf_sha:
|
||||||
return "Firmware on the box: unknown - connect in the Serial monitor and press Reset & capture to see it."
|
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()}"
|
msg = f"Box currently runs: {fw.describe()}"
|
||||||
if not img:
|
if not img:
|
||||||
return msg
|
return msg
|
||||||
if same_build(fw.elf_sha, img.app.elf_sha):
|
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>"
|
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)
|
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
|
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:
|
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>"
|
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:
|
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 "
|
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>")
|
"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>"
|
return msg + "<br><b style='color:#c77c02'>The box runs a different build.</b>"
|
||||||
|
|
||||||
# ------------------------------------------------------------ flash
|
# ------------------------------------------------------------ flash
|
||||||
def _start(self) -> None:
|
def _start(self) -> None:
|
||||||
img, port = self._selected_image(), self._selected_port()
|
img, port = self._selected_image(), self._selected_port()
|
||||||
if not img or not port:
|
if not img or not port:
|
||||||
return
|
return
|
||||||
mode = Mode.APP_ONLY if self.rb_app.isChecked() else Mode.FULL
|
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
|
what = ("the firmware app (pairing and settings are kept)" if mode == Mode.APP_ONLY
|
||||||
else "the COMPLETE image (pairing and OTA registration are erased)")
|
else "the COMPLETE image (pairing and OTA registration are erased)")
|
||||||
if QMessageBox.question(self, "Flash firmware",
|
if QMessageBox.question(self, "Flash firmware",
|
||||||
f"Write {what}\n\nFirmware: v{img.app.version}, compiled {img.app.built}\n"
|
f"Write {what}\n\nFirmware: v{img.app.version}, compiled {img.app.built}\n"
|
||||||
f"File: firmware/{img.name}\nBox: {port.label}\n\n"
|
f"File: firmware/{img.name}\nBox: {port.label}\n\n"
|
||||||
"Keep the box powered and the USB cable connected until it finishes.",
|
"Keep the box powered and the USB cable connected until it finishes.",
|
||||||
QMessageBox.StandardButton.Ok | QMessageBox.StandardButton.Cancel
|
QMessageBox.StandardButton.Ok | QMessageBox.StandardButton.Cancel
|
||||||
) != QMessageBox.StandardButton.Ok:
|
) != QMessageBox.StandardButton.Ok:
|
||||||
return
|
return
|
||||||
backup_to = None
|
backup_to = None
|
||||||
if self.backup.isChecked():
|
if self.backup.isChecked():
|
||||||
BACKUP_DIR.mkdir(parents=True, exist_ok=True)
|
BACKUP_DIR.mkdir(parents=True, exist_ok=True)
|
||||||
stamp = dt.datetime.now().strftime("%Y%m%d_%H%M%S")
|
stamp = dt.datetime.now().strftime("%Y%m%d_%H%M%S")
|
||||||
backup_to = BACKUP_DIR / f"{(port.mac or port.device).replace(':', '')}_{stamp}.bin"
|
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)
|
plan = build_plan(img, mode, port.device, Path(tempfile.mkdtemp(prefix="kota_flash_")), backup_to)
|
||||||
|
|
||||||
self._port, self._image = port, img
|
self._port, self._image = port, img
|
||||||
self.serial_tab.release_port() # esptool needs the port exclusively
|
self.serial_tab.release_port() # esptool needs the port exclusively
|
||||||
self.output.clear()
|
self.output.clear()
|
||||||
self.output.appendPlainText("\n".join(plan.summary()))
|
self.output.appendPlainText("\n".join(plan.summary()))
|
||||||
self._show_result("", None)
|
self._show_result("", None)
|
||||||
self._runner = FlashRunner(plan, self._bridge.step.emit, self._bridge.progress.emit,
|
self._runner = FlashRunner(plan, self._bridge.step.emit, self._bridge.progress.emit,
|
||||||
self._bridge.output.emit, self._bridge.done.emit)
|
self._bridge.output.emit, self._bridge.done.emit)
|
||||||
self._set_busy(True)
|
self._set_busy(True)
|
||||||
self._runner.start()
|
self._runner.start()
|
||||||
|
|
||||||
def _set_busy(self, busy: bool) -> None:
|
def _set_busy(self, busy: bool) -> None:
|
||||||
for w in (self.port_combo, self.image_combo, self.rb_app, self.backup, self.confirm_full,
|
for w in (self.port_combo, self.image_combo, self.rb_app, self.backup, self.confirm_full,
|
||||||
self.reload_btn):
|
self.reload_btn):
|
||||||
w.setEnabled(not busy)
|
w.setEnabled(not busy)
|
||||||
self._update()
|
self._update()
|
||||||
|
|
||||||
def _on_step(self, i: int, title: str) -> None:
|
def _on_step(self, i: int, title: str) -> None:
|
||||||
n = len(self._runner.plan.steps) if self._runner else 0
|
n = len(self._runner.plan.steps) if self._runner else 0
|
||||||
self.step_label.setText(f"Step {i + 1} of {n + 1}: {title}")
|
self.step_label.setText(f"Step {i + 1} of {n + 1}: {title}")
|
||||||
|
|
||||||
def _on_done(self, res: Result) -> None:
|
def _on_done(self, res: Result) -> None:
|
||||||
self._runner = None
|
self._runner = None
|
||||||
if not res.ok:
|
if not res.ok:
|
||||||
self._set_busy(False)
|
self._set_busy(False)
|
||||||
self.step_label.setText("Stopped.")
|
self.step_label.setText("Stopped.")
|
||||||
hint = f"<p>{res.hint}</p>" if res.hint else ""
|
hint = f"<p>{res.hint}</p>" if res.hint else ""
|
||||||
self._show_result(f"<b>Flashing failed.</b> {res.message}{hint}", "error")
|
self._show_result(f"<b>Flashing failed.</b> {res.message}{hint}", "error")
|
||||||
self.details_btn.setChecked(True)
|
self.details_btn.setChecked(True)
|
||||||
return
|
return
|
||||||
self.step_label.setText("Final step: restarting the box and checking which firmware it boots...")
|
self.step_label.setText("Final step: restarting the box and checking which firmware it boots...")
|
||||||
self.bar.setValue(0)
|
self.bar.setValue(0)
|
||||||
self._show_result("Firmware written. Waiting for the box to start...", "info")
|
self._show_result("Firmware written. Waiting for the box to start...", "info")
|
||||||
self.serial_tab.connect_port(self._port, capture=True)
|
self.serial_tab.connect_port(self._port, capture=True)
|
||||||
self._verify_ms = 0
|
self._verify_ms = 0
|
||||||
self._verify_timer.start()
|
self._verify_timer.start()
|
||||||
|
|
||||||
def _check_verify(self) -> None:
|
def _check_verify(self) -> None:
|
||||||
self._verify_ms += self._verify_timer.interval()
|
self._verify_ms += self._verify_timer.interval()
|
||||||
self.bar.setValue(min(100, int(100 * self._verify_ms / VERIFY_TIMEOUT_MS)))
|
self.bar.setValue(min(100, int(100 * self._verify_ms / VERIFY_TIMEOUT_MS)))
|
||||||
fw = self.serial_tab.engine.firmware
|
fw = self.serial_tab.engine.firmware
|
||||||
want = self._image.app.elf_sha[:8]
|
want = self._image.app.elf_sha[:8]
|
||||||
done = same_build(fw.elf_sha, self._image.app.elf_sha)
|
done = same_build(fw.elf_sha, self._image.app.elf_sha)
|
||||||
if done or self._verify_ms >= VERIFY_TIMEOUT_MS:
|
if done or self._verify_ms >= VERIFY_TIMEOUT_MS:
|
||||||
self._verify_timer.stop()
|
self._verify_timer.stop()
|
||||||
self._set_busy(False)
|
self._set_busy(False)
|
||||||
self.bar.setValue(100)
|
self.bar.setValue(100)
|
||||||
if done:
|
if done:
|
||||||
self.step_label.setText("Done.")
|
self.step_label.setText("Done.")
|
||||||
self._show_result(f"<b>Success.</b> The box boots the new firmware (build {want}). "
|
self._show_result(f"<b>Success.</b> The box boots the new firmware (build {want}). "
|
||||||
"Check the Diagnosis panel in the Serial monitor.", "ok")
|
"Check the Diagnosis panel in the Serial monitor.", "ok")
|
||||||
else:
|
else:
|
||||||
seen = fw.elf_sha[:8] if fw.elf_sha else "no boot seen"
|
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}. "
|
self._show_result(f"<b>Written, but not verified.</b> Expected build {want}, saw: {seen}. "
|
||||||
"Open the Serial monitor and press Reset & capture.", "warning")
|
"Open the Serial monitor and press Reset & capture.", "warning")
|
||||||
|
|
||||||
def _show_result(self, html: str, kind: str | None) -> None:
|
def _show_result(self, html: str, kind: str | None) -> None:
|
||||||
colours = {"ok": ("#2e9e44", "#e3f4e7"), "info": ("#2e6da4", "#e3edf7"),
|
colours = {"ok": ("#2e9e44", "#e3f4e7"), "info": ("#2e6da4", "#e3edf7"),
|
||||||
"warning": ("#c77c02", "#fdf0d6"), "error": ("#d9534f", "#f9e0df")}
|
"warning": ("#c77c02", "#fdf0d6"), "error": ("#d9534f", "#f9e0df")}
|
||||||
self.result.setVisible(bool(html))
|
self.result.setVisible(bool(html))
|
||||||
if html:
|
if html:
|
||||||
border, bg = colours[kind or "info"]
|
border, bg = colours[kind or "info"]
|
||||||
self.result.setStyleSheet(f"QLabel {{ border:2px solid {border}; background:{bg}; border-radius:6px; }}")
|
self.result.setStyleSheet(f"QLabel {{ border:2px solid {border}; background:{bg}; border-radius:6px; }}")
|
||||||
self.result.setText(html)
|
self.result.setText(html)
|
||||||
|
|
||||||
|
|
||||||
def _parse_built(s: str | None) -> dt.datetime | None:
|
def _parse_built(s: str | None) -> dt.datetime | None:
|
||||||
"""'Jun 29 2026 11:03:32' (app_init "Compile time") -> datetime."""
|
"""'Jun 29 2026 11:03:32' (app_init "Compile time") -> datetime."""
|
||||||
if not s:
|
if not s:
|
||||||
return None
|
return None
|
||||||
try:
|
try:
|
||||||
return dt.datetime.strptime(" ".join(s.split()), "%b %d %Y %H:%M:%S")
|
return dt.datetime.strptime(" ".join(s.split()), "%b %d %Y %H:%M:%S")
|
||||||
except ValueError:
|
except ValueError:
|
||||||
return None
|
return None
|
||||||
+424
-424
@@ -1,424 +1,424 @@
|
|||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
from pathlib import Path
|
from pathlib import Path
|
||||||
|
|
||||||
from PySide6.QtCore import QCoreApplication, QObject, QSettings, Qt, QTimer, QUrl, Signal
|
from PySide6.QtCore import QCoreApplication, QObject, QSettings, Qt, QTimer, QUrl, Signal
|
||||||
from PySide6.QtGui import QColor, QDesktopServices, QFont, QGuiApplication, QTextCharFormat, QTextCursor
|
from PySide6.QtGui import QColor, QDesktopServices, QFont, QGuiApplication, QTextCharFormat, QTextCursor
|
||||||
from PySide6.QtWidgets import (
|
from PySide6.QtWidgets import (
|
||||||
QCheckBox,
|
QCheckBox,
|
||||||
QComboBox,
|
QComboBox,
|
||||||
QFileDialog,
|
QFileDialog,
|
||||||
QHBoxLayout,
|
QHBoxLayout,
|
||||||
QInputDialog,
|
QInputDialog,
|
||||||
QLabel,
|
QLabel,
|
||||||
QMainWindow,
|
QMainWindow,
|
||||||
QMessageBox,
|
QMessageBox,
|
||||||
QPlainTextEdit,
|
QPlainTextEdit,
|
||||||
QPushButton,
|
QPushButton,
|
||||||
QSplitter,
|
QSplitter,
|
||||||
QTabWidget,
|
QTabWidget,
|
||||||
QTextBrowser,
|
QTextBrowser,
|
||||||
QVBoxLayout,
|
QVBoxLayout,
|
||||||
QWidget,
|
QWidget,
|
||||||
)
|
)
|
||||||
|
|
||||||
from .. import __version__
|
from .. import __version__
|
||||||
from ..core.logfile import read_log_file
|
from ..core.logfile import read_log_file
|
||||||
from ..core.logline import LineKind, LogLine, host_event
|
from ..core.logline import LineKind, LogLine, host_event
|
||||||
from ..core.session import SessionLog
|
from ..core.session import SessionLog
|
||||||
from ..diag.engine import DiagnosticsEngine
|
from ..diag.engine import DiagnosticsEngine
|
||||||
from ..diag.guides import GuideRunner
|
from ..diag.guides import GuideRunner
|
||||||
from ..serialio.manager import SerialManager, State
|
from ..serialio.manager import SerialManager, State
|
||||||
from ..serialio.ports import PortInfo, list_serial_ports
|
from ..serialio.ports import PortInfo, list_serial_ports
|
||||||
from ..matter.payload import SetupPayload, payload_from_log
|
from ..matter.payload import SetupPayload, payload_from_log
|
||||||
from ..service.report import DEFAULT_BASE, normalize_mac, report_url
|
from ..service.report import DEFAULT_BASE, normalize_mac, report_url
|
||||||
from .cheatsheet import cheatsheet_html
|
from .cheatsheet import cheatsheet_html
|
||||||
from .diag_panel import DiagnosticsPanel
|
from .diag_panel import DiagnosticsPanel
|
||||||
from .flash_tab import FlashTab
|
from .flash_tab import FlashTab
|
||||||
from .matter_qr import MatterQrDialog
|
from .matter_qr import MatterQrDialog
|
||||||
from .guide_panel import GuidePanel
|
from .guide_panel import GuidePanel
|
||||||
from .sd_tab import SdTab
|
from .sd_tab import SdTab
|
||||||
|
|
||||||
MAX_LINES = 20000
|
MAX_LINES = 20000
|
||||||
# "KOTA" = the firmware's structured diagnostic lines (1.0.16+) plus errors.
|
# "KOTA" = the firmware's structured diagnostic lines (1.0.16+) plus errors.
|
||||||
LEVEL_FILTERS = {"All lines": None, "KOTA diagnostics + errors": "KOTA",
|
LEVEL_FILTERS = {"All lines": None, "KOTA diagnostics + errors": "KOTA",
|
||||||
"Warnings + errors": {"W", "E"}, "Errors only": {"E"}}
|
"Warnings + errors": {"W", "E"}, "Errors only": {"E"}}
|
||||||
COLORS = {
|
COLORS = {
|
||||||
"E": "#ff6b6b",
|
"E": "#ff6b6b",
|
||||||
"W": "#f5c451",
|
"W": "#f5c451",
|
||||||
"I": "#d4d4d4",
|
"I": "#d4d4d4",
|
||||||
LineKind.BOOT: "#6fc3ff",
|
LineKind.BOOT: "#6fc3ff",
|
||||||
LineKind.RESET: "#6fc3ff",
|
LineKind.RESET: "#6fc3ff",
|
||||||
LineKind.PANIC: "#ff4dd2",
|
LineKind.PANIC: "#ff4dd2",
|
||||||
LineKind.HOST: "#7ee07e",
|
LineKind.HOST: "#7ee07e",
|
||||||
LineKind.KOTA: "#5fd7e8",
|
LineKind.KOTA: "#5fd7e8",
|
||||||
LineKind.RAW: "#a8a8a8",
|
LineKind.RAW: "#a8a8a8",
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
class _Bridge(QObject):
|
class _Bridge(QObject):
|
||||||
"""Marshals SerialManager callbacks (reader thread) onto the UI thread."""
|
"""Marshals SerialManager callbacks (reader thread) onto the UI thread."""
|
||||||
|
|
||||||
line = Signal(object)
|
line = Signal(object)
|
||||||
state = Signal(object, str)
|
state = Signal(object, str)
|
||||||
|
|
||||||
|
|
||||||
class SerialTab(QWidget):
|
class SerialTab(QWidget):
|
||||||
def __init__(self, parent: QWidget | None = None):
|
def __init__(self, parent: QWidget | None = None):
|
||||||
super().__init__(parent)
|
super().__init__(parent)
|
||||||
self._bridge = _Bridge()
|
self._bridge = _Bridge()
|
||||||
self._bridge.line.connect(self._on_line)
|
self._bridge.line.connect(self._on_line)
|
||||||
self._bridge.state.connect(self._on_state)
|
self._bridge.state.connect(self._on_state)
|
||||||
self._manager = SerialManager(self._bridge.line.emit, self._bridge.state.emit)
|
self._manager = SerialManager(self._bridge.line.emit, self._bridge.state.emit)
|
||||||
self._session = SessionLog()
|
self._session = SessionLog()
|
||||||
self._ports: list[PortInfo] = []
|
self._ports: list[PortInfo] = []
|
||||||
self._counts = {"E": 0, "W": 0, "boots": 0}
|
self._counts = {"E": 0, "W": 0, "boots": 0}
|
||||||
self._engine = DiagnosticsEngine()
|
self._engine = DiagnosticsEngine()
|
||||||
self._diag_dirty = True
|
self._diag_dirty = True
|
||||||
self._runner = GuideRunner(self._engine, on_action=self._guide_action, on_log=self._guide_log)
|
self._runner = GuideRunner(self._engine, on_action=self._guide_action, on_log=self._guide_log)
|
||||||
|
|
||||||
# --- controls
|
# --- controls
|
||||||
self.port_combo = QComboBox(minimumWidth=320)
|
self.port_combo = QComboBox(minimumWidth=320)
|
||||||
self.all_ports = QCheckBox("Show all ports")
|
self.all_ports = QCheckBox("Show all ports")
|
||||||
self.refresh_btn = QPushButton("Refresh")
|
self.refresh_btn = QPushButton("Refresh")
|
||||||
self.connect_btn = QPushButton("Connect")
|
self.connect_btn = QPushButton("Connect")
|
||||||
self.reset_btn = QPushButton("Reset && capture")
|
self.reset_btn = QPushButton("Reset && capture")
|
||||||
self.reset_btn.setToolTip("Reboot the sensorbox and record the log from the first boot line")
|
self.reset_btn.setToolTip("Reboot the sensorbox and record the log from the first boot line")
|
||||||
self.filter_combo = QComboBox()
|
self.filter_combo = QComboBox()
|
||||||
self.filter_combo.addItems(LEVEL_FILTERS)
|
self.filter_combo.addItems(LEVEL_FILTERS)
|
||||||
self.clear_btn = QPushButton("Clear view")
|
self.clear_btn = QPushButton("Clear view")
|
||||||
self.save_btn = QPushButton("Save view as...")
|
self.save_btn = QPushButton("Save view as...")
|
||||||
self.folder_btn = QPushButton("Open logs folder")
|
self.folder_btn = QPushButton("Open logs folder")
|
||||||
self.analyze_btn = QPushButton("Analyze log file...")
|
self.analyze_btn = QPushButton("Analyze log file...")
|
||||||
self.analyze_btn.setToolTip("Load a saved session log or serial capture and diagnose it")
|
self.analyze_btn.setToolTip("Load a saved session log or serial capture and diagnose it")
|
||||||
self.copy_btn = QPushButton("Copy report")
|
self.copy_btn = QPushButton("Copy report")
|
||||||
self.copy_btn.setToolTip("Copy the diagnosis as text (e.g. to send to the firmware team)")
|
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 = QPushButton("Service report...")
|
||||||
self.service_btn.setToolTip("Open this box's page in the KOTA service system with the diagnosis "
|
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")
|
"filled in; check it and press Save there")
|
||||||
self._settings = QSettings("KOTA", "TechnicianTool")
|
self._settings = QSettings("KOTA", "TechnicianTool")
|
||||||
self.auto_service = QCheckBox("Open service report on disconnect")
|
self.auto_service = QCheckBox("Open service report on disconnect")
|
||||||
self.auto_service.setChecked(self._settings.value("service/auto", False, type=bool))
|
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.auto_service.toggled.connect(lambda on: self._settings.setValue("service/auto", on))
|
||||||
self._active_port: PortInfo | None = None
|
self._active_port: PortInfo | None = None
|
||||||
|
|
||||||
row1 = QHBoxLayout()
|
row1 = QHBoxLayout()
|
||||||
for w in (QLabel("Port:"), self.port_combo, self.all_ports, self.refresh_btn,
|
for w in (QLabel("Port:"), self.port_combo, self.all_ports, self.refresh_btn,
|
||||||
self.connect_btn, self.reset_btn):
|
self.connect_btn, self.reset_btn):
|
||||||
row1.addWidget(w)
|
row1.addWidget(w)
|
||||||
row1.addStretch(1)
|
row1.addStretch(1)
|
||||||
row2 = QHBoxLayout()
|
row2 = QHBoxLayout()
|
||||||
for w in (QLabel("Show:"), self.filter_combo, self.clear_btn, self.save_btn, self.folder_btn,
|
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):
|
self.analyze_btn, self.copy_btn, self.service_btn, self.auto_service):
|
||||||
row2.addWidget(w)
|
row2.addWidget(w)
|
||||||
row2.addStretch(1)
|
row2.addStretch(1)
|
||||||
|
|
||||||
self.view = QPlainTextEdit(readOnly=True)
|
self.view = QPlainTextEdit(readOnly=True)
|
||||||
self.view.setMaximumBlockCount(MAX_LINES)
|
self.view.setMaximumBlockCount(MAX_LINES)
|
||||||
self.view.setLineWrapMode(QPlainTextEdit.LineWrapMode.NoWrap)
|
self.view.setLineWrapMode(QPlainTextEdit.LineWrapMode.NoWrap)
|
||||||
mono = QFont("Menlo" if QFont("Menlo").exactMatch() else "Consolas")
|
mono = QFont("Menlo" if QFont("Menlo").exactMatch() else "Consolas")
|
||||||
mono.setStyleHint(QFont.StyleHint.Monospace)
|
mono.setStyleHint(QFont.StyleHint.Monospace)
|
||||||
mono.setPointSize(10)
|
mono.setPointSize(10)
|
||||||
self.view.setFont(mono)
|
self.view.setFont(mono)
|
||||||
self.view.setStyleSheet("QPlainTextEdit { background:#1e1e1e; color:#d4d4d4; }")
|
self.view.setStyleSheet("QPlainTextEdit { background:#1e1e1e; color:#d4d4d4; }")
|
||||||
|
|
||||||
self.diag = DiagnosticsPanel()
|
self.diag = DiagnosticsPanel()
|
||||||
self.guide = GuidePanel(self._runner, self._engine, matter_payload=self.matter_payload)
|
self.guide = GuidePanel(self._runner, self._engine, matter_payload=self.matter_payload)
|
||||||
self.side_tabs = QTabWidget()
|
self.side_tabs = QTabWidget()
|
||||||
self.side_tabs.addTab(self.diag, "Diagnosis")
|
self.side_tabs.addTab(self.diag, "Diagnosis")
|
||||||
self.side_tabs.addTab(self.guide, "Guided troubleshooting")
|
self.side_tabs.addTab(self.guide, "Guided troubleshooting")
|
||||||
split = QSplitter(Qt.Orientation.Horizontal)
|
split = QSplitter(Qt.Orientation.Horizontal)
|
||||||
split.addWidget(self.view)
|
split.addWidget(self.view)
|
||||||
split.addWidget(self.side_tabs)
|
split.addWidget(self.side_tabs)
|
||||||
split.setStretchFactor(0, 3)
|
split.setStretchFactor(0, 3)
|
||||||
split.setStretchFactor(1, 2)
|
split.setStretchFactor(1, 2)
|
||||||
split.setSizes([700, 480])
|
split.setSizes([700, 480])
|
||||||
|
|
||||||
self.status = QLabel()
|
self.status = QLabel()
|
||||||
layout = QVBoxLayout(self)
|
layout = QVBoxLayout(self)
|
||||||
layout.addLayout(row1)
|
layout.addLayout(row1)
|
||||||
layout.addLayout(row2)
|
layout.addLayout(row2)
|
||||||
layout.addWidget(split, 1)
|
layout.addWidget(split, 1)
|
||||||
layout.addWidget(self.status)
|
layout.addWidget(self.status)
|
||||||
|
|
||||||
# --- wiring
|
# --- wiring
|
||||||
self.refresh_btn.clicked.connect(self.refresh_ports)
|
self.refresh_btn.clicked.connect(self.refresh_ports)
|
||||||
self.all_ports.toggled.connect(self.refresh_ports)
|
self.all_ports.toggled.connect(self.refresh_ports)
|
||||||
self.connect_btn.clicked.connect(self._toggle_connect)
|
self.connect_btn.clicked.connect(self._toggle_connect)
|
||||||
self.reset_btn.clicked.connect(self._manager.reset_board)
|
self.reset_btn.clicked.connect(self._manager.reset_board)
|
||||||
self.clear_btn.clicked.connect(self.view.clear)
|
self.clear_btn.clicked.connect(self.view.clear)
|
||||||
self.save_btn.clicked.connect(self._save_view)
|
self.save_btn.clicked.connect(self._save_view)
|
||||||
self.folder_btn.clicked.connect(self._open_folder)
|
self.folder_btn.clicked.connect(self._open_folder)
|
||||||
self.analyze_btn.clicked.connect(self._analyze_file)
|
self.analyze_btn.clicked.connect(self._analyze_file)
|
||||||
self.copy_btn.clicked.connect(self._copy_report)
|
self.copy_btn.clicked.connect(self._copy_report)
|
||||||
self.service_btn.clicked.connect(lambda: self._open_service_report(auto=False))
|
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())
|
self.diag.qr_btn.clicked.connect(lambda: MatterQrDialog(self.matter_payload(), self).exec())
|
||||||
|
|
||||||
# Report refresh is throttled; lines can arrive at >100/s.
|
# Report refresh is throttled; lines can arrive at >100/s.
|
||||||
self._diag_timer = QTimer(self, interval=400)
|
self._diag_timer = QTimer(self, interval=400)
|
||||||
self._diag_timer.timeout.connect(self._refresh_diag)
|
self._diag_timer.timeout.connect(self._refresh_diag)
|
||||||
self._diag_timer.start()
|
self._diag_timer.start()
|
||||||
|
|
||||||
# Auto-detect a box being plugged in while idle.
|
# Auto-detect a box being plugged in while idle.
|
||||||
self._poll = QTimer(self, interval=2000)
|
self._poll = QTimer(self, interval=2000)
|
||||||
self._poll.timeout.connect(self._auto_refresh)
|
self._poll.timeout.connect(self._auto_refresh)
|
||||||
self._poll.start()
|
self._poll.start()
|
||||||
|
|
||||||
self.refresh_ports()
|
self.refresh_ports()
|
||||||
self._on_state(State.DISCONNECTED, "")
|
self._on_state(State.DISCONNECTED, "")
|
||||||
|
|
||||||
# ---- ports -------------------------------------------------------
|
# ---- ports -------------------------------------------------------
|
||||||
def refresh_ports(self) -> None:
|
def refresh_ports(self) -> None:
|
||||||
current = self.port_combo.currentData()
|
current = self.port_combo.currentData()
|
||||||
self._ports = list_serial_ports(include_all=self.all_ports.isChecked())
|
self._ports = list_serial_ports(include_all=self.all_ports.isChecked())
|
||||||
self.port_combo.clear()
|
self.port_combo.clear()
|
||||||
for p in self._ports:
|
for p in self._ports:
|
||||||
self.port_combo.addItem(p.label, p.device)
|
self.port_combo.addItem(p.label, p.device)
|
||||||
if not self._ports:
|
if not self._ports:
|
||||||
self.port_combo.addItem("No sensorbox found - check USB cable and power switch", None)
|
self.port_combo.addItem("No sensorbox found - check USB cable and power switch", None)
|
||||||
idx = self.port_combo.findData(current)
|
idx = self.port_combo.findData(current)
|
||||||
self.port_combo.setCurrentIndex(max(idx, 0))
|
self.port_combo.setCurrentIndex(max(idx, 0))
|
||||||
|
|
||||||
def _auto_refresh(self) -> None:
|
def _auto_refresh(self) -> None:
|
||||||
if self._manager.is_running:
|
if self._manager.is_running:
|
||||||
return
|
return
|
||||||
devices = [p.device for p in list_serial_ports(self.all_ports.isChecked())]
|
devices = [p.device for p in list_serial_ports(self.all_ports.isChecked())]
|
||||||
if devices != [p.device for p in self._ports]:
|
if devices != [p.device for p in self._ports]:
|
||||||
self.refresh_ports()
|
self.refresh_ports()
|
||||||
|
|
||||||
def _selected_port(self) -> PortInfo | None:
|
def _selected_port(self) -> PortInfo | None:
|
||||||
dev = self.port_combo.currentData()
|
dev = self.port_combo.currentData()
|
||||||
return next((p for p in self._ports if p.device == dev), None)
|
return next((p for p in self._ports if p.device == dev), None)
|
||||||
|
|
||||||
# ---- connection --------------------------------------------------
|
# ---- connection --------------------------------------------------
|
||||||
def _toggle_connect(self) -> None:
|
def _toggle_connect(self) -> None:
|
||||||
if self._manager.is_running:
|
if self._manager.is_running:
|
||||||
# Session file is closed in _on_state(DISCONNECTED), after the
|
# Session file is closed in _on_state(DISCONNECTED), after the
|
||||||
# reader thread's final queued lines have been written.
|
# reader thread's final queued lines have been written.
|
||||||
self._manager.disconnect()
|
self._manager.disconnect()
|
||||||
return
|
return
|
||||||
port = self._selected_port()
|
port = self._selected_port()
|
||||||
if port is None:
|
if port is None:
|
||||||
return
|
return
|
||||||
self._connect(port)
|
self._connect(port)
|
||||||
|
|
||||||
def _connect(self, port: PortInfo) -> None:
|
def _connect(self, port: PortInfo) -> None:
|
||||||
self._counts = {"E": 0, "W": 0, "boots": 0}
|
self._counts = {"E": 0, "W": 0, "boots": 0}
|
||||||
self._engine.reset()
|
self._engine.reset()
|
||||||
self._runner.cancel()
|
self._runner.cancel()
|
||||||
self._diag_dirty = True
|
self._diag_dirty = True
|
||||||
self._session.start(port.mac or port.device)
|
self._session.start(port.mac or port.device)
|
||||||
self._active_port = port
|
self._active_port = port
|
||||||
self._manager.connect(port)
|
self._manager.connect(port)
|
||||||
|
|
||||||
def matter_payload(self) -> SetupPayload:
|
def matter_payload(self) -> SetupPayload:
|
||||||
"""Pairing payload reported by this box (KOTA: matter), from its log, or the defaults."""
|
"""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 [],
|
return payload_from_log([self._engine.matter_advert] if self._engine.matter_advert else [],
|
||||||
self._engine.matter_qr, self._engine.matter_manual)
|
self._engine.matter_qr, self._engine.matter_manual)
|
||||||
|
|
||||||
# ---- service system -------------------------------------------------
|
# ---- service system -------------------------------------------------
|
||||||
def _service_base(self) -> str:
|
def _service_base(self) -> str:
|
||||||
return str(self._settings.value("service/base", DEFAULT_BASE))
|
return str(self._settings.value("service/base", DEFAULT_BASE))
|
||||||
|
|
||||||
def _open_service_report(self, auto: bool) -> None:
|
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 "")
|
mac = normalize_mac(self._engine.mac or (self._active_port.mac if self._active_port else "") or "")
|
||||||
if len(mac) != 12:
|
if len(mac) != 12:
|
||||||
if not auto:
|
if not auto:
|
||||||
QMessageBox.information(self, "Service report", "The box's MAC address is not known yet. "
|
QMessageBox.information(self, "Service report", "The box's MAC address is not known yet. "
|
||||||
"Connect to the box and press Reset & capture first.")
|
"Connect to the box and press Reset & capture first.")
|
||||||
return
|
return
|
||||||
url = report_url(mac, self._engine.report(), self._service_base())
|
url = report_url(mac, self._engine.report(), self._service_base())
|
||||||
QDesktopServices.openUrl(QUrl(url))
|
QDesktopServices.openUrl(QUrl(url))
|
||||||
# Log that it happened, not the report itself (it is already in the session log).
|
# 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")
|
self._guide_log(f"service report for {mac} opened in the browser - check it and press Save there")
|
||||||
|
|
||||||
# ---- hand-off with the flash tab ------------------------------------
|
# ---- hand-off with the flash tab ------------------------------------
|
||||||
@property
|
@property
|
||||||
def engine(self) -> DiagnosticsEngine:
|
def engine(self) -> DiagnosticsEngine:
|
||||||
return self._engine
|
return self._engine
|
||||||
|
|
||||||
def release_port(self) -> None:
|
def release_port(self) -> None:
|
||||||
"""Stop monitoring so esptool can open the port exclusively."""
|
"""Stop monitoring so esptool can open the port exclusively."""
|
||||||
if self._manager.is_running:
|
if self._manager.is_running:
|
||||||
self._no_auto_service = True # a flash hand-off is not the end of a session
|
self._no_auto_service = True # a flash hand-off is not the end of a session
|
||||||
self._manager.disconnect() # joins the reader thread
|
self._manager.disconnect() # joins the reader thread
|
||||||
QCoreApplication.processEvents() # deliver its queued final lines/state now
|
QCoreApplication.processEvents() # deliver its queued final lines/state now
|
||||||
self._no_auto_service = False
|
self._no_auto_service = False
|
||||||
|
|
||||||
def connect_port(self, port: PortInfo, capture: bool = True) -> None:
|
def connect_port(self, port: PortInfo, capture: bool = True) -> None:
|
||||||
"""Monitor `port`; with capture, restart the box once connected to record its boot."""
|
"""Monitor `port`; with capture, restart the box once connected to record its boot."""
|
||||||
self.release_port()
|
self.release_port()
|
||||||
idx = self.port_combo.findData(port.device)
|
idx = self.port_combo.findData(port.device)
|
||||||
if idx < 0:
|
if idx < 0:
|
||||||
self.port_combo.addItem(port.label, port.device)
|
self.port_combo.addItem(port.label, port.device)
|
||||||
self._ports.append(port)
|
self._ports.append(port)
|
||||||
idx = self.port_combo.count() - 1
|
idx = self.port_combo.count() - 1
|
||||||
self.port_combo.setCurrentIndex(idx)
|
self.port_combo.setCurrentIndex(idx)
|
||||||
self._reset_on_connect = capture
|
self._reset_on_connect = capture
|
||||||
self._connect(port)
|
self._connect(port)
|
||||||
|
|
||||||
def _on_state(self, state: State, detail: str) -> None:
|
def _on_state(self, state: State, detail: str) -> None:
|
||||||
running = state != State.DISCONNECTED
|
running = state != State.DISCONNECTED
|
||||||
if not running and self._manager.is_running:
|
if not running and self._manager.is_running:
|
||||||
return # stale event from a session that was already replaced
|
return # stale event from a session that was already replaced
|
||||||
if state == State.CONNECTED and getattr(self, "_reset_on_connect", False):
|
if state == State.CONNECTED and getattr(self, "_reset_on_connect", False):
|
||||||
self._reset_on_connect = False
|
self._reset_on_connect = False
|
||||||
QTimer.singleShot(300, self._manager.reset_board)
|
QTimer.singleShot(300, self._manager.reset_board)
|
||||||
if not running and self._session.path is not None:
|
if not running and self._session.path is not None:
|
||||||
self._session.write_report(self._engine.report().to_text())
|
self._session.write_report(self._engine.report().to_text())
|
||||||
if (self.auto_service.isChecked() and self._engine.lines
|
if (self.auto_service.isChecked() and self._engine.lines
|
||||||
and not getattr(self, "_no_auto_service", False)):
|
and not getattr(self, "_no_auto_service", False)):
|
||||||
self._open_service_report(auto=True)
|
self._open_service_report(auto=True)
|
||||||
self._session.stop()
|
self._session.stop()
|
||||||
self.connect_btn.setText("Disconnect" if running else "Connect")
|
self.connect_btn.setText("Disconnect" if running else "Connect")
|
||||||
self.reset_btn.setEnabled(state == State.CONNECTED)
|
self.reset_btn.setEnabled(state == State.CONNECTED)
|
||||||
self.port_combo.setEnabled(not running)
|
self.port_combo.setEnabled(not running)
|
||||||
self.all_ports.setEnabled(not running)
|
self.all_ports.setEnabled(not running)
|
||||||
self.refresh_btn.setEnabled(not running)
|
self.refresh_btn.setEnabled(not running)
|
||||||
# Offline analysis would mix with the live session; disconnect first.
|
# Offline analysis would mix with the live session; disconnect first.
|
||||||
self.analyze_btn.setEnabled(not running)
|
self.analyze_btn.setEnabled(not running)
|
||||||
self._state_text = f"{state.value}" + (f" ({detail})" if detail else "")
|
self._state_text = f"{state.value}" + (f" ({detail})" if detail else "")
|
||||||
self._update_status()
|
self._update_status()
|
||||||
|
|
||||||
def _update_status(self) -> None:
|
def _update_status(self) -> None:
|
||||||
sess = f" | Session log: {self._session.path}" if self._session.path else ""
|
sess = f" | Session log: {self._session.path}" if self._session.path else ""
|
||||||
c = self._counts
|
c = self._counts
|
||||||
self.status.setText(
|
self.status.setText(
|
||||||
f"{getattr(self, '_state_text', '')} | boots seen: {c['boots']} "
|
f"{getattr(self, '_state_text', '')} | boots seen: {c['boots']} "
|
||||||
f"errors: {c['E']} warnings: {c['W']}{sess}"
|
f"errors: {c['E']} warnings: {c['W']}{sess}"
|
||||||
)
|
)
|
||||||
|
|
||||||
# ---- lines -------------------------------------------------------
|
# ---- lines -------------------------------------------------------
|
||||||
def _on_line(self, line: LogLine) -> None:
|
def _on_line(self, line: LogLine) -> None:
|
||||||
self._session.write(line)
|
self._session.write(line)
|
||||||
self._engine.feed(line)
|
self._engine.feed(line)
|
||||||
self._runner.feed(line)
|
self._runner.feed(line)
|
||||||
self._diag_dirty = True
|
self._diag_dirty = True
|
||||||
if line.kind == LineKind.BOOT:
|
if line.kind == LineKind.BOOT:
|
||||||
self._counts["boots"] += 1
|
self._counts["boots"] += 1
|
||||||
if line.level in ("E", "W"):
|
if line.level in ("E", "W"):
|
||||||
self._counts[line.level] += 1
|
self._counts[line.level] += 1
|
||||||
self._update_status()
|
self._update_status()
|
||||||
|
|
||||||
if self._visible(line):
|
if self._visible(line):
|
||||||
self._append(line)
|
self._append(line)
|
||||||
|
|
||||||
def _visible(self, line: LogLine) -> bool:
|
def _visible(self, line: LogLine) -> bool:
|
||||||
allowed = LEVEL_FILTERS[self.filter_combo.currentText()]
|
allowed = LEVEL_FILTERS[self.filter_combo.currentText()]
|
||||||
if allowed is None or line.kind in (LineKind.HOST, LineKind.PANIC, LineKind.BOOT, LineKind.RESET):
|
if allowed is None or line.kind in (LineKind.HOST, LineKind.PANIC, LineKind.BOOT, LineKind.RESET):
|
||||||
return True
|
return True
|
||||||
if allowed == "KOTA":
|
if allowed == "KOTA":
|
||||||
return line.kind == LineKind.KOTA or line.level == "E"
|
return line.kind == LineKind.KOTA or line.level == "E"
|
||||||
return line.level in allowed
|
return line.level in allowed
|
||||||
|
|
||||||
def _append(self, line: LogLine) -> None:
|
def _append(self, line: LogLine) -> None:
|
||||||
sb = self.view.verticalScrollBar()
|
sb = self.view.verticalScrollBar()
|
||||||
at_bottom = sb.value() >= sb.maximum() - 4
|
at_bottom = sb.value() >= sb.maximum() - 4
|
||||||
fmt = QTextCharFormat()
|
fmt = QTextCharFormat()
|
||||||
colour = COLORS.get(line.kind) if line.kind == LineKind.KOTA and line.level == "I" else None
|
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")))
|
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"):
|
if line.kind in (LineKind.PANIC, LineKind.BOOT, LineKind.HOST) or line.record in ("boot", "status"):
|
||||||
fmt.setFontWeight(QFont.Weight.Bold)
|
fmt.setFontWeight(QFont.Weight.Bold)
|
||||||
cur = QTextCursor(self.view.document())
|
cur = QTextCursor(self.view.document())
|
||||||
cur.movePosition(QTextCursor.MoveOperation.End)
|
cur.movePosition(QTextCursor.MoveOperation.End)
|
||||||
if not self.view.document().isEmpty():
|
if not self.view.document().isEmpty():
|
||||||
cur.insertBlock()
|
cur.insertBlock()
|
||||||
cur.insertText(line.text, fmt)
|
cur.insertText(line.text, fmt)
|
||||||
if at_bottom:
|
if at_bottom:
|
||||||
sb.setValue(sb.maximum())
|
sb.setValue(sb.maximum())
|
||||||
|
|
||||||
# ---- diagnostics -------------------------------------------------
|
# ---- diagnostics -------------------------------------------------
|
||||||
def _refresh_diag(self) -> None:
|
def _refresh_diag(self) -> None:
|
||||||
if self._diag_dirty:
|
if self._diag_dirty:
|
||||||
self._diag_dirty = False
|
self._diag_dirty = False
|
||||||
self.diag.show_report(self._engine.report())
|
self.diag.show_report(self._engine.report())
|
||||||
self.guide.refresh() # countdowns and timeouts need a steady tick
|
self.guide.refresh() # countdowns and timeouts need a steady tick
|
||||||
|
|
||||||
# ---- guided troubleshooting hooks ------------------------------------
|
# ---- guided troubleshooting hooks ------------------------------------
|
||||||
def _guide_action(self, action: str) -> bool:
|
def _guide_action(self, action: str) -> bool:
|
||||||
if action == "reset" and self._manager.state == State.CONNECTED:
|
if action == "reset" and self._manager.state == State.CONNECTED:
|
||||||
self._manager.reset_board()
|
self._manager.reset_board()
|
||||||
return True
|
return True
|
||||||
return False
|
return False
|
||||||
|
|
||||||
def _guide_log(self, text: str) -> None:
|
def _guide_log(self, text: str) -> None:
|
||||||
# Technician answers go into the session log and the log view.
|
# Technician answers go into the session log and the log view.
|
||||||
line = host_event(text)
|
line = host_event(text)
|
||||||
self._session.write(line)
|
self._session.write(line)
|
||||||
self._append(line)
|
self._append(line)
|
||||||
self._diag_dirty = True
|
self._diag_dirty = True
|
||||||
|
|
||||||
def _copy_report(self) -> None:
|
def _copy_report(self) -> None:
|
||||||
QGuiApplication.clipboard().setText(self._engine.report().to_text())
|
QGuiApplication.clipboard().setText(self._engine.report().to_text())
|
||||||
|
|
||||||
def _analyze_file(self) -> None:
|
def _analyze_file(self) -> None:
|
||||||
path, _ = QFileDialog.getOpenFileName(
|
path, _ = QFileDialog.getOpenFileName(
|
||||||
self, "Analyze log file", str(self._session.root), "Logs (*.log *.txt);;All files (*)")
|
self, "Analyze log file", str(self._session.root), "Logs (*.log *.txt);;All files (*)")
|
||||||
if not path:
|
if not path:
|
||||||
return
|
return
|
||||||
lines = read_log_file(Path(path))
|
lines = read_log_file(Path(path))
|
||||||
self.view.clear()
|
self.view.clear()
|
||||||
self._engine.reset()
|
self._engine.reset()
|
||||||
self._runner.cancel()
|
self._runner.cancel()
|
||||||
self._counts = {"E": 0, "W": 0, "boots": 0}
|
self._counts = {"E": 0, "W": 0, "boots": 0}
|
||||||
for line in lines:
|
for line in lines:
|
||||||
self._engine.feed(line)
|
self._engine.feed(line)
|
||||||
if line.kind == LineKind.BOOT:
|
if line.kind == LineKind.BOOT:
|
||||||
self._counts["boots"] += 1
|
self._counts["boots"] += 1
|
||||||
if line.level in ("E", "W"):
|
if line.level in ("E", "W"):
|
||||||
self._counts[line.level] += 1
|
self._counts[line.level] += 1
|
||||||
self._append(line)
|
self._append(line)
|
||||||
self._state_text = f"Analyzed file: {Path(path).name} ({len(lines)} lines)"
|
self._state_text = f"Analyzed file: {Path(path).name} ({len(lines)} lines)"
|
||||||
self._update_status()
|
self._update_status()
|
||||||
self._diag_dirty = True
|
self._diag_dirty = True
|
||||||
self._refresh_diag()
|
self._refresh_diag()
|
||||||
|
|
||||||
# ---- misc --------------------------------------------------------
|
# ---- misc --------------------------------------------------------
|
||||||
def _save_view(self) -> None:
|
def _save_view(self) -> None:
|
||||||
path, _ = QFileDialog.getSaveFileName(self, "Save log view", "sensorbox_log.txt", "Text (*.txt)")
|
path, _ = QFileDialog.getSaveFileName(self, "Save log view", "sensorbox_log.txt", "Text (*.txt)")
|
||||||
if path:
|
if path:
|
||||||
with open(path, "w", encoding="utf-8") as fh:
|
with open(path, "w", encoding="utf-8") as fh:
|
||||||
fh.write(self.view.toPlainText())
|
fh.write(self.view.toPlainText())
|
||||||
|
|
||||||
def _open_folder(self) -> None:
|
def _open_folder(self) -> None:
|
||||||
self._session.root.mkdir(parents=True, exist_ok=True)
|
self._session.root.mkdir(parents=True, exist_ok=True)
|
||||||
QDesktopServices.openUrl(QUrl.fromLocalFile(str(self._session.root)))
|
QDesktopServices.openUrl(QUrl.fromLocalFile(str(self._session.root)))
|
||||||
|
|
||||||
def shutdown(self) -> None:
|
def shutdown(self) -> None:
|
||||||
self._manager.disconnect()
|
self._manager.disconnect()
|
||||||
self._session.stop()
|
self._session.stop()
|
||||||
|
|
||||||
|
|
||||||
class MainWindow(QMainWindow):
|
class MainWindow(QMainWindow):
|
||||||
def __init__(self):
|
def __init__(self):
|
||||||
super().__init__()
|
super().__init__()
|
||||||
self.setWindowTitle(f"KOTA Sensorbox Technician Tool v{__version__}")
|
self.setWindowTitle(f"KOTA Sensorbox Technician Tool v{__version__}")
|
||||||
self.resize(1200, 800)
|
self.resize(1200, 800)
|
||||||
tabs = QTabWidget()
|
tabs = QTabWidget()
|
||||||
guide = QTextBrowser(openExternalLinks=True)
|
guide = QTextBrowser(openExternalLinks=True)
|
||||||
guide.setHtml(cheatsheet_html())
|
guide.setHtml(cheatsheet_html())
|
||||||
self.serial_tab = SerialTab()
|
self.serial_tab = SerialTab()
|
||||||
self.flash_tab = FlashTab(self.serial_tab)
|
self.flash_tab = FlashTab(self.serial_tab)
|
||||||
tabs.addTab(guide, "Quick start")
|
tabs.addTab(guide, "Quick start")
|
||||||
tabs.addTab(self.serial_tab, "Serial monitor")
|
tabs.addTab(self.serial_tab, "Serial monitor")
|
||||||
tabs.addTab(self.flash_tab, "Flash firmware")
|
tabs.addTab(self.flash_tab, "Flash firmware")
|
||||||
self.sd_tab = SdTab(self.serial_tab)
|
self.sd_tab = SdTab(self.serial_tab)
|
||||||
tabs.addTab(self.sd_tab, "SD card")
|
tabs.addTab(self.sd_tab, "SD card")
|
||||||
self.setCentralWidget(tabs)
|
self.setCentralWidget(tabs)
|
||||||
settings_menu = self.menuBar().addMenu("Settings")
|
settings_menu = self.menuBar().addMenu("Settings")
|
||||||
settings_menu.addAction("Service system address...", self._edit_service_base)
|
settings_menu.addAction("Service system address...", self._edit_service_base)
|
||||||
|
|
||||||
def _edit_service_base(self) -> None:
|
def _edit_service_base(self) -> None:
|
||||||
st = self.serial_tab
|
st = self.serial_tab
|
||||||
text, ok = QInputDialog.getText(
|
text, ok = QInputDialog.getText(
|
||||||
self, "Service system address",
|
self, "Service system address",
|
||||||
"Address of the KOTA service system (the box MAC is added at the end):",
|
"Address of the KOTA service system (the box MAC is added at the end):",
|
||||||
text=st._service_base())
|
text=st._service_base())
|
||||||
if ok and text.strip().startswith(("https://", "http://")):
|
if ok and text.strip().startswith(("https://", "http://")):
|
||||||
st._settings.setValue("service/base", text.strip())
|
st._settings.setValue("service/base", text.strip())
|
||||||
elif ok:
|
elif ok:
|
||||||
QMessageBox.warning(self, "Service system address", "The address must start with https://")
|
QMessageBox.warning(self, "Service system address", "The address must start with https://")
|
||||||
|
|
||||||
def closeEvent(self, event): # noqa: N802 (Qt naming)
|
def closeEvent(self, event): # noqa: N802 (Qt naming)
|
||||||
self.serial_tab.shutdown()
|
self.serial_tab.shutdown()
|
||||||
super().closeEvent(event)
|
super().closeEvent(event)
|
||||||
+76
-76
@@ -1,76 +1,76 @@
|
|||||||
"""Matter pairing QR code on screen, so the technician can scan it from the laptop."""
|
"""Matter pairing QR code on screen, so the technician can scan it from the laptop."""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
import segno
|
import segno
|
||||||
from PySide6.QtCore import Qt
|
from PySide6.QtCore import Qt
|
||||||
from PySide6.QtGui import QColor, QImage, QPainter, QPixmap
|
from PySide6.QtGui import QColor, QImage, QPainter, QPixmap
|
||||||
from PySide6.QtWidgets import QDialog, QDialogButtonBox, QLabel, QVBoxLayout, QWidget
|
from PySide6.QtWidgets import QDialog, QDialogButtonBox, QLabel, QVBoxLayout, QWidget
|
||||||
|
|
||||||
from ..matter.payload import SetupPayload
|
from ..matter.payload import SetupPayload
|
||||||
|
|
||||||
|
|
||||||
def qr_pixmap(text: str, size: int = 260) -> QPixmap:
|
def qr_pixmap(text: str, size: int = 260) -> QPixmap:
|
||||||
"""Black-on-white QR with the quiet zone phones need (4 modules)."""
|
"""Black-on-white QR with the quiet zone phones need (4 modules)."""
|
||||||
qr = segno.make(text, error="m")
|
qr = segno.make(text, error="m")
|
||||||
matrix = [list(row) for row in qr.matrix_iter(scale=1, border=4)]
|
matrix = [list(row) for row in qr.matrix_iter(scale=1, border=4)]
|
||||||
n = len(matrix)
|
n = len(matrix)
|
||||||
module = max(1, size // n)
|
module = max(1, size // n)
|
||||||
img = QImage(n * module, n * module, QImage.Format.Format_RGB32)
|
img = QImage(n * module, n * module, QImage.Format.Format_RGB32)
|
||||||
img.fill(QColor("white"))
|
img.fill(QColor("white"))
|
||||||
p = QPainter(img)
|
p = QPainter(img)
|
||||||
p.setPen(Qt.PenStyle.NoPen)
|
p.setPen(Qt.PenStyle.NoPen)
|
||||||
p.setBrush(QColor("black"))
|
p.setBrush(QColor("black"))
|
||||||
for y, row in enumerate(matrix):
|
for y, row in enumerate(matrix):
|
||||||
for x, dark in enumerate(row):
|
for x, dark in enumerate(row):
|
||||||
if dark:
|
if dark:
|
||||||
p.drawRect(x * module, y * module, module, module)
|
p.drawRect(x * module, y * module, module, module)
|
||||||
p.end()
|
p.end()
|
||||||
return QPixmap.fromImage(img)
|
return QPixmap.fromImage(img)
|
||||||
|
|
||||||
|
|
||||||
class MatterQrWidget(QWidget):
|
class MatterQrWidget(QWidget):
|
||||||
def __init__(self, payload: SetupPayload, size: int = 260, parent: QWidget | None = None):
|
def __init__(self, payload: SetupPayload, size: int = 260, parent: QWidget | None = None):
|
||||||
super().__init__(parent)
|
super().__init__(parent)
|
||||||
self.image = QLabel()
|
self.image = QLabel()
|
||||||
self.image.setAlignment(Qt.AlignmentFlag.AlignCenter)
|
self.image.setAlignment(Qt.AlignmentFlag.AlignCenter)
|
||||||
self.code = QLabel()
|
self.code = QLabel()
|
||||||
self.code.setAlignment(Qt.AlignmentFlag.AlignCenter)
|
self.code.setAlignment(Qt.AlignmentFlag.AlignCenter)
|
||||||
self.code.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
|
self.code.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
|
||||||
f = self.code.font()
|
f = self.code.font()
|
||||||
f.setPointSize(f.pointSize() + 4)
|
f.setPointSize(f.pointSize() + 4)
|
||||||
f.setBold(True)
|
f.setBold(True)
|
||||||
self.code.setFont(f)
|
self.code.setFont(f)
|
||||||
self.note = QLabel(wordWrap=True)
|
self.note = QLabel(wordWrap=True)
|
||||||
self.note.setAlignment(Qt.AlignmentFlag.AlignCenter)
|
self.note.setAlignment(Qt.AlignmentFlag.AlignCenter)
|
||||||
self.note.setStyleSheet("color:#555")
|
self.note.setStyleSheet("color:#555")
|
||||||
lay = QVBoxLayout(self)
|
lay = QVBoxLayout(self)
|
||||||
lay.addWidget(self.image)
|
lay.addWidget(self.image)
|
||||||
lay.addWidget(self.code)
|
lay.addWidget(self.code)
|
||||||
lay.addWidget(self.note)
|
lay.addWidget(self.note)
|
||||||
self._size = size
|
self._size = size
|
||||||
self.set_payload(payload)
|
self.set_payload(payload)
|
||||||
|
|
||||||
def set_payload(self, payload: SetupPayload) -> None:
|
def set_payload(self, payload: SetupPayload) -> None:
|
||||||
self.payload = payload
|
self.payload = payload
|
||||||
self.image.setPixmap(qr_pixmap(payload.qr_text(), self._size))
|
self.image.setPixmap(qr_pixmap(payload.qr_text(), self._size))
|
||||||
self.code.setText(f"Manual code: {payload.manual_code_pretty()}")
|
self.code.setText(f"Manual code: {payload.manual_code_pretty()}")
|
||||||
if payload.from_box:
|
if payload.from_box:
|
||||||
src = "QR and manual code exactly as reported by the box (KOTA: matter line)"
|
src = "QR and manual code exactly as reported by the box (KOTA: matter line)"
|
||||||
else:
|
else:
|
||||||
src = f"Discriminator {payload.discriminator} " + (
|
src = f"Discriminator {payload.discriminator} " + (
|
||||||
"(from this box's log)" if payload.from_log else
|
"(from this box's log)" if payload.from_log else
|
||||||
"(standard code of the v1.0 firmware - connect the box to confirm)")
|
"(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. "
|
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.")
|
f"{src}. Same as the sticker on the box.")
|
||||||
|
|
||||||
|
|
||||||
class MatterQrDialog(QDialog):
|
class MatterQrDialog(QDialog):
|
||||||
def __init__(self, payload: SetupPayload, parent: QWidget | None = None):
|
def __init__(self, payload: SetupPayload, parent: QWidget | None = None):
|
||||||
super().__init__(parent)
|
super().__init__(parent)
|
||||||
self.setWindowTitle("Matter pairing code")
|
self.setWindowTitle("Matter pairing code")
|
||||||
lay = QVBoxLayout(self)
|
lay = QVBoxLayout(self)
|
||||||
lay.addWidget(MatterQrWidget(payload, 320))
|
lay.addWidget(MatterQrWidget(payload, 320))
|
||||||
buttons = QDialogButtonBox(QDialogButtonBox.StandardButton.Close)
|
buttons = QDialogButtonBox(QDialogButtonBox.StandardButton.Close)
|
||||||
buttons.rejected.connect(self.reject)
|
buttons.rejected.connect(self.reject)
|
||||||
lay.addWidget(buttons)
|
lay.addWidget(buttons)
|
||||||
+1063
-1063
File diff suppressed because it is too large.
Load diff
+1935
-1935
File diff suppressed because it is too large.
Load diff
Reference in new issue
Block a user