# HTTP-API v1 für die WCH-App Diese Referenz beschreibt die versionierte HTTP/JSON-Schnittstelle der CH32V208-App. Die maschinenlesbare, normative Beschreibung ist [OpenAPI 3.1](http-api-v1.openapi.json). Die eigene Geräte-API bleibt immer eingeschaltet. Seit der Firmware vom 17.10.2026 ist `/api/v1` ihr einziger API-Namensraum: Unversionierte `/api/...`-Pfade sind stillgelegt und liefern 404 `not_found` im v1-Fehlerformat, ohne einen Gerätebefehl auszulösen. Der optionale [WLED-JSON-Adapter](wled-json.md) verwendet die vom WLED-Protokoll vorgegebenen `/json`-Pfade; er ist ein gesondert schaltbarer Kompatibilitätsdienst. Statische Assets (`/`, `/device.js`, …) bleiben unversioniert. Die Weboberfläche lädt `/navigation.js` vor `/device.js` beziehungsweise `/check.js`. `/device.js` bündelt Szene, Budget, Live-Steuerung, Hauptseite, MQTT, BLE, WLED, Netzwerk-DMX und Firmwareverwaltung in dieser Reihenfolge; `/check.js` bündelt Ergebnisansicht, Kurven und Einmessung. Die Quelldateien bleiben getrennt. Ausgeliefert werden nur `/`, `/logo.svg`, `/device.css`, `/navigation.js`, `/device.js`, `/check.html` und `/check.js`, jeweils gzip-komprimiert mit `Cache-Control: no-store` und Unterstützung für GET und HEAD. Frühere einzelne Script-URLs wie `/scene.js`, `/network.js` oder `/check-view.js` liefern 404; die Funktionen sind in den Bündeln enthalten. Die eingebettete Controller-Webseite verwendet ausschließlich `/api/v1`: Lichtsteuerung, Einstellungen, Diagnose/Streifencheck, Kurven, MQTT, BLE, WLED, Art-Net und sACN einschließlich STOP-/Abbruch-Beacons. Nach einem erfolgreichen Leistungs-, Temperatur- oder Kanallayout-PUT prüft sie die kompakte Ressourcenantwort und liest anschließend `GET /api/v1/status` für die vollständige Anzeige. Beide Schritte bleiben serialisiert und teilen sich die 3-s-Frist. Schlägt einer fehl, gilt der Zustand als unbestätigt; Mutationen und vorgemerkte Änderungen werden nicht automatisch wiederholt. Auch alle Prüfskripte verwenden `/api/v1`. Firmwareupdates laufen ausschließlich im Recovery-Loader über HTTP (siehe [Firmwareupdate](#firmwareupdate-über-den-recovery-loader)); das frühere UDP-Protokoll auf Port 4242 existiert nicht mehr. ## Geltung und Erreichbarkeit Die Board-API liegt unter `http:///api/v1/` auf Port 80; alternativ gilt der aktuelle eigene mDNS-Name, etwa `poe-rgb-aabbcc.local`. Der Name kann sich bei Konflikten ändern. Das Board akzeptiert als `Host` nur seine aktuelle IP oder seinen eigenen aktuellen `.local`-Namen, jeweils mit optionalem `:80`. Eine vorhandene `Origin` muss ebenfalls eine dieser HTTP-Geräteadressen sein. Origin muss bei einem direkten Client wie curl nicht mitgesendet werden. Fremde Hosts/Origins werden mit 403 abgewiesen. Diese Zulassung ist keine Benutzeranmeldung. Authentisierung, TLS, DNS-/IPv6-MQTT und MCU-Flashpersistenz sind nicht implementiert. Relative URLs verwenden die aktuelle Geräteadresse. Die API ist für das lokale Netz ausgelegt. ## HTTP, JSON und Antworten - Board: eine Anfrage je TCP-Verbindung; HTTP/1.0 oder HTTP/1.1, CRLF, keine Pipeline, kein Keepalive. Es gibt zwei gleichzeitige TCP-Plätze; SYNs bei vollen Plätzen warten in einer FIFO (höchstens vier, 4 s seit dem letzten SYN) und erhalten den nächsten frei werdenden Platz sofort, ohne auf die SYN-Wiederholung des Clients zu warten. Ein dauerhaft pollender Browser kann so keinen anderen Client aushungern. Antworten enthalten `Connection: close` und `Cache-Control: no-store`. - Die gesamte Boardanfrage einschließlich Header und Body ist auf 1024 Byte begrenzt. JSON-Bodies sind auf 128 Byte begrenzt; nur MQTT erlaubt bis 768 Byte. Whitespace zählt mit. MQTTs maximale Bodygröße hebt die gemeinsame 1024-Byte-Grenze nicht auf. Höchstens 24 eindeutige Headernamen; doppelte Header sind unzulässig. - PUT/POST benötigen genau eine dezimale `Content-Length` und den Content-Type `application/json`. Auf dem Board ist kein `; charset=...`-Zusatz erlaubt. `Transfer-Encoding`, `Content-Encoding` und `Expect` sind unzulässig. GET sendet keinen Body. - Ein Requestbody muss alle angegebenen Pflichtschlüssel enthalten; ausdrücklich optionale Schlüssel dürfen fehlen. Unbekannte/fehlende/doppelte Schlüssel, `null`, falsche Typen und Bereichsverletzungen werden abgewiesen. Ganzzahlfelder benötigen die dezimale Ganzzahlschreibweise ohne Vorzeichen, Bruchteil, Exponent oder führende Nullen. JSON-Booleans gelten nur dort, wo ausdrücklich Boolean steht, insbesondere die Protokollschalter; `auto` und `overdrive` sind Integer 0/1. - Alle hier aufgeführten Erfolge antworten mit 200 und `application/json`. Lesen und erfolgreiches Setzen einer Ressource liefern dasselbe Statusschema. 200 bestätigt die Annahme bzw. den Status zum Antwortzeitpunkt; ein gestarteter Puls, Abgleich oder Lernjob kann danach noch laufen. - Nicht aufgeführte Methoden, einschließlich HEAD auf API-Ressourcen, liefern 405; der Header `Allow` nennt die erlaubten Methoden (`GET`, `GET, PUT` oder `POST`). Wie bei HTTP üblich hat eine HEAD-Antwort keinen Body. Pfade sind exakt, ohne Queryparameter oder abschließenden Slash. Numerische Pfadteile haben keine führenden Nullen, außer dem einzelnen `0`. Ein unvollständiger Body erzeugt keine Mutation. Start-, Nullpunkt-, Eco- und MQTT-Abschaltfreigaben können intern **pending** bleiben: dieselbe Verbindung wartet auf das endgültige Ergebnis, es gibt weder HTTP 202 noch einen erneut zu sendenden Auftrag. Ein Abbruch oder Transportablauf verwirft eine noch wartende Lichtfreigabe. Globales AUS kann sie unterbrechen; andere konkurrierende Mutationen können 409 erhalten. Das ersetzt nicht die eigenständigen Laufzeitgrenzen akzeptierter Jobs. Die TCP-Grenzen sind 1 s ohne erste Requestbytes, 4 s Inaktivität und 10 s absolute Verbindungslebensdauer; sie sind keine Lease für Dauerlicht. ## Routen `D` = vollständiger `DeviceStatus`, `G` = `Diagnostics`, `P` = `PowerStatus`, `T` = `TemperatureStatus`. Alle Board-GETs lesen ohne EIN-/ACK-Auftrag und ohne Verlängerung von Lichtintention, Testfreigabe oder Jobfrist. Hintergrundregelung und Schutz laufen während des Lesens weiter. Temperaturgrenze und Kanallayout werden im AUS-Zustand gespeichert; die übrigen Einstellungen bleiben RAM-Zustand. PUT erzeugt keinen neuen EIN-/ACK-Auftrag. | v1-Pfad (unter `/api/v1`) | Methode | Exakter JSON-Body | Erfolg | |---|---|---|---| | `/status` | GET | – | D | | `/diagnostics` | GET | – | G | | `/firmware` | GET | – | `FirmwareStatus` | | `/power` | GET / PUT | PUT: `{"max_led_mw":5000}` | P | | `/temperature` | GET / PUT | PUT: `{"max_temperature_mc":50000}` | T | | `/light` | GET / PUT | PUT: `{"layout":2}` | `{"layout":2}` | | `/eco` | GET / PUT | PUT: `{"stage":3,"auto":0}` | D | | `/efficiency` | GET / PUT | PUT: `{"efficiency_permille":930}` | D | | `/mqtt` | GET / PUT | vollständige Konfiguration oder `{"enabled":false}` | `MqttStatus` | | `/ble` | GET / PUT | PUT: `{"enabled":true}` oder `{"enabled":false}` | `BleStatus` | | `/wled` | GET / PUT | PUT: exakt `{"enabled":true}` oder `{"enabled":false}` | `{"enabled":false,"ram_bytes":0}` | | `/artnet` | GET / PUT | PUT: `{"enabled":false}` oder `{"enabled":true}` mit optionalen Integern `universe`, `start_address` | `ArtNetStatus` | | `/sacn` | GET / PUT | PUT: `{"enabled":false}` oder `{"enabled":true}` mit optionalen Integern `universe`, `start_address` | `SacnStatus` | | `/scene` | POST | `{"r":0,"g":0,"b":0,"cw":200,"ww":200}`; optional zusätzlich `"transition_ms":1500` | D | | `/off` | POST | `{}` | D | | `/ack` | POST | `{}` | D | | `/recovery` | POST | `{}` | 202, `FirmwareStatus` | | `/factory-reset` | POST | `{"confirm":1}` | 202, `FirmwareStatus` | | `/learn` | GET | – | `LearnStatus` | | `/learn/begin` | POST | `{}` | `LearnStatus` | | `/learn/commit` | POST | `{"generation":1}` | `LearnStatus` | | `/learn/abort` | POST | `{"generation":1}` | `LearnStatus` | | `/learn/result/{generation}` | GET | – | `LearnProfile` | Einstellungen verwenden PUT, Aktionen POST. Die frühere Einzelzellenaktion `/api/learn/cell` existiert nicht mehr (das autonome Lernen hat sie ersetzt). Die Versionierung betrifft den API-Pfad, nicht das Profil- oder Flash-Layout. ## Gemeinsame Leistungs- und Temperaturressourcen `GET` und erfolgreicher `PUT /api/v1/power` liefern mindestens: ```json {"user_led_mw":5000,"effective_led_mw":5000,"max_led_mw":23715,"measured_led_mw":0,"measured_valid":true,"limiting":false,"faults":0} ``` Alle Leistungen sind ganzzahlige Milliwatt am **LED-Ausgang**. `user_led_mw` ist der gespeicherte Benutzer-Sollwert; `effective_led_mw` berücksichtigt die aktuelle Versorgung/Schutzgrenze und überschreitet den Sollwert nicht. `max_led_mw` in der **Antwort** ist die aktuell zulässige obere Benutzergrenze. Derselbe Schlüssel im **PUT-Body** ist der neu gewünschte Sollwert. Auf dem Board gilt 0–30000 mW als äußerer Bereich, zusätzlich die dynamische Grenze aus PoE und Effizienz. `measured_led_mw` ist `null`, wenn `measured_valid:false`; auf dem Board verlangt die Gültigkeit sowohl `adc_valid=1` als auch `mean_valid=1`. `limiting` ist Boolean und erfasst Strom-, Leistungs- oder Messbegrenzung (`limits`-Bits 0, 1, 3). `GET` und erfolgreicher `PUT /api/v1/temperature` liefern genau: ```json {"temperature_mc":30000,"temperature_valid":true,"max_temperature_mc":50000,"temperature_hysteresis_mc":5000,"faults":0} ``` Temperaturen sind Milligrad Celsius. `temperature_mc` ist ohne gültige Messung `null`; die Grenze ist 30000–80000 in Schritten von 5000 (andere Werte: 400), Standard 70000, Hysterese immer 5000. Eine geänderte Grenze wird im Flash gespeichert, sobald alle Ausgänge AUS sind und keine BLE-Verbindung besteht, und gilt nach jedem Neustart. Die Weboberfläche bietet dafür eine Auswahl 30–80 °C und erlaubt die Änderung bei ausgeschaltetem Licht auch direkt nach einer Temperaturabschaltung. Gemeint ist die interne MCU-Temperatur, kein LED-/Buck-Hotspot. `faults` ist in beiden Ressourcen die nichtnegative Ausgangsfehlerbitmaske. Die gemeinsamen Ressourcen verwenden **Booleans**, während der unveränderte volle Boardstatus die vorhandenen Integerflags 0/1 bewahrt. ## Licht, Einstellungen und Schutz Kanalwerte sind Integer 0–1000 Promille in R/G/B/CW/WW-Reihenfolge. `/scene` ersetzt den vollständigen Dauerlichtauftrag; fünf Nullen sind AUS. Ein ausdrücklich neuer von null verschiedener Szeneauftrag kann einschalten. Die Firmware regelt akzeptiertes Dauerlicht unabhängig von Browser, Reload oder Netzwerk weiter. AUS, Reset, 0-W-Budget und Schutzabschaltung löschen diesen Auftrag; Budgetanhebung oder ACK stellen ihn nicht wieder her. Ein positiver Budgetwechsel kann eine laufende Szene gemeinsam herunter- oder nach erneuter Qualifikation hochregeln. PUT ist deshalb keine Garantie eines unveränderten momentanen PWM-Vektors, aber kein neuer Lichtstart. `POST /api/v1/scene` akzeptiert zusätzlich den optionalen Integer `transition_ms` von **0 bis 60000 ms**. Ohne den Schlüssel oder bei 0 gilt die Szene sofort. Beispiel für einen Übergang über 1,5 Sekunden: ```json {"r":0,"g":0,"b":0,"cw":200,"ww":200,"transition_ms":1500} ``` Alle fünf Kanalwerte bleiben Pflicht. Die Übergangsdauer gehört zu genau diesem Szeneauftrag; ein neuer Auftrag ersetzt den bisherigen Übergang. Zulassung, Regelung und Schutzgrenzen gelten während des Übergangs unverändert. **Fünf Nullen schalten auch mit einer gültigen positiven Übergangsdauer sofort aus.** `/off`, 0-W-Budget und Schutzabschaltungen warten nie auf einen Fade. `/off` verlangt weiterhin exakt `{}`; `/pulse` unterstützt keinen `transition_ms`-Schlüssel und dauert weiterhin fest 1000 ms. Ganzzahlschreibweise, exakte Schlüsselprüfung sowie die Grenzen von 128 JSON- und 1024 Requestbytes bleiben unverändert. Aktuelle Firmware meldet im vollständigen Status die schreibgeschützte Fähigkeit `"scene_transition_max_ms":60000`. Fehlt sie, unterstützt die ältere Firmware keine HTTP-Fades; Clients senden dann ausschließlich die bisherigen fünf Kanalschlüssel. Diese additive Erweiterung bleibt unter `/api/v1`. Seit dem 19.10.2026 entfernt: der 1-s-Testpuls `/pulse` (Ausgänge schalten nur Szenen und der Streifencheck), der CW/WW-Abgleich `/calibrate` (der Streifencheck `/learn/*` misst alle Kanäle vollständiger) und der manuelle Stromnullpunkt `/adc/zero`. Den Nullpunkt misst die Firmware selbst beim Start, bei AUS aus 32 unterschiedlichen vollständigen 64-Scan-Blöcken innerhalb von 250 ms. Scheitert das, etwa wegen einer Übertemperatur beim Start, wiederholt sie die Messung im Hintergrund einmal pro Sekunde bei AUS und ohne Fehler, bis `zero_valid=1` ist; jeder externe Auftrag hat Vorrang. `zero_valid=1` bestätigt Erfolg, auch wenn `zero_raw=0`. Eco `stage` ist 0–3, `auto` Integer 0/1. Ein qualifizierter Eco-Wechsel kann Dauerlicht erhalten, beendet aber begrenzte Puls-/Kalibrier-/Lernkontexte. Eine eigene Overdrive-Einstellung gibt es nicht: Eine Leistungsgrenze (`PUT /power`) oberhalb von `compliance_led_budget_mw` wählt Overdrive, eine Grenze darauf oder darunter beendet ihn. Overdrive verlangt aktuell bestätigten Type 2 und Schutzfreigaben, sonst 400; ein Effizienzwechsel schaltet ihn nie ein. `overdrive` im Status (Integer 0/1) zeigt den Zustand. Die Effizienzannahme beträgt 100–1000 Promille, Standard 930. Die dynamische Benutzergrenze ist `floor(poe_input_limit_mw * efficiency_permille / 1000)`; typische Grenzen bei 930 sind 12043 / 23715 / 27900 mW für Type 1 / Type 2 normal / Type 2 Overdrive. Das sind Annahmen, keine PoE-Eingangsmessung oder gemessene Konformitätszusage. `/off` ist globaler STOP einschließlich wartender Starts und laufender Jobs und quittiert keine Fehler. `/ack` verlangt physisches AUS, frische gültige gesunde Messungen sowie bei Temperaturfehler die Hysterese. Abkühlen oder Erhöhen der Temperaturgrenze quittiert nicht. Watchdogfehler lassen sich nicht per ACK reaktivieren. Strom-/Spannungsdaten haben eine unabhängige 50-ms-Frist, Temperaturdaten eine Frist von weniger als 2 s; API-Polling ersetzt keine Messung und keine Sicherheitsüberwachung. Hot-/OCP-Fehler bleiben bei gesunder Sensorik diagnostizierbar. ## Vollständiger Boardstatus `GET` und erfolgreicher `PUT /api/v1/light` liefern genau `{"layout":N}`. `N` ist 0 für fünf einzelne Leuchten/Spots, 1 für RGB, 2 für RGB + CW/WW und 3 für CW/WW. Das Gerät besitzt diese Einstellung gemeinsam für Weboberfläche, MQTT/Home Assistant und den optionalen WLED-JSON-Adapter; `light_layout` im vollständigen Status gibt denselben Wert zurück. Ein Wechsel sendet keinen Lichtauftrag, verändert auch keine bereits aktive Fünfkanalszene und verlängert keine Freigabe. Die Webauswahl übernimmt einen neuen Modus erst nach bestätigtem PUT und anschließendem vollständigem Status. Geänderte Layouts werden mit Temperaturgrenze und vorhandenem Lernprofil im bisherigen Gerätejournal gespeichert, sobald alle Ausgänge AUS sind und die Funk-/Flash-Freigabe vorliegt. Bis dahin gilt das Layout im RAM; ein Neustart vor dem Speichern kann den letzten gespeicherten Wert zurückbringen. Im bisherigen PRDV-v1-Datensatz enthält das frühere reservierte UInt16-Feld bei Offset 10 nun das Layout. Alte Datensätze mit 0 bleiben gültig und laden fünf Einzelleuchten; Profile und Journalbindung bleiben erhalten. `DeviceStatus` enthält alle folgenden Felder; nur die ausdrücklich als optional beschriebene Fähigkeit `scene_transition_max_ms` darf bei älterer Firmware fehlen. Er ist eine eingefrorene Aufnahme; kooperative Hintergrundarbeit mischt keine späteren Werte hinein. Flags sind **Integer 0/1**. Ungültige physische Messungen werden `null`; rohe Diagnosewerte und Zeitstempel bleiben numerisch und benötigen ihre Gültigkeits-/Kontextfelder. Millisekundenwerte sind lokale 32-Bit-Uptime mit Überlauf, keine UTC-Zeit; Differenzen modular auswerten. | Feld | JSON-Typ / Bereich | Bedeutung | |---|---|---| | `mvp` | Integer = 1 | | | `now_ms` | Integer 0–2³²−1 | Snapshot uptime in milliseconds modulo 2^32; not UTC. | | `deadline_ms` | Integer 0–2³²−1 | Absolute pulse deadline on the same wrapping millisecond clock; zero if none. | | `pulse_active` | Integer 0/1 | A bounded pulse is active. | | `cw_requested` | Integer 0–1000 | Requested cold-white level. | | `ww_requested` | Integer 0–1000 | Requested warm-white level. | | `cw_applied` | Integer 0–1000 | Applied cold-white level. | | `ww_applied` | Integer 0–1000 | Applied warm-white level. | | `r_requested` | Integer 0–1000 | Requested red level. | | `g_requested` | Integer 0–1000 | Requested green level. | | `b_requested` | Integer 0–1000 | Requested blue level. | | `r_applied` | Integer 0–1000 | Applied red level. | | `g_applied` | Integer 0–1000 | Applied green level. | | `b_applied` | Integer 0–1000 | Applied blue level. | | `user_led_mw` | Integer 0–30000 | Stored LED-output user target in mW. | | `effective_led_mw` | Integer 0–30000 | Effective LED-output target in mW after present restrictions. | | `measured_led_mw` | Integer/null | Measured LED-output power in mW; null unless adc_valid and mean_valid are 1. | | `estimated_poe_input_mw` | Integer/null | Estimated PoE-input power in mW, rounded up from measured LED power / efficiency; null unless adc_valid and mean_valid are 1. Not an input measurement. | | `compliance_led_budget_mw` | Integer 0–30000 | Normal-mode LED-output budget in mW for detected supply and assumed efficiency; the label does not certify PoE compliance. | | `overdrive_led_budget_mw` | Integer 0–30000 | Maximum LED-output budget in mW if the current supply permits overdrive. | | `current_ma` | Integer/null | Current in mA; null unless adc_valid is 1. | | `rail_mv` | Integer/null | Measured supply rail in mV; null unless adc_valid is 1. | | `current_uncal_ma` | Integer/null | Uncorrected current in mA; null unless adc_valid is 1. | | `temperature_mc` | Integer/null | Smoothed MCU temperature in millidegrees Celsius; null unless temperature_valid is 1. | | `temperature_raw_mc` | Integer/null | Latest raw MCU temperature in millidegrees Celsius; null unless temperature_valid is 1. ACK uses raw health as well as the filtered value. | | `temperature_valid` | Integer 0/1 | Temperature data are valid. | | `ready` | Integer 0/1 | Controller feedback is ready; not by itself authorization to energize. | | `adc_valid` | Integer 0/1 | Current/rail ADC data are valid. | | `t2p` | Integer 0/1 | PoE Type-2 signal: 1 confirmed Type 2, 0 Type 1 or not confirmed; not an LLDP class. | | `avg_valid` | Integer 0/1 | Averaged measurement group is valid. | | `zero_valid` | Integer 0/1 | A complete current-zero qualification succeeded, including a valid numerical zero of 0. | | `mean_valid` | Integer 0/1 | The mean block is valid. | | `scene_active` | Integer 0/1 | Continuous scene intent is active. | | `scene_transition_max_ms` | Integer = 60000, optional | Schreibgeschützte Fähigkeit für HTTP-Szenenübergänge; aktuelle Firmware liefert 60000 ms, ältere Firmware kann das Feld weglassen. | | `overdrive` | Integer 0/1 | Overdrive selection is active. | | `auto_eco` | Integer 0/1 | Automatic Eco selection is enabled. | | `eco_settling` | Integer 0/1 | Eco transition is settling. | | `cpu_valid` | Integer 0/1 | CPU-load estimate is valid. | | `ram_stack_valid` | Integer 0/1 | Stack-use estimate is valid. | | `ram_layout_valid` | Integer 0/1 | RAM/stack layout check is valid. | | `loop_valid` | Integer 0/1 | Loop timing estimate is valid. | | `temperature_sample_ms` | Integer 0–2³²−1 | Temperature acquisition timestamp on the wrapping uptime clock, ms. | | `adc_sample_ms` | Integer 0–2³²−1 | ADC acquisition timestamp on the wrapping uptime clock, ms. | | `mean_start_ms` | Integer 0–2³²−1 | Start of the mean acquisition window on the wrapping uptime clock, ms. | | `mean_sample_ms` | Integer 0–2³²−1 | End/sample timestamp of the mean window on the wrapping uptime clock, ms. | | `max_temperature_mc` | Integer 30000–80000 in 5000er-Schritten | MCU temperature threshold in millidegrees Celsius; default 70000. | | `limits` | Integer 0–2³²−1 | Current output-limiting bitmask; see reference. | | `faults` | Integer 0–2³²−1 | Latched output-fault bitmask; see reference. | | `bsp_fault` | Integer 0–2³²−1 | Board-platform fault bitmask; zero means none. | | `max_current_ma` | Integer 0–2³²−1 | Current output-protection bound in mA. | | `protection_led_mw` | Integer 0–2³²−1 | Power output-protection bound in mW. | | `avg_current_ma` | Integer/null | Averaged current in mA; null unless adc_valid and avg_valid are 1. | | `avg_rail_mv` | Integer/null | Averaged rail in mV; null unless adc_valid and avg_valid are 1. | | `avg_led_mw` | Integer/null | Averaged LED power in mW; null unless adc_valid and avg_valid are 1. | | `mean_count` | Integer 0–2³²−1 | Number of scans represented by the averaged block, normally 64. | | `adc_i_raw` | Integer 0–4095 | Latest raw 12-bit current ADC count. | | `adc_v_raw` | Integer 0–4095 | Latest raw 12-bit rail ADC count. | | `peak_i_raw` | Integer 0–4095 | Peak raw 12-bit current ADC count. | | `zero_raw` | Integer 0–64 | Qualified current-zero raw ADC count. Validity is zero_valid, never zero_raw != 0. | | `safety_irq_lag_ms` | Integer 0–2³²−1 | Age of the independent safety interrupt in ms. | | `target_led_mw` | Integer 0–30000 | Regulator LED-output target in mW, including internal reserve. | | `max_led_budget_mw` | Integer 0–30000 | Largest presently accepted LED-output user target in mW. | | `poe_input_limit_mw` | Integer 0–30000 | Assumed PoE-input frame in mW: 12950, 25500 or 30000 depending on supply/overdrive. | | `mean_i_raw` | Integer/null | Mean raw current count; null unless adc_valid and mean_valid are 1. | | `mean_v_raw` | Integer/null | Mean raw rail count; null unless adc_valid and mean_valid are 1. | | `poe_input_estimated` | Integer = 1 | Input power is estimated, never directly measured. | | `efficiency_permille` | Integer 100–1000 | Assumed total LED-output / PoE-input efficiency in promille. | | `light_layout` | Integer 0–3 | Gemeinsames Web-/MQTT-Kanallayout: 0 Einzelleuchten, 1 RGB, 2 RGB/CCT, 3 CCT. | | `eco_stage` | Integer 0–3 | Applied Eco voltage stage. | | `eco_requested` | Integer 0–3 | Requested Eco voltage stage. | | `cpu_permille` | Integer 0–1000 | Estimated CPU load in promille; interpret only when cpu_valid is 1. | | `ram_free_bytes` | Integer 0–2³²−1 | RAM in bytes that the heap has not claimed yet (static gap minus BLE/MQTT and other allocations); a lower bound, memory freed back to the allocator is not counted. | | `ram_stack_reserve_bytes` | Integer 0–2³²−1 | Reserved stack size in bytes. | | `ram_stack_used_bytes` | Integer 0–2³²−1 | Observed stack usage in bytes; interpret only when ram_stack_valid is 1. | | `loop_mean_us` | Integer 0–2³²−1 | Mean foreground iteration time in microseconds; interpret only when loop_valid is 1. | | `loop_max_us` | Integer 0–2³²−1 | Maximum foreground iteration time in microseconds; interpret only when loop_valid is 1. | `faults`-Bits: 0 ADC, 1 Spannung, 2 Strom, 3 Leistung, 4 Hardware-OCP, 5 Plattform, 6 Übertemperatur, 7 Temperatursensor. Mehrere Bits können gleichzeitig gesetzt sein. `limits`-Bits: 0 Strom, 1 Leistung, 2 unbekannte Last, 3 Messung, 4 Einschwingen, 5 Modelldomäne, 6 empirische Softregelung. `bsp_fault` ist die gesonderte Plattformbitmaske; ihr Detailvertrag gehört zur BSP-Diagnose, nicht zu einer neuen HTTP-Steueraktion. Nicht bekannte zukünftige Bits dürfen nicht als fehlerfrei interpretiert werden. ## Laufzeitdiagnose `GET /api/v1/diagnostics` liefert `Diagnostics`, eine reine Leseaufnahme ohne Wirkung auf Ausgänge, Freigaben, Fehler oder Einstellungen. Sie ersetzt die früheren UDP-Textdiagnosen. Alle Werte sind vorzeichenlose Integer, Flags 0/1; die vollständige Feldliste steht im [OpenAPI-Vertrag](http-api-v1.openapi.json). | Gruppe | Felder | Bedeutung | |---|---|---| | Zeitmaxima seit Start | `service_max_us`, `prepare_max_us`, `transport_max_us`, `service_gap_max_us`, `status_json_max_us`, `request_max_us`, `status_gap_max_us`, `asset_request_max_us`, `irq_off_max_us`, `protection_isr_max_us`, `protection_timing_valid` | Längster Regelungsdurchlauf, Framevorbereitung, Transportdurchlauf, Abstand zweier Regelungsstarts, HTTP-Statusaufbereitung, HTTP-Anfrage, Regelungsabstand innerhalb der Statusaufbereitung, Assetanfrage, IRQ-Sperre und Schutz-ISR | | ADC-Freigabe und Mittelwert | `adc_until_ms`, `adc_scan_ms`, `mean_start_ms`, `mean_sample_ms`, `aux_sample_ms`, `mean_epoch`, `mean_valid`, `mean_pending`, `publish_attempts`, `publish_rejections`, `publish_max_us` | Messfrist, letzte Scan-/Mittelwert-/Hilfsmesszeit und Veröffentlichungsstatistik der Mittelwerte | | ADC-Versorgung der Regelung | `mean_pending_overwrites`, `mean_boundary_rejections`, `mean_radio_corrections`, `mean_wait_max_us` | Seit Start: unveröffentlicht ersetzte Kandidaten, nicht eindeutig zuordenbare DMA-Grenzereignisse und maximale Wartezeit von einer beobachteten Grenze bis zum Beginn eines Veröffentlichungsversuchs (µs, auch bei dessen Verwerfung). Bewusste PWM-/AUX-Resets und das erste verworfene Halbfenster zählen nicht als Überlastverlust. `publish_max_us` bleibt die anschließende Bearbeitungsdauer. `mean_radio_corrections` zählt Mittelwertblöcke, aus denen ein BLE-Funkburst herausgerechnet wurde: Er hebt alle ADC-Kanäle um denselben Faktor an. Nur bei aktivem BLE-Funk: Steigt die Spannung innerhalb einer eingeschwungenen Eco-Stufe um 1/256 bis 1/20 über den letzten sauberen Block, höchstens 20 ms lang, werden Spannung und Strom durch diesen Faktor geteilt. Kein Block wird verzögert oder gemittelt. | | Live-Hilfsmessung | `aux_live_count`, `aux_last_us`, `aux_max_us`, `aux_max_ocp_gap_us` | TEMP/VREFINT-Besuche unter Last; `aux_max_ocp_gap_us` ist kein Nachweis durchgängiger Stromüberwachung | | Erste Fehleraufnahme | `fault_source`, `fault_phase`, `fault_gain`, `fault_channel`, `fault_time_us`, `fault_elapsed_us`, `fault_bits`, `fault_raw`, `fault_scan_raw`, `fault_last_x1_raw`, `fault_reference_raw`, `fault_threshold_raw`, `fault_adc_flags` | Bleibt durch AUS und ACK bis zum Neustart erhalten; Codes siehe Bringup-Anleitung (Quellrepository: `firmware/bringup/README.md`) | | BLE-Stack | `ble_available`, `ble_initialized`, `ble_restart_required`, `ble_error`, `ble_startup_line`, `ble_library_code`, `ble_library_status`, `ble_snv_writes`, `ble_snv_unaligned`, `ble_snv_last_words`, `ble_snv_tail_words` | Ohne BLE-Stack im Image ist `ble_available` 0 und alle übrigen BLE-Felder 0 | | Letzte Lernablehnung | `refusal_count`, `refusal_step`, `refusal_bsp`, `refusal_at_ms`, `refusal_deadline_ms`, `refusal_feedback_ms`, `refusal_scan_ms`, `refusal_cell`, `refusal_phase`, `refusal_r`, `refusal_g`, `refusal_b`, `refusal_cw`, `refusal_ww` | Welche Prüfung während des Lernens eine Ausgabe abwies und mit welcher PWM-Anforderung | ## Firmwareupdate über den Recovery-Loader Die App installiert keine Firmware. `GET /api/v1/firmware` liefert `FirmwareStatus`: Modus (`app`), Layout-ABI 3, die Hauptversion der residenten Recovery-Services (`services`, 0 = keine), die Release-Version des laufenden Images (`version`, z. B. `0.1.0`; im Recovery-Modus die der Recovery), App-Slot, das übernommene Image laut Metadaten (Größe, CRC, Art: `app_kind` 3 eigenständig, 4 benötigt Recovery-Services Hauptversion 1), Bootgeneration, MAC und mDNS-Hostname; `update` ist in der App immer `null`. `POST /api/v1/recovery` mit `{}` schaltet alle Ausgänge AUS, fordert für den nächsten Start den Recovery-Loader an und setzt nach kurzer Antwortfrist zurück. Die Antwort `202` enthält denselben `FirmwareStatus`, damit der Browser den Hostnamen kennt; Wiederholungen verschieben die Frist nicht. Direkte Image-Routen (`/firmware/image`, `/firmware/run`) gibt es in der App nicht (404). Der Loader (48 KiB, eigenständig startfähig, auch ohne gültige App) antwortet unter derselben DHCP-Identität und demselben Hostnamen mit derselben Host-/Origin-Prüfung: | Pfad | Methode | Wirkung | |---|---|---| | `/` | GET / HEAD | Englische Update-Seite (Datei wählen, installieren, starten) | | `/api/v1/firmware` | GET | `FirmwareStatus` mit `mode` `recovery`; `app_valid` nach vollständiger CRC-Prüfung; `update` mit `id`, `phase` (`idle`, `receiving`, `ready`, `failed`), `received`, `total`, `error` | | `/api/v1/firmware/image` | PUT | Paket (`.pbu`) als `application/octet-stream`, `Content-Length` = 32 + Imagegröße, `X-Update-Id` = 16 Hexziffern | | `/api/v1/firmware/image/{offset}` | GET | Readback von höchstens 2048 Byte des App-Slots ab `offset` | | `/api/v1/firmware/run` | POST | Startet das geprüfte Image (202), danach keine weiteren Schreibaufträge in diesem Boot | | `/api/v1/firmware/abort` | POST | Bricht den laufenden Transfer mit gleicher `X-Update-Id` ab | | `/api/v1/recovery` | POST | 200; der Loader läuft bereits | Ablauf eines PUT: Der Loader prüft den 32-Byte-Paketkopf (Magic, ABI 3, Board, Art 3 oder 4, Ladeadresse, Größe, Kopf-CRC) und die Länge, bevor er die Metadatenseite löscht. Danach schreibt er jede 256-Byte-Seite, liest sie zurück und vergleicht, prüft am Ende den CRC des gesamten Images im Flash und schreibt erst dann die Metadaten. Erfolg: `200` mit `FirmwareStatus` (`phase` `ready`). Abgelehnte Pakete (`package_rejected`, `length_mismatch`) und Abbruch (`aborted`) antworten erst nach dem vollständigen Body mit `422` bzw. `409`, Schreib- oder Prüffehler mit `500`. Es gibt genau einen Schreiber: Ein zweiter PUT, auch mit derselben ID, und jede schon verwendete ID erhalten sofort `409`; der Status zeigt das Ergebnis. Bricht die Verbindung ab, endet der Transfer mit `interrupted`, das alte Image ist dann nicht mehr gültig, und ein neuer PUT mit neuer ID beginnt bei Offset null. Ein Transfer ohne Fortschritt endet nach 5 s, jeder nach spätestens 180 s. CRC ist eine Integritätsprüfung, keine Authentisierung. Werkzeug: `scripts/firmware_update.py --host 192.168.1.250 upload build/ethernet/poe-rgb-mvp.pbu --run` fordert bei Bedarf den Loader an, lädt hoch, prüft per Readback und startet. curl braucht `-H 'Expect:'`, weil das Gerät `Expect: 100-continue` ablehnt: ```sh curl --fail-with-body -X POST -H 'Content-Type: application/json' --data '{}' "$DEVICE/api/v1/recovery" curl --fail-with-body -T poe-rgb-mvp.pbu -H 'Expect:' -H 'Content-Type: application/octet-stream' \ -H "X-Update-Id: $(openssl rand -hex 8)" "$DEVICE/api/v1/firmware/image" curl --fail-with-body -X POST "$DEVICE/api/v1/firmware/run" ``` ## MQTT- und BLE-Einstellungen Ein vollständiger MQTT-PUT benötigt **alle** Schlüssel `enabled`, `broker`, `port`, `username`, `password`; lediglich `reset_password` und `telemetry_interval_s` sind optional: ```json {"enabled":true,"broker":"192.168.1.2","port":1883,"username":"led","password":"example","telemetry_interval_s":10} ``` `broker` ist eine kanonische IPv4-Adresse ohne führende Nullen; erstes Oktett 1–223 außer 127. Port ist 1–65535. Benutzername/Passwort dürfen leer sein und höchstens 32/64 **UTF-8-Bytes nach JSON-Decodierung** haben; C0-/C1-Steuerzeichen und ungepaarte Surrogate sind verboten. OpenAPI kennzeichnet die zusätzliche Bytegrenze mit `x-max-utf8-bytes`, da JSON-Schema-`maxLength` Zeichen zählt. Leeres Passwort behält ein vorhandenes Secret. `reset_password:true` löscht es, auch wenn zugleich ein nichtleeres Passwort mitgesendet wurde. Das Intervall ist 1–3600 s; ohne Angabe wird bei jeder Konfiguration 10 gesetzt, nicht der vorherige Wert übernommen. Eine Deaktivierung ist exakt `{"enabled":false}`. Fehlerhafte Konfiguration wird ohne Teiländerung abgewiesen; eine erfolgreiche Rekonfiguration kann die MQTT-Verbindung neu aufbauen. Die komplette erfolgreiche `MqttStatus`-Antwort enthält `enabled`, `connected`, `broker`, `port`, `username`, `password_set`, `telemetry_interval_s`, `hostname`, `ram_bytes`, `error`. `enabled`, `connected` und `password_set` sind Boolean; Port/Intervall/RAM sind Integer. Disabled: Broker/Benutzername leer, Port/Intervall/RAM 0. `error` ist im erfolgreichen Status leer oder `stopping`; `hostname` ist der aktuelle Name ohne `.local`. Es wird niemals das Passwort ausgegeben. GET aktiviert/allokiert nichts. Beim Abschalten werden Zugangsdaten überschrieben und der MQTT-Arbeitsbereich nach begrenztem Shutdown freigegeben; ein abgebrochener HTTP-Stream kehrt eine bereits gestartete Abschaltung nicht um. Weitere Topic-/Discovery-Semantik: [mDNS und MQTT](mdns-mqtt.md). BLE-PUT ist exakt `{"enabled":true}` oder `{"enabled":false}`. Die erstmalige Aktivierung verlangt AUS ohne aktiven Test; ein bereits aktives EIN ist wirkungslos. Die vollständige `BleStatus`-Antwort enthält Booleans `enabled`, `connected`, `initialized`, `restart_required`, Integer `ram_bytes`, den konfigurierbaren FE0F-Lampennamen (1–20 UTF-8-Byte, Standard `PoE RGB`), Integer `error` (0–255), außerdem `link_count`, `link_failures`, `disconnect_count`, `read_count`, `last_read_uuid`, `ll_event_count`, `conn_interval`, `conn_latency`, `conn_timeout` (je 0–65535), `gap_state`, `gap_opcode`, `gap_status`, `disconnect_reason`, `pair_state`, `pair_status` (je 0–255) und `tmos_ticks` (UInt32). `conn_interval` hat 1,25-ms-, `conn_timeout` 10-ms-, TMOS 0,625-ms-Einheiten; `conn_latency` zählt Intervalle. `error` enthält WCH-Status oder lokale E0–E7 als Dezimalwerte 224–231. Ein erfolgreicher GET kann den letzten Fehler weiter anzeigen. `recovering` kennzeichnet die Trennung nach einem wiederholbaren Pairing-Abbruch; `bond_dirty`, `bond_error` und `bond_generation` zeigen die unabhängig vom SDK-Ereignis verifizierte dauerhafte Speicherung. `write_count` und `last_write_uuid` ergänzen die Lesediagnose (UInt16). MQTT-/BLE-Erfolge bewahren ihre vorhandenen Statusobjekte. Nicht-2xx-v1-Antworten verwenden hingegen immer das gemeinsame Fehlerobjekt. MQTT, BLE, WLED, Art-Net und sACN starten nach Reset deaktiviert; die eigene HTTP-API und ihre mDNS-Erreichbarkeit bleiben eingeschaltet. BLE-Bonds und Gerätename besitzen ihren eigenen persistenten Speichervertrag; Abschalten kann SDK-RAM bis zum Neustart behalten. `restart_required` kennzeichnet Teilinitialisierungs-/Stack-/Kopplungsfehler. Die Hue-Kompatibilität bleibt experimentell, siehe [Hue BLE](hue-ble.md); v1 ist keine zusätzliche Hardwareabnahme. Fehlende Board-Callbacks/Hardware oder fehlgeschlagener Start können 503 liefern. `GET /api/v1/wled` und ein erfolgreicher PUT liefern genau die Booleans-/Integer-Kombination `{"enabled":false,"ram_bytes":0}` beziehungsweise bei eingeschaltetem Adapter `{"enabled":true,"ram_bytes":N}`. GET allokiert nichts. PUT verlangt exakt den einzelnen Boolean-Schlüssel `enabled`; fehlende, doppelte oder unbekannte Schlüssel und andere Typen ergeben 400 ohne Teiländerung. Wiederholtes EIN behält den bestehenden Zustand, wiederholtes AUS bleibt AUS. EIN legt den WLED-Arbeitsbereich an, AUS verwirft wartende WLED-Aufträge und gibt ihn frei; eine bereits zugelassene Szene läuft weiter. Ein Licht-STOP erfolgt über `/off`. Deaktiviert antworten `/json` und die weiteren WLED-Routen mit 404; `/api/v1` bleibt erreichbar. Dieser Schalter und der WLED-Farb-/Übergangszustand sind nicht persistent. Umfang, Routen und Kanalabbildung stehen im [WLED-Vertrag](wled-json.md). ## Art-Net- und sACN-Einstellungen `GET /api/v1/artnet` und `GET /api/v1/sacn` lesen die beiden unabhängig schaltbaren Empfänger. Erfolgreiche GETs und PUTs liefern jeweils genau: ```json {"enabled":false,"universe":0,"start_address":1,"active":false,"blocked":false,"sources":0,"packets":0,"dropped":0,"ram_bytes":0} ``` Das Beispiel zeigt Art-Net nach dem Start; für sACN ist das Standard-Universe **1**. Art-Net erlaubt Universe **0–32767**, sACN **1–63999**. `start_address` ist **1–508** und bezeichnet den ersten von fünf aufeinanderfolgenden DMX-Kanälen für die physischen Ausgänge **R/G/B/CW/WW**. Das gemeinsame RGB/CCT-Layout beeinflusst diese Zuordnung nicht. PUT verlangt den Boolean `enabled`. Abschalten ist exakt `{"enabled":false}`. Bei `enabled:true` sind `universe` und `start_address` optional; fehlende Werte behalten die aktuelle Konfiguration dieses Empfängers oder verwenden die Startwerte, wenn kein gemeinsamer Arbeitsbereich existiert. Zum Beispiel: ```json {"enabled":true,"universe":42,"start_address":11} ``` Ein gültiger `{"enabled":true}`-PUT schaltet frei beziehungsweise **rearmiert ausdrücklich nur den angesprochenen Empfänger**. Auch bei unveränderter Konfiguration werden dessen zwischengespeicherte Quellen verworfen; neue Lichtdaten benötigen ein neues DMX-Paket. GET rearmiert und allokiert nichts. Unbekannte, doppelte oder fehlende Schlüssel, falsche Typen und Bereichsverletzungen ergeben 400 ohne Teiländerung. Die 128-Byte-Bodygrenze gilt auch hier. Fehlende Board-Callbacks oder eine nicht mögliche Allokation ergeben 503. | Statusfeld | Typ / Bedeutung | |---|---| | `enabled` | Boolean: dieser Empfänger ist eingeschaltet. | | `universe`, `start_address` | Integer: bestätigte Konfiguration in den genannten Bereichen. | | `active` | Boolean: dieser Empfänger ist derzeit das ausgewählte, zulässige Eingangsprotokoll. Das bestätigt **keinen physischen Lichtausgang**: Ein empfangenes Nullbild kann aktiv sein, während Ausgangsfreigabe und Schutz einen anderen Auftrag noch ablehnen können. | | `blocked` | Boolean: dieser eingeschaltete Empfänger wurde etwa durch manuelle Steuerung, STOP, Signalverlust oder Schutz ausgesetzt. Ein ausdrücklicher `enabled:true`-PUT rearmiert ihn. | | `sources` | Integer 0–2: aktuell gespeicherte Quellen dieses Protokolls. | | `packets` | Sättigender UInt32-Zähler für am eingeschalteten Protokollport eingegangene Pakete einschließlich Erkennung und Daten. | | `dropped` | Sättigender UInt32-Zähler für fehlerhafte oder ignorierte Pakete, etwa falsches Universe, alte Sequenz, Preview, nicht unterstützten Startcode, blockierte/zu kurze Daten oder ausgeschöpften Quellenspeicher. | | `ram_bytes` | UInt32: Größe des **gemeinsamen** optionalen Art-Net/sACN-Arbeitsbereichs. Dieser Wert kann bei ausgeschaltetem Einzelempfänger positiv sein, solange der andere eingeschaltet ist. Keine zusätzlichen statischen Transportdaten und kein Allokatoraufwand enthalten. | Konfiguration und Zähler liegen ausschließlich im RAM. Nach einem Neustart sind beide Empfänger AUS. Erst wenn der letzte Empfänger abgeschaltet wird, wird der gemeinsame Arbeitsbereich freigegeben und werden beide Konfigurationen auf die Startwerte zurückgesetzt. Solange einer aktiv bleibt, behält der ausgeschaltete Empfänger sein Universe und seine Startadresse. Manuelle Lichtsteuerung, STOP und Schutz setzen laufende Streams aus. Eine Konfigurationsänderung, Rearmierung oder Abschaltung beendet gegebenenfalls das von diesem Protokoll gehaltene Licht; eine manuelle Szene bleibt erhalten. Der Empfang allein hebt keine Schutzsperre auf. Die Weboberfläche verwendet getrennte Formulare unter Diagnostics, schreibt nur bei **Apply**, bewahrt ungespeicherte Eingaben bei **Refresh status** und wiederholt fehlgeschlagene Änderungen nicht automatisch. Die eigene HTTP-API bleibt immer verfügbar. Paketformate, Quellenzusammenführung, Protokollauswahl, Erkennung und Signalverlust stehen im [Art-Net-/sACN-Vertrag](artnet-sacn.md). ## Lernen: Generationen, Ergebnisse und Fristen `/learn/begin` erzeugt bei AUS den autonomen Auftrag für vier Stufen × fünf Kanäle. Generationen sind positive 32-Bit-Ganzzahlen; 0 steht nur im Status für „keine Generation“. Stage 0–3 und Channel 0–4 entsprechen R/G/B/CW/WW. Ein veralteter oder fremder Generationsbezug und unzulässige Zustände werden abgewiesen. Die absolute Gesamtfrist beträgt **120 s**, die Zellfrist **5 s**. Browserpolling verlängert keine Frist. Der legale Prüfraum kann größer als das normale Benutzerbudget sein, aktiviert jedoch kein implizites Overdrive. Ende/Abbruch stellen das normale Benutzerbudget und die alte Eco-Einstellung bei AUS wieder her, niemals eine frühere EIN-Szene. `LearnStatus` enthält `generation`, `state`, `reason`, `completed` (0–20), `stage`, `channel`, `active_generation`, Integerflags `active_valid`/`relearn_needed`, `phase` und `point` (0–10, gemessene 10-%-Stufen der laufenden Zelle). `state`: 0 unbenutzt, 2 läuft, 3 übernommen, 4 abgebrochen, 5 vollständig gemessen (1 wird nicht verwendet). `reason`: 0 OK, 1 Stopp, 2 Schutz, 3 Budget, 4 Frist, 6 Ausgabe, 7 Spannung, 8 Kontext (5 wird nicht verwendet). `phase`: 0 keine, 1 AUS abwarten, 2 Stufe abwarten, 3 AUS-Baseline, 4 Rampe, 5 Zellen-AUS, 6 fertig; 7 ist reserviert. Das Board hält **einen** Lernbericht: Ein gestarteter Lauf ersetzt das aktive Profil sofort (`active_valid` 0), ein Abbruch hinterlässt kein aktives Profil. Ein vollständiger Lauf erfordert ausdrückliches generationsgebundenes `/commit` bei AUS; derselbe bereits übernommene Generationskontext erlaubt wiederholtes Commit. `LearnProfile` (`/learn/result/{generation}`) enthält genau `generation`, `completed` (0–20), `stage_mv` (4 Werte: Median der AUS-Railspannung je Stufe in mV, gemessen an deren erster Zelle; 0 solange ungemessen) und `current_ma` (20 Listen in der Reihenfolge Stufe × 5 + Kanal, Kanäle R/G/B/CW/WW). Jede Liste enthält die Ströme in mA bei 10 %, 20 % … 100 % PWM, jeweils als Median aus fünf Messblöcken und nie kleiner als die vorige Stufe; 0 % ist 0 mA. Nur gemessene Stufen werden gelistet: Eine kürzere Liste einer abgeschlossenen Zelle endete an einer Grenze (Testbudget oder Schutz), die Liste der laufenden Zelle wächst während der Messung. Das sind insgesamt höchstens 200 Stromwerte. Nur die Generation des einen Berichts ist lesbar; jede andere liefert 409. Der GET startet keine Messung. **Werksreset:** `POST /api/v1/factory-reset` mit genau `{"confirm":1}` schaltet alle Ausgänge AUS, beendet einen laufenden Streifencheck, stoppt BLE, speichert den Auslieferungszustand (5 W, 70 °C, 93 %, Eco 3 manuell, Spots, BLE/MQTT/WLED/Art-Net/sACN aus, kein Streifenprofil; Hue-Kopplungen bleiben) und startet neu. Die Antwort 202 enthält den `FirmwareStatus` vor dem Neustart; ein abgeschlossener Reset zeigt eine neue `boot_generation`. Lässt sich das Journal nicht schreiben, läuft das Gerät mit den alten Einstellungen weiter. Denselben Auslieferungszustand stellt die Firmware beim Start selbst her und schreibt ihn neu, wenn die gespeicherten Einstellungen ihre CRC-, Bereichs- oder Versionsprüfung nicht bestehen; der Status meldet dann `settings_reset=1`, die Weboberfläche zeigt es in der Statuszeile. Alle Einstellungen (Leistungsgrenze samt Overdrive, Effizienz, Eco, Temperaturgrenze, Kanal-Layout, BLE, MQTT samt Zugangsdaten, WLED, Art-Net, sACN) und das zuletzt festgeschriebene Streifenprofil liegen im Journal und werden beim Start wiederhergestellt. Gespeichert wird nur bei ausgeschaltetem Licht und ohne BLE-Verbindung. Nullpunkt (beim Start neu gemessen) und Laufzeitaufträge liegen im Board-RAM. ## Fehler und Wiederholungen Alle nicht erfolgreichen v1-API-Antworten haben denselben JSON-Vertrag: ```json {"error":"Geraet hat Aktion abgelehnt; Status pruefen","code":"conflict"} ``` | HTTP | Stabiler `code` | Bedeutung | |---|---|---| | 400 | `invalid_request` | Framing, JSON, Typ, Schlüssel oder Bereich ungültig | | 403 | `forbidden` | Host, Origin oder absolutes Requestziel fremd | | 404 | `not_found` | unbekannter Pfad, auch jeder unversionierte `/api/...`-Pfad | | 405 | `method_not_allowed` | Methode für diese Ressource unzulässig | | 409 | `conflict` | Zustand, Schutz, Generation oder Konkurrenz verhindert Ausführung | | 413 | `request_too_large` | Body/Gesamtanfrage zu groß | | 431 | `headers_too_large` | Headerblock füllt die Anfragegrenze vor Abschluss | | 503 | `unavailable` | Statusquelle, optionaler Dienst oder Hardwareinitialisierung nicht verfügbar | | 500 | `internal_error` | interner Fehler | `error` ist Diagnoseprosa und darf sich ändern; Clients verzweigen nach HTTP-Status und `code`. Framing-/Transportabbrüche können ohne JSON-Antwort enden; vor Erkennen eines v1-Ziels ist eine v1-Fehlerhülle nicht garantiert. HTTP-Fehlerantworten enthalten keine Zugangsdaten. GET kann bei vorübergehendem Transportfehler mit Abstand wiederholt werden. **PUT/POST nach unbekanntem Ausgang nicht automatisch wiederholen:** Neue Verbindungen besitzen keine Idempotency-Key-Deduplizierung. Ein PUT setzt zwar dieselbe Einstellung, kann aber Freigaben oder MQTT-Verbindungen neu bewerten; ein POST kann eine neue Aktion/Generation erzeugen. TCP-Retransmits derselben Verbindung sind transportseitig dedupliziert. Nach verlorener Antwort zuerst GET lesen und Zustand abgleichen; eine verbleibende Unsicherheit durch eine ausdrückliche neue Nutzerentscheidung auflösen. Globales AUS ist absichtlich wiederholbar; wiederholtes bereits aktives BLE-EIN und Commit derselben bereits übernommenen Generation haben die beschriebenen engen Idempotenzgrenzen. Keiner dieser Fälle erlaubt pauschale automatische Mutationsretries. ## curl-Beispiele Die Beispiele verwenden eine aktuelle eigene Geräteadresse. curl setzt Host und Content-Length passend; keine Retry-Option verwenden. ```sh DEVICE=http://192.168.1.250 curl --fail-with-body "$DEVICE/api/v1/status" curl --fail-with-body "$DEVICE/api/v1/power" curl --fail-with-body -X PUT -H 'Content-Type: application/json' \ --data '{"max_led_mw":5000}' "$DEVICE/api/v1/power" curl --fail-with-body -X PUT -H 'Content-Type: application/json' \ --data '{"max_temperature_mc":50000}' "$DEVICE/api/v1/temperature" curl --fail-with-body -X POST -H 'Content-Type: application/json' \ --data '{"r":0,"g":0,"b":0,"cw":200,"ww":200}' "$DEVICE/api/v1/scene" curl --fail-with-body -X POST -H 'Content-Type: application/json' \ --data '{}' "$DEVICE/api/v1/off" curl --fail-with-body -X POST -H 'Content-Type: application/json' \ --data '{}' "$DEVICE/api/v1/learn/begin" # Generation aus der erfolgreichen begin-Antwort übernehmen, nicht blind 1 annehmen: GENERATION=1 curl --fail-with-body "$DEVICE/api/v1/learn/result/$GENERATION/0/0" curl --fail-with-body -X POST -H 'Content-Type: application/json' \ --data "{\"generation\":$GENERATION}" "$DEVICE/api/v1/learn/abort" ``` ## Nachweise Die lokale Vertragsprüfung validiert echte C-HTTP-Antworten des Board-Adapters gegen die OpenAPI-Beschreibung; sie ist keine neue elektrische, MQTT-Broker-, Home-Assistant- oder Android-Hue-Abnahme. Ausführliche bestehende Boardnachweise und offene Grenzen bleiben in den verlinkten Fachreferenzen und der Bringup-Anleitung (Quellrepository: `firmware/bringup/README.md`) dokumentiert.