kkallas/kota-technician-tool
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Technician tool v0.7

Browse Source 
Imported from the Google Drive folder 004-technician_tool/v0.7.
This commit is contained in:
kkallas committed 2026-09-28 19:11:20 +02:00
1 parent 22bd853ecf
commit dd915b5a74
29 files changed
+8429 -3981
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

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