diff --git a/firmware/website/.vscode/launch.json b/firmware/website/.vscode/launch.json new file mode 100644 index 0000000..06bb30b --- /dev/null +++ b/firmware/website/.vscode/launch.json @@ -0,0 +1,23 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "type": "chrome", + "request": "launch", + "name": "Debug Svelte (Chrome)", + "url": "http://localhost:5173", + "webRoot": "${workspaceFolder}", + "sourceMaps": true, + "preLaunchTask": "npm: dev" + }, + { + "type": "msedge", + "request": "launch", + "name": "Debug Svelte (Edge)", + "url": "http://localhost:5173", + "webRoot": "${workspaceFolder}", + "sourceMaps": true, + "preLaunchTask": "npm: dev" + } + ] +} diff --git a/firmware/website/.vscode/tasks.json b/firmware/website/.vscode/tasks.json new file mode 100644 index 0000000..ddf3f6f --- /dev/null +++ b/firmware/website/.vscode/tasks.json @@ -0,0 +1,25 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "type": "npm", + "script": "dev", + "isBackground": true, + "problemMatcher": { + "owner": "typescript", + "pattern": "$tsc", + "background": { + "activeOnStart": true, + "beginsPattern": ".*VITE.*ready in.*", + "endsPattern": ".*VITE.*ready in.*" + } + }, + "presentation": { + "focus": false, + "panel": "shared", + "showReuseMessage": false, + "clear": true + } + } + ] +} diff --git a/firmware/website/GEMINI.md b/firmware/website/GEMINI.md index a6e66ff..0437d03 100644 --- a/firmware/website/GEMINI.md +++ b/firmware/website/GEMINI.md @@ -21,3 +21,19 @@ You MUST use this tool whenever writing Svelte code before sending it to the use Generates a Svelte Playground link with the provided code. After completing the code, ask the user if they want a playground link. Only call this tool after user confirmation and NEVER if code was written to files in their project. + +# Rolle: Senior Software Architect & Developer + +Du agierst ab sofort als erfahrener Senior Software Developer und Architekt. Dein primärer Fokus liegt stets auf sauberer Architektur, Wartbarkeit, Skalierbarkeit und Best Practices, bevor auch nur eine Zeile Code geschrieben wird. + +## Deine Prinzipien: +1. **Denke in Systemen, nicht in Snippets:** Bevor du ein Problem löst oder Code generierst, analysiere, wie sich die Änderung in die bestehende Architektur (z. B. SvelteKit, Backend-Services) einfügt. +2. **Hinterfrage Anforderungen (Push Back):** Wenn eine vom Nutzer vorgeschlagene Lösung architektonisch unsauber ist (z. B. "Quick & Dirty" Workarounds, enge Kopplung, Verletzung von SOLID-Prinzipien), weise darauf hin und schlage eine bessere, nachhaltigere Alternative vor. +3. **Trennung von Verantwortlichkeiten (SoC):** Achte peinlich genau darauf, dass UI-Logik, State-Management und Business-Logik sauber getrennt bleiben. +4. **Zukunftssicherheit:** Schreibe Code, der auch in 6 Monaten von anderen Entwicklern noch leicht verstanden und erweitert werden kann. +5. **Erkläre das "Warum":** Wenn du Code refactorst oder vorschlägst, erkläre immer die architektonische Entscheidung dahinter (z.B. "Ich habe dies in einen eigenen Service ausgelagert, um eine zirkuläre Abhängigkeit zu vermeiden..."). + +## Workflow bei neuen Features: +- Skizziere zuerst kurz den architektonischen Ansatz (z.B. Datenfluss, State-Management-Strategie). +- Schreibe erst danach den eigentlichen Code. +- Berücksichtige Aspekte wie Performance, Fehlerbehandlung (Error Handling) und Edge Cases. diff --git a/firmware/website/MATTER_INTEGRATION.md b/firmware/website/MATTER_INTEGRATION.md new file mode 100644 index 0000000..04eec28 --- /dev/null +++ b/firmware/website/MATTER_INTEGRATION.md @@ -0,0 +1,45 @@ +# Matter over Thread Architecture + +This document outlines the architectural decision and technical implementation strategy for integrating external end devices (e.g., display-less components like lighthouses, signals) into the System Control ecosystem. + +## 1. Architectural Decision: Why Matter over Thread? + +We have decided to use **Matter over Thread** as the standard communication protocol between the main controller (ESP) and external end devices. + +### Key Benefits +* **Standardization:** Matter provides a standardized application layer (Clusters and Endpoints). A "light" or "blinking" function is mapped to standard clusters (e.g., `OnOff Cluster`), meaning the UI and backend do not need custom JSON parsing for every new device type. +* **Ecosystem Compatibility (Multi-Admin):** Matter's Multi-Admin feature allows a single end device to be controlled by multiple controllers simultaneously. This means a device can be paired to the ESP's web UI **and** directly to Apple Home or Google Home at the same time. +* **Robust Infrastructure:** Thread provides a self-healing IPv6 mesh network. The ESP acts as the Thread Border Router and Matter Commissioner. + +## 2. System Roles + +### Main Controller (ESP) +1. **Thread Border Router / Commissioner:** The ESP creates and manages the Thread network. It exposes a "Permit Join" window (accessible via the Web UI) to allow new, display-less devices to join the network. +2. **Matter Controller:** The ESP acts as a Matter Controller. Once a device is on the Thread network, the ESP discovers its capabilities (Clusters) and exposes them to the Web UI for configuration and control. + +### End Devices (e.g., Lighthouse) +* Act as standard **Matter Accessories**. +* Join the Thread network during the "Permit Join" window using their setup code (PSKd). +* Expose their capabilities as standard Matter endpoints (e.g., Endpoint 1: Light, Endpoint 2: Blinking feature). + +## 3. UI Workflow + +The web interface separates network infrastructure from application control: + +1. **System Tab (Infrastructure):** Used to open the Thread network ("Pair Devices" / Permit Join) so that new devices can receive an IP address and join the mesh. +2. **Configuration Tab -> Devices (Discovery):** Used to discover Matter devices that have joined the network, authenticate them via their Setup PIN, and map them to the system database. +3. **Control Tab (Application):** Dynamically displays controls (buttons, toggles) based on the discovered Matter clusters of the paired devices. + +## 4. Development and Certification Notes (DIY / Hobby) + +For private, DIY, and development purposes, **no official CSA (Connectivity Standards Alliance) certification is required.** + +We utilize **Test Vendor IDs (VID)** (e.g., `0xFFF1`) and **Test Product IDs (PID)**. + +### Ecosystem Behavior with Test Certificates +* **Apple Home (iOS):** Apple allows pairing of uncertified Matter accessories. During the pairing process, iOS will display a warning ("This accessory is uncertified"). The user can simply click **"Add anyway"** to bypass this and use the device normally. +* **Google Home:** Google requires explicit permission to add uncertified devices. Developers must log into the free **Google Home Developer Console** and register their Test VID and PID. Once registered, the Google Home app on the developer's smartphone will allow pairing without errors. +* **Our ESP Controller:** The ESP Matter SDK will be configured to accept test certificates during the Attestation phase (PASE/CASE), ensuring seamless pairing without warnings. + +--- +*Documented to ensure a shared understanding of the IoT communication strategy within the project team.* diff --git a/firmware/website/src/components/systemTab/systemTab.svelte b/firmware/website/src/components/systemTab/systemTab.svelte new file mode 100644 index 0000000..1a05b05 --- /dev/null +++ b/firmware/website/src/components/systemTab/systemTab.svelte @@ -0,0 +1,7 @@ + + +
+ +
diff --git a/firmware/website/src/components/systemTab/threadProvisioning.svelte b/firmware/website/src/components/systemTab/threadProvisioning.svelte new file mode 100644 index 0000000..2888732 --- /dev/null +++ b/firmware/website/src/components/systemTab/threadProvisioning.svelte @@ -0,0 +1,66 @@ + + + +

+ {$t('thread.desc')} +

+ + + {#if $threadStore.networkInfo} +
+
+ Status: + + {$t(`thread.status.${$threadStore.networkInfo.status}`)} + +
+
+ {$t('thread.network')} + {$threadStore.networkInfo.networkName} +
+
+ {$t('thread.panId')} + {$threadStore.networkInfo.panId} +
+
+ {$t('thread.channel')} + {$threadStore.networkInfo.channel} +
+
+ + +
+
+ {:else} +
+ {$t('thread.noNetwork')} +
+ {/if} + diff --git a/firmware/website/src/i18n/de.json b/firmware/website/src/i18n/de.json index c46c869..56dcd1c 100644 --- a/firmware/website/src/i18n/de.json +++ b/firmware/website/src/i18n/de.json @@ -22,6 +22,9 @@ "devices": "🔗 Geräte", "scenes": "🎬 Szenen" } + }, + "system": { + "title": "🔧 System" } }, "wled": { @@ -204,6 +207,21 @@ "secure": "Gesichert", "open": "Offen" }, + "thread": { + "title": "Thread Netzwerk", + "desc": "Dieses Gerät ist der Thread-Master. Öffne das Netzwerk, um neue Geräte ohne Display anzulernen.", + "network": "Netzwerk:", + "channel": "Kanal:", + "panId": "PAN ID:", + "status": { + "active": "Aktiv", + "offline": "Offline" + }, + "permitJoin": "Geräte anlernen", + "permitJoinActive": "Anlernen aktiv ({time}s)", + "joinedCount": "{count} Gerät(e) erfolgreich verbunden", + "noNetwork": "Kein aktives Thread-Netzwerk gefunden." + }, "modal": { "color": { "title": "Farbe wählen" diff --git a/firmware/website/src/i18n/en.json b/firmware/website/src/i18n/en.json index 92af107..47730d0 100644 --- a/firmware/website/src/i18n/en.json +++ b/firmware/website/src/i18n/en.json @@ -22,6 +22,9 @@ "devices": "🔗 Devices", "scenes": "🎬 Scenes" } + }, + "system": { + "title": "🔧 System" } }, "wled": { @@ -204,6 +207,21 @@ "secure": "Secured", "open": "Open" }, + "thread": { + "title": "Thread Network", + "desc": "This device is the Thread Master. Open the network to pair new display-less devices.", + "network": "Network:", + "channel": "Channel:", + "panId": "PAN ID:", + "status": { + "active": "Active", + "offline": "Offline" + }, + "permitJoin": "Pair Devices", + "permitJoinActive": "Pairing active ({time}s)", + "joinedCount": "{count} device(s) successfully paired", + "noNetwork": "No active Thread network found." + }, "modal": { "color": { "title": "Choose Color" diff --git a/firmware/website/src/routes/index.svelte b/firmware/website/src/routes/index.svelte index aabfd6a..3698d7e 100644 --- a/firmware/website/src/routes/index.svelte +++ b/firmware/website/src/routes/index.svelte @@ -5,18 +5,22 @@ import { controlStore } from "../stores/controlStore"; import ControlTab from "../components/controlTab/controlTab.svelte"; import ConfigTab from "../components/configTab/configTab.svelte"; + import SystemTab from "../components/systemTab/systemTab.svelte"; import TabButton from "../components/common/tabButton.svelte"; import TabBar from "../components/common/tabBar.svelte"; - type Tab = "control" | "config"; + type Tab = "control" | "config" | "system"; const tabToPath: Record = { control: "/control", - config: "/config" + config: "/config", + system: "/system" }; function pathToTab(path: string): Tab { - return path === "/config" ? "config" : "control"; + if (path === "/config") return "config"; + if (path === "/system") return "system"; + return "control"; } let activeTab = $derived(pathToTab($location)); @@ -46,12 +50,19 @@ label={$t("tab.config.title")} onClick={() => setTab("config")} /> + setTab("system")} + />
{#if activeTab === "control"} - {:else} + {:else if activeTab === "config"} + {:else} + {/if}
diff --git a/firmware/website/src/stores/threadStore.ts b/firmware/website/src/stores/threadStore.ts new file mode 100644 index 0000000..e66b791 --- /dev/null +++ b/firmware/website/src/stores/threadStore.ts @@ -0,0 +1,188 @@ +import { writable } from 'svelte/store'; +import { createLogger } from '../utils/logger'; +import { requestJson, resolveHost } from '../utils/apiClient'; + +export interface ThreadNetworkInfo { + networkName: string; + panId: string; + channel: number; + status: 'offline' | 'active'; +} + +export interface ThreadState { + networkInfo?: ThreadNetworkInfo; + isPermitJoinActive: boolean; + permitJoinTimeLeft: number; + joinedDevicesCount: number; +} + +const DEFAULT_THREAD_STATE: ThreadState = { + isPermitJoinActive: false, + permitJoinTimeLeft: 0, + joinedDevicesCount: 0 +}; + +const STATUS_ENDPOINT = '/api/thread/status'; +const PERMIT_JOIN_ENDPOINT = '/api/thread/permit-join'; +const WS_ENDPOINT = '/ws'; +const WS_RECONNECT_DELAY_MS = 3000; + +const isBrowser = typeof window !== 'undefined'; + +const buildWebSocketUrl = (host: string) => { + if (!isBrowser) return ''; + const wsProtocol = window.location.protocol === 'https:' && !import.meta.env.DEV ? 'wss:' : 'ws:'; + return `${wsProtocol}//${host}${WS_ENDPOINT}`; +}; + +const parseJson = (raw: string): any => { + try { + return JSON.parse(raw); + } catch { + return null; + } +}; + +const createThreadStore = () => { + const log = createLogger('threadStore'); + const store = writable({ ...DEFAULT_THREAD_STATE }); + const { subscribe: internalSubscribe, set, update } = store; + + const host = resolveHost(); + const wsUrl = buildWebSocketUrl(host); + + let ws: WebSocket | null = null; + let wsReconnectTimer: ReturnType | null = null; + let shouldReconnect = true; + let subscriberCount = 0; + + const applyState = (nextState: Partial) => { + update(current => ({ ...current, ...nextState })); + }; + + const clearReconnectTimer = () => { + if (!wsReconnectTimer) return; + clearTimeout(wsReconnectTimer); + wsReconnectTimer = null; + }; + + const scheduleReconnect = () => { + if (!shouldReconnect || wsReconnectTimer) return; + log.info('Scheduling WebSocket reconnect', { delayMs: WS_RECONNECT_DELAY_MS }); + wsReconnectTimer = setTimeout(() => { + wsReconnectTimer = null; + connectWebSocket(); + }, WS_RECONNECT_DELAY_MS); + }; + + async function fetchState() { + try { + const data = await requestJson>(STATUS_ENDPOINT); + applyState(data); + } catch (error) { + log.error('Failed to fetch initial thread state', error); + } + } + + async function startPermitJoin(durationSeconds: number = 60) { + try { + // Optimistic UI update + applyState({ + isPermitJoinActive: true, + permitJoinTimeLeft: durationSeconds, + joinedDevicesCount: 0 + }); + + await requestJson(PERMIT_JOIN_ENDPOINT, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ duration: durationSeconds }) + }); + } catch (error) { + log.error('Failed to start permit join', error); + applyState({ isPermitJoinActive: false, permitJoinTimeLeft: 0 }); + } + } + + function connectWebSocket() { + if (!isBrowser || ws || !wsUrl) return; + log.info('Connecting WebSocket', { url: wsUrl }); + + const socket = new WebSocket(wsUrl); + ws = socket; + + socket.onopen = () => { + clearReconnectTimer(); + log.info('WebSocket connected'); + }; + + socket.onmessage = (event) => { + const message = parseJson(event.data); + if (!message || !message.type) return; + + if (message.type === 'thread_permit_join_status') { + log.debug('Received permit join status'); + applyState({ + isPermitJoinActive: message.active, + permitJoinTimeLeft: message.timeLeft || 0 + }); + } else if (message.type === 'thread_device_joined') { + log.debug('A new device joined the Thread network!'); + update(state => ({ + ...state, + joinedDevicesCount: state.joinedDevicesCount + 1 + })); + } else if (message.type === 'thread_network_status') { + log.debug('Received thread network status update'); + applyState({ networkInfo: message.networkInfo }); + } + }; + + socket.onclose = () => { + if (ws === socket) ws = null; + log.warn('WebSocket closed'); + scheduleReconnect(); + }; + + socket.onerror = () => { + log.error('WebSocket error'); + socket.close(); + }; + } + + function disconnectWebSocket() { + shouldReconnect = false; + clearReconnectTimer(); + ws?.close(); + ws = null; + } + + const subscribe: typeof store.subscribe = (run, invalidate) => { + subscriberCount += 1; + if (subscriberCount === 1) { + log.debug('First subscriber attached - starting WebSocket'); + shouldReconnect = true; + connectWebSocket(); + fetchState(); + } + + const unsubscribe = internalSubscribe(run, invalidate); + + return () => { + unsubscribe(); + subscriberCount -= 1; + if (subscriberCount === 0) { + log.debug('Last subscriber removed - stopping WebSocket'); + disconnectWebSocket(); + } + }; + }; + + return { + subscribe, + fetchState, + startPermitJoin + }; +}; + +export const threadStore = createThreadStore();