Documentazione API HTTP

1 / Base URL e accesso

L'API utilizza HTTP/1.1 nella rete locale ed è raggiungibile tramite http://luma.local oppure tramite l'indirizzo IP del dispositivo. Non esporre mai la porta 80 del dispositivo direttamente a Internet.

• Richieste e risposte usano JSON con Content-Type: application/json.
• Le risposte API usano Cache-Control: no-store.
• I comandi riusciti restituiscono {"ok":true}; gli errori usano uno status HTTP 4xx/5xx e, dove previsto, {"ok":false,"error":"..."}.

2 / Autenticazione locale

Quando api.auth_required è true, le route protette richiedono Authorization: Bearer . Solo le risorse di sblocco, GET /api/auth/status e POST /api/auth/login restano pubbliche.

La password locale deve avere almeno 8 caratteri; una stringa vuota la rimuove. Le sessioni interattive vivono in RAM per 12 ore e vengono revocate al cambio password o al riavvio. Dopo cinque login falliti il dispositivo restituisce 429 try_later per 30 secondi. Il verificatore persistente usa PBKDF2-HMAC-SHA256 con salt casuale e costo versionato.

Sessione interattiva

read -s LUMA_PASSWORD
LUMA_TOKEN=$(curl -fsS -H 'Content-Type: application/json' \
  -d "{\"password\":\"$LUMA_PASSWORD\"}" \
  http://luma.local/api/auth/login | jq -er .token)

curl -fsS -H "Authorization: Bearer $LUMA_TOKEN" \
  http://luma.local/api/state

Token persistente per integrazioni

Per Home Assistant, Node-RED, backend e automazioni crea una credenziale separata usando una sessione amministrativa. Conserva il campo secret in un secret store, mai nel repository.

INTEGRATION=$(curl -fsS -X POST \
  -H "Authorization: Bearer $LUMA_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"label":"Home Assistant"}' \
  http://luma.local/api/tokens)

LUMA_API_TOKEN=$(printf '%s' "$INTEGRATION" | jq -er .secret)
LUMA_TOKEN_ID=$(printf '%s' "$INTEGRATION" | jq -er .id)

3 / Stato e modello dati

• Sei canali cablati 0..5 per LED mono PWM, con misura INA219 per canale.
• Gruppi RGB/RGBW/CCT con base 0 o 3, secondo il layout.
• Strip indirizzabili S1/S2 come gruppi virtuali 6 e 7; usano alimentazione esterna e non hanno misura di potenza.
• Scene scenarios, switch a muro 1..2 e zone/sensori.

/api/state.system espone nvs_queue_overflows, nvs_queue_pending e nvs_flush_failures. Un contatore errori non nullo segnala un commit asincrono non arrivato in flash.

/api/state.inputEvents conserva in RAM gli ultimi 32 eventi SW1/SW2 in ordine, con sequence, timestamp, switchId e type. La sequenza riparte dopo il reboot e la coda non è persistente.

4 / Canali cablati 0–5

pwm:0 non equivale allo spegnimento: usa {"state":false}, così il livello precedente viene ricordato. dimming_ms è il tempo della transizione completa 0→100%, intero 0..10000; zero è immediato.

curl -fS -X POST -H "Authorization: Bearer $LUMA_TOKEN" \
  -H 'Content-Type: application/json' \
  http://luma.local/api/channel/0 -d '{"state":true,"pwm":60}'

5 / Gruppi RGB, RGBW, CCT e strip

I gruppi analogici usano base 0 o 3; le strip S1/S2 usano base 6 e 7. Nei gruppi analogici i positivi dei canali devono essere ponticellati e i ritorni PWM restano separati. La potenza mostrata è la somma degli INA e il ramo più restrittivo governa il derating del gruppo.

Per la configurazione strip, porta 0 = S1 e 1 = S2. Chip 0: WS2812/13/15/SK6812 RGB (GRB); 1: WS2811/UCS1903 RGB 800 kHz; 2: SK6812 RGBW; 3: APA102/SK9822. Il chip 3 usa S1 come data e S2 come clock, quindi esclude la seconda strip.

curl -fS -X POST -H "Authorization: Bearer $LUMA_TOKEN" \
  -H 'Content-Type: application/json' \
  http://luma.local/api/group/6 \
  -d '{"state":true,"brightness":40,"color":"#ff0000","effect":"rainbow"}'

6 / Scene e switch a muro

Le azioni scena sono {type:"channel"|"group"|"all", target, state, value, color?}. Per gli switch, channel_mask usa i bit 0–5 per i canali, 6/7 per S1/S2; zero significa tutto.

7 / Rete, zone e configurazione

/api/config/layout accetta: mono6, rgb_mono, mono_rgb, rgb2, rgbw_mono, cct_mono4, m_cct_m3, m2_cct_m2, m3_cct_m, mono4_cct, cct2_mono2, mono2_cct2, rgb_cct_m, cct_m_rgb, rgbw_cct.

8 / Energia e pricing

curl -fsS -H "Authorization: Bearer $LUMA_TOKEN" \
  http://luma.local/api/energy/history | jq '.today, .month'

curl -fS -X POST -H "Authorization: Bearer $LUMA_TOKEN" \
  -H 'Content-Type: application/json' -d '{"value":0.2845}' \
  http://luma.local/api/prefs/kwh-price

9 / Programmazioni locali

Massimo 16 programmazioni. Maschere canali 1..0x3f, giorni 1..0x7f (bit 0 = lunedì), minuti 0..1439, evento 0=fisso, 1=alba, 2=tramonto, offset solare -180..180. Payload impossibili restituiscono 422 invalid_schedule.

10 / OTA

11 / KNXnet/IP

La build corrente include il client KNXnet/IP tunnelling. Configurazione e mappature sono persistenti e tutte le route richiedono autenticazione.

Gli indirizzi di gruppo sono main/middle/sub (0..31/0..7/0..255). I segreti KNX Secure non transitano nelle risposte.

12 / MQTT

Il client MQTT configurabile è separato dal collegamento privato OBJEX Cloud. Le route richiedono autenticazione locale; password e CA non vengono mai restituite.

Campi segreti vuoti conservano il valore esistente; usa le route dedicate per cancellarli. Il trasporto mqtt richiede allowPlaintext:true. I comandi MQTT passano sempre dallo stato canonico e non aggirano le protezioni elettriche o termiche.

13 / Home Assistant

L'integrazione diretta è indipendente da MQTT: usa Zeroconf e REST HTTP nella LAN. L'inventario segue il Channel setup e presenta mono, RGB, RGBW, CCT e strip come entità logiche.

Non creare manualmente switch REST YAML. Abilita Settings → Protocols → Home Assistant, installa il componente luma e completa il pairing in Settings → Devices & services. La password viene usata una volta; il componente conserva solo il token dedicato.

14 / Limiti, errori e concorrenza

• Body ordinari: massimo 8 KB e 4 s; login: 512 B; import autenticato: 64 KB e 10 s.
• 400 JSON/tipo/URL non valido; 401 autenticazione mancante o scaduta; 404 risorsa assente; 409 conflitto; 422 configurazione impossibile; 500 persistenza fallita; 503 sottosistema non pronto.
• Import, mappa canali, scene, programmazioni e zone ripristinano lo snapshot precedente in caso di errore.
• Non inviare comandi concorrenti sullo stesso campo aspettandoti un merge: prevale l'ultimo comando valido e lo stato firmware resta la fonte di verità.

15 / Disponibilità delle funzioni

• Gli endpoint DALI /api/dali/* sono feature-gated e assenti dalla build corrente.
• KNX è abilitato. Una build che lo escluda restituisce 404 da /api/knx/* senza modificare la configurazione.
• MQTT cloud è gestito automaticamente e non espone comandi HTTP manuali. Il client MQTT pubblico usa credenziali e namespace indipendenti.
• L'API può crescere con il firmware; in caso di dubbio /api/state è lo specchio fedele delle funzioni disponibili.

16 / Operazioni distruttive

Queste operazioni possono cancellare dati, interrompere il servizio o revocare l'accesso. Esporta la configurazione e verifica il target prima di eseguirle.