feat(ui): add web led-tool usb controls

Made-with: Cursor

src/controllers/led_tool.py

@@ -0,0 +1,189 @@
+import json
+import os
+import subprocess
+import sys
+
+from microdot import Microdot
+from serial.tools import list_ports
+
+controller = Microdot()
+
+
+def _repo_root() -> str:
+    return os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+
+
+def _led_cli_path() -> str:
+    return os.path.join(_repo_root(), "led-tool", "cli.py")
+
+
+def _build_led_cli_command(port: str, payload: dict):
+    cmd = [sys.executable, _led_cli_path(), "--port", port]
+
+    flag_map = (
+        ("name", "--name"),
+        ("led_pin", "--pin"),
+        ("num_leds", "--leds"),
+        ("brightness", "--brightness"),
+        ("transport", "--transport"),
+        ("ssid", "--ssid"),
+        ("password", "--wifi-password"),
+        ("wifi_channel", "--wifi-channel"),
+        ("default", "--default"),
+    )
+
+    for key, flag in flag_map:
+        value = payload.get(key)
+        if value is None:
+            continue
+        value_str = str(value).strip()
+        if value_str == "":
+            continue
+        cmd.extend([flag, value_str])
+
+    return cmd
+
+
+def _run_led_cli_command(cmd, cli_path: str, timeout_s=180):
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout_s,
+            cwd=os.path.dirname(cli_path),
+        )
+    except subprocess.TimeoutExpired:
+        return (
+            json.dumps({"error": "led-tool command timed out after 180 seconds"}),
+            504,
+            {"Content-Type": "application/json"},
+        )
+    except Exception as exc:
+        return (
+            json.dumps({"error": str(exc)}),
+            500,
+            {"Content-Type": "application/json"},
+        )
+
+    return (
+        json.dumps(
+            {
+                "ok": result.returncode == 0,
+                "returncode": result.returncode,
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+                "command": cmd,
+            }
+        ),
+        200,
+        {"Content-Type": "application/json"},
+    )
+
+
+def _extract_settings_from_stdout(stdout: str):
+    text = (stdout or "").strip()
+    if not text:
+        return None
+    try:
+        parsed = json.loads(text)
+        return parsed if isinstance(parsed, dict) else None
+    except Exception:
+        return None
+
+
+@controller.get("/ports")
+async def list_serial_ports(request):
+    ports = []
+    for info in list_ports.comports():
+        ports.append(
+            {
+                "device": info.device,
+                "description": info.description,
+                "hwid": info.hwid,
+            }
+        )
+    return (
+        json.dumps(
+            {
+                "ports": ports,
+                "led_cli_exists": os.path.exists(_led_cli_path()),
+            }
+        ),
+        200,
+        {"Content-Type": "application/json"},
+    )
+
+
+@controller.post("/settings")
+async def apply_settings(request):
+    data = request.json or {}
+    port = str(data.get("port") or "").strip()
+    if not port:
+        return (
+            json.dumps({"error": "port is required"}),
+            400,
+            {"Content-Type": "application/json"},
+        )
+
+    cli_path = _led_cli_path()
+    if not os.path.exists(cli_path):
+        return (
+            json.dumps({"error": "led-tool/cli.py not found"}),
+            500,
+            {"Content-Type": "application/json"},
+        )
+
+    cmd = _build_led_cli_command(port, data) + ["--follow"]
+    return _run_led_cli_command(cmd, cli_path, timeout_s=None)
+
+
+@controller.post("/reset")
+@controller.post("/reset/")
+async def reset_device(request):
+    data = request.json or {}
+    port = str(data.get("port") or "").strip()
+    if not port:
+        return (
+            json.dumps({"error": "port is required"}),
+            400,
+            {"Content-Type": "application/json"},
+        )
+
+    cli_path = _led_cli_path()
+    if not os.path.exists(cli_path):
+        return (
+            json.dumps({"error": "led-tool/cli.py not found"}),
+            500,
+            {"Content-Type": "application/json"},
+        )
+
+    cmd = [sys.executable, cli_path, "--port", port, "--reset", "--follow"]
+    return _run_led_cli_command(cmd, cli_path, timeout_s=None)
+
+
+@controller.get("/settings")
+async def read_settings(request):
+    port = str(request.args.get("port") or "").strip()
+    if not port:
+        return (
+            json.dumps({"error": "port is required"}),
+            400,
+            {"Content-Type": "application/json"},
+        )
+
+    cli_path = _led_cli_path()
+    if not os.path.exists(cli_path):
+        return (
+            json.dumps({"error": "led-tool/cli.py not found"}),
+            500,
+            {"Content-Type": "application/json"},
+        )
+
+    cmd = [sys.executable, cli_path, "--port", port, "--show"]
+    body, status, headers = _run_led_cli_command(cmd, cli_path)
+    if status != 200:
+        return body, status, headers
+    data = json.loads(body)
+    data["settings"] = _extract_settings_from_stdout(data.get("stdout") or "")
+    return json.dumps(data), status, headers

src/main.py

@@ -21,6 +21,7 @@ import controllers.scene as scene
 import controllers.pattern as pattern
 import controllers.settings as settings_controller
 import controllers.device as device_controller
+import controllers.led_tool as led_tool_controller
 from models.transport import get_sender, set_sender, get_current_sender
 from models.device import Device, normalize_mac
 from models import wifi_ws_clients as tcp_client_registry
@@ -273,6 +274,7 @@ async def main(port=80):
     app.mount(pattern.controller, '/patterns')
     app.mount(settings_controller.controller, '/settings')
     app.mount(device_controller.controller, '/devices')
+    app.mount(led_tool_controller.controller, '/led-tool')
 
     tcp_client_registry.set_settings(settings)
     tcp_client_registry.set_tcp_status_broadcaster(broadcast_device_tcp_status)

src/static/led_tool.js

@@ -0,0 +1,255 @@
+document.addEventListener('DOMContentLoaded', () => {
+  const openBtn = document.getElementById('led-tool-btn');
+  const modal = document.getElementById('led-tool-modal');
+  const closeBtn = document.getElementById('led-tool-close-btn');
+  const refreshPortsBtn = document.getElementById('led-tool-refresh-ports-btn');
+  const form = document.getElementById('led-tool-form');
+  const readBtn = document.getElementById('led-tool-read-btn');
+  const resetBtn = document.getElementById('led-tool-reset-btn');
+  const portSelect = document.getElementById('led-tool-port');
+  const outputEl = document.getElementById('led-tool-output');
+  const messageEl = document.getElementById('led-tool-message');
+
+  if (!openBtn || !modal || !form || !portSelect || !outputEl || !messageEl) {
+    return;
+  }
+
+  const showMessage = (text, type = 'success') => {
+    messageEl.textContent = text;
+    messageEl.className = `message ${type} show`;
+  };
+
+  const setOutput = (text) => {
+    outputEl.value = text || '';
+  };
+
+  const parseApiResponse = async (response) => {
+    const bodyText = await response.text();
+    let data = null;
+    try {
+      data = bodyText ? JSON.parse(bodyText) : {};
+    } catch (error) {
+      data = { error: bodyText || `HTTP ${response.status}` };
+    }
+    return data;
+  };
+
+  const setFieldValue = (id, value) => {
+    const el = document.getElementById(id);
+    if (!el) return;
+    if (value === undefined || value === null) return;
+    el.value = String(value);
+  };
+
+  const populateFormFromSettings = (settings) => {
+    if (!settings || typeof settings !== 'object') return false;
+    setFieldValue('led-tool-name', settings.name);
+    setFieldValue('led-tool-num-leds', settings.num_leds);
+    setFieldValue('led-tool-led-pin', settings.led_pin);
+    setFieldValue('led-tool-brightness', settings.brightness);
+    setFieldValue('led-tool-transport', settings.transport_type);
+    setFieldValue('led-tool-ssid', settings.ssid);
+    setFieldValue('led-tool-password', settings.password);
+    setFieldValue('led-tool-wifi-channel', settings.wifi_channel);
+    setFieldValue('led-tool-default', settings.default);
+    return true;
+  };
+
+  const loadPorts = async () => {
+    const defaultPort = '/dev/ttyACM0';
+    try {
+      const response = await fetch('/led-tool/ports');
+      const data = await response.json();
+      const previous = portSelect.value;
+      portSelect.innerHTML = '<option value="">Select a serial port</option>';
+
+      for (const port of data.ports || []) {
+        const option = document.createElement('option');
+        option.value = port.device;
+        option.textContent = `${port.device} - ${port.description || 'Unknown'}`;
+        portSelect.appendChild(option);
+      }
+      if (previous) {
+        portSelect.value = previous;
+      } else if ((data.ports || []).some((p) => p.device === defaultPort)) {
+        portSelect.value = defaultPort;
+      } else {
+        const fallback = document.createElement('option');
+        fallback.value = defaultPort;
+        fallback.textContent = `${defaultPort} - default`;
+        portSelect.appendChild(fallback);
+        portSelect.value = defaultPort;
+      }
+
+      if (!data.led_cli_exists) {
+        showMessage('led-tool/cli.py was not found on the host.', 'error');
+      } else if ((data.ports || []).length === 0) {
+        showMessage('No serial ports found.', 'error');
+      } else {
+        showMessage(`Found ${(data.ports || []).length} serial port(s).`, 'success');
+      }
+    } catch (error) {
+      showMessage(`Failed to read serial ports: ${error.message}`, 'error');
+    }
+  };
+
+  openBtn.addEventListener('click', () => {
+    modal.classList.add('active');
+    loadPorts();
+  });
+
+  if (closeBtn) {
+    closeBtn.addEventListener('click', () => {
+      modal.classList.remove('active');
+    });
+  }
+
+  if (refreshPortsBtn) {
+    refreshPortsBtn.addEventListener('click', () => {
+      loadPorts();
+    });
+  }
+
+  if (readBtn) {
+    readBtn.addEventListener('click', async () => {
+      const port = portSelect.value.trim();
+      if (!port) {
+        showMessage('Select a serial port first.', 'error');
+        return;
+      }
+      setOutput('Reading settings from device...');
+      showMessage('Reading settings over USB...', 'success');
+      try {
+        const response = await fetch(`/led-tool/settings?port=${encodeURIComponent(port)}`);
+        const data = await parseApiResponse(response);
+        if (!response.ok) {
+          showMessage(data.error || 'Read failed.', 'error');
+          setOutput(data.error || 'Request failed.');
+          return;
+        }
+        const output = [
+          `exit code: ${data.returncode}`,
+          '',
+          'stdout:',
+          data.stdout || '(none)',
+          '',
+          'stderr:',
+          data.stderr || '(none)',
+        ].join('\n');
+        setOutput(output);
+        if (data.ok) {
+          const populated = populateFormFromSettings(data.settings);
+          if (populated) {
+            showMessage('Settings read and fields populated.', 'success');
+          } else {
+            showMessage('Settings read successfully.', 'success');
+          }
+        } else {
+          showMessage('Read completed with errors. Check output.', 'error');
+        }
+      } catch (error) {
+        showMessage(`Request failed: ${error.message}`, 'error');
+        setOutput(error.message);
+      }
+    });
+  }
+
+  if (resetBtn) {
+    resetBtn.addEventListener('click', async () => {
+      const port = portSelect.value.trim();
+      if (!port) {
+        showMessage('Select a serial port first.', 'error');
+        return;
+      }
+      setOutput('Resetting device and following output...');
+      showMessage('Resetting device over USB...', 'success');
+      try {
+        const response = await fetch('/led-tool/reset', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ port }),
+        });
+        const data = await parseApiResponse(response);
+        if (!response.ok) {
+          showMessage(data.error || 'Reset failed.', 'error');
+          setOutput(data.error || 'Request failed.');
+          return;
+        }
+        const output = [
+          `exit code: ${data.returncode}`,
+          '',
+          'stdout:',
+          data.stdout || '(none)',
+          '',
+          'stderr:',
+          data.stderr || '(none)',
+        ].join('\n');
+        setOutput(output);
+        if (data.ok) {
+          showMessage('Device reset complete.', 'success');
+        } else {
+          showMessage('Reset completed with errors. Check output.', 'error');
+        }
+      } catch (error) {
+        showMessage(`Request failed: ${error.message}`, 'error');
+        setOutput(error.message);
+      }
+    });
+  }
+
+  form.addEventListener('submit', async (event) => {
+    event.preventDefault();
+    const port = portSelect.value.trim();
+    if (!port) {
+      showMessage('Select a serial port first.', 'error');
+      return;
+    }
+
+    const payload = {
+      port,
+      name: document.getElementById('led-tool-name')?.value?.trim() || '',
+      num_leds: document.getElementById('led-tool-num-leds')?.value?.trim() || '',
+      led_pin: document.getElementById('led-tool-led-pin')?.value?.trim() || '',
+      brightness: document.getElementById('led-tool-brightness')?.value?.trim() || '',
+      transport: document.getElementById('led-tool-transport')?.value?.trim() || '',
+      ssid: document.getElementById('led-tool-ssid')?.value?.trim() || '',
+      password: document.getElementById('led-tool-password')?.value?.trim() || '',
+      wifi_channel: document.getElementById('led-tool-wifi-channel')?.value?.trim() || '',
+      default: document.getElementById('led-tool-default')?.value?.trim() || '',
+    };
+
+    setOutput('Running led-tool command...');
+    showMessage('Running command over USB...', 'success');
+    try {
+      const response = await fetch('/led-tool/settings', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+      });
+      const data = await parseApiResponse(response);
+      if (!response.ok) {
+        showMessage(data.error || 'Command failed.', 'error');
+        setOutput(data.error || 'Request failed.');
+        return;
+      }
+      const output = [
+        `exit code: ${data.returncode}`,
+        '',
+        'stdout:',
+        data.stdout || '(none)',
+        '',
+        'stderr:',
+        data.stderr || '(none)',
+      ].join('\n');
+      setOutput(output);
+      if (data.ok) {
+        showMessage('Settings applied via USB.', 'success');
+      } else {
+        showMessage('Command completed with errors. Check output.', 'error');
+      }
+    } catch (error) {
+      showMessage(`Request failed: ${error.message}`, 'error');
+      setOutput(error.message);
+    }
+  });
+});

src/templates/index.html

@@ -22,6 +22,7 @@
                 <button class="btn btn-secondary edit-mode-only" id="patterns-btn">Patterns</button>
                 <button class="btn btn-secondary edit-mode-only" id="color-palette-btn">Colour Palette</button>
                 <button class="btn btn-secondary edit-mode-only" id="send-profile-presets-btn">Send Presets</button>
+                <button class="btn btn-secondary edit-mode-only" id="led-tool-btn">LED Tool</button>
                 <button class="btn btn-secondary" id="help-btn">Help</button>
                 <button type="button" class="btn btn-secondary ui-mode-toggle" id="ui-mode-toggle" aria-pressed="false" title="Switch preset strip mode — label is the mode you will switch to">Edit mode</button>
             </div>
@@ -36,6 +37,7 @@
                     <button type="button" class="edit-mode-only" data-target="patterns-btn">Patterns</button>
                     <button type="button" class="edit-mode-only" data-target="color-palette-btn">Colour Palette</button>
                     <button type="button" class="edit-mode-only" data-target="send-profile-presets-btn">Send Presets</button>
+                    <button type="button" class="edit-mode-only" data-target="led-tool-btn">LED Tool</button>
                     <button type="button" data-target="help-btn">Help</button>
                 </div>
             </div>
@@ -364,6 +366,13 @@
                 <li><strong>Colour Palette</strong>: build profile colours and use <strong>From Palette</strong> in preset editor to add linked colours (badge <strong>P</strong>) that update when palette colours change.</li>
             </ul>
 
+            <h3>What led-tool does</h3>
+            <ul>
+                <li><strong>USB device setup</strong>: updates <code>settings.json</code> on ESP32 drivers over serial (for example name, pin, LED count, Wi-Fi credentials).</li>
+                <li><strong>Deploy and maintenance</strong>: uploads driver files, flashes firmware, resets device, and follows serial logs.</li>
+                <li><strong>Scope</strong>: led-tool configures devices directly; this web UI controls profiles/zones/presets and sends runtime messages.</li>
+            </ul>
+
             <div class="modal-actions">
                 <button class="btn btn-secondary" id="help-close-btn">Close</button>
             </div>
@@ -438,9 +447,86 @@
         </div>
     </div>
 
+    <!-- LED Tool Modal -->
+    <div id="led-tool-modal" class="modal">
+        <div class="modal-content">
+            <h2>LED Tool (USB)</h2>
+            <p class="muted-text" style="margin-top: 0;">Configure a driver connected over USB using <code>led-tool</code>.</p>
+            <div id="led-tool-message" class="message" style="margin-bottom: 0.75rem;"></div>
+            <form id="led-tool-form">
+                <div class="form-group">
+                    <label for="led-tool-port">Serial port</label>
+                    <div class="profiles-actions" style="gap: 0.5rem;">
+                        <select id="led-tool-port" required style="flex:1;">
+                            <option value="">Select a serial port</option>
+                        </select>
+                        <button type="button" class="btn btn-secondary" id="led-tool-refresh-ports-btn">Refresh</button>
+                    </div>
+                </div>
+
+                <div class="form-group">
+                    <label for="led-tool-name">Name</label>
+                    <input type="text" id="led-tool-name" placeholder="led-abcdef123456">
+                </div>
+                <div class="profiles-actions">
+                    <div class="preset-editor-field">
+                        <label for="led-tool-num-leds">Num LEDs</label>
+                        <input type="number" id="led-tool-num-leds" min="1" max="5000" placeholder="60">
+                    </div>
+                    <div class="preset-editor-field">
+                        <label for="led-tool-led-pin">LED pin</label>
+                        <input type="number" id="led-tool-led-pin" min="0" max="48" placeholder="4">
+                    </div>
+                </div>
+                <div class="profiles-actions">
+                    <div class="preset-editor-field">
+                        <label for="led-tool-brightness">Brightness</label>
+                        <input type="number" id="led-tool-brightness" min="0" max="255" placeholder="255">
+                    </div>
+                    <div class="preset-editor-field">
+                        <label for="led-tool-wifi-channel">WiFi channel</label>
+                        <input type="number" id="led-tool-wifi-channel" min="1" max="11" placeholder="6">
+                    </div>
+                </div>
+                <div class="profiles-actions">
+                    <div class="preset-editor-field">
+                        <label for="led-tool-transport">Transport</label>
+                        <select id="led-tool-transport">
+                            <option value="">(no change)</option>
+                            <option value="espnow">espnow</option>
+                            <option value="wifi">wifi</option>
+                        </select>
+                    </div>
+                    <div class="preset-editor-field">
+                        <label for="led-tool-default">Default preset</label>
+                        <input type="text" id="led-tool-default" placeholder="on">
+                    </div>
+                </div>
+                <div class="form-group">
+                    <label for="led-tool-ssid">SSID</label>
+                    <input type="text" id="led-tool-ssid" placeholder="Your WiFi SSID">
+                </div>
+                <div class="form-group">
+                    <label for="led-tool-password">WiFi password</label>
+                    <input type="password" id="led-tool-password" placeholder="WiFi password">
+                </div>
+
+                <div class="modal-actions">
+                    <button type="button" class="btn btn-secondary" id="led-tool-read-btn">Read</button>
+                    <button type="button" class="btn btn-secondary" id="led-tool-reset-btn">Reset</button>
+                    <button type="submit" class="btn btn-primary">Apply via USB</button>
+                    <button type="button" class="btn btn-secondary" id="led-tool-close-btn">Close</button>
+                </div>
+            </form>
+            <label for="led-tool-output" style="margin-top:0.5rem; display:block;">Command output</label>
+            <textarea id="led-tool-output" rows="12" readonly style="width:100%; font-family:monospace; resize:vertical;"></textarea>
+        </div>
+    </div>
+
     <!-- Styles moved to /static/style.css -->
     <script src="/static/zones.js"></script>
     <script src="/static/help.js"></script>
+    <script src="/static/led_tool.js"></script>
     <script src="/static/color_palette.js"></script>
     <script src="/static/profiles.js"></script>
     <script src="/static/zone_palette.js"></script>