"""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>
    """