Technician tool v0.1

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

kota_tech/ui/cheatsheet.py

@@ -0,0 +1,83 @@
+"""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>: power switch 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.",
+    "Note the RGB LED colour and compare with the table below.",
+]
+
+
+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>
+    """