# Presentazione Professionale dei Nodi KNX Ultimate

Questa guida funge da scaletta per video, webinar o formazione interna: ogni sezione riassume lo scopo del nodo, le funzioni principali, le impostazioni critiche e gli scenari d'uso più ricorrenti. Manteniamo l'elenco allineato all'effettiva distribuzione dei nodi pubblicati nel pacchetto (vedi `package.json`).

---

## knxUltimate-config
- **Obiettivo**: impostare parametri di connessione KNX/IP (host, porta, tunneling, sicurezza) e caricare il CSV ETS.
- **Funzioni principali**: gestione protocolli (UDP/TCP/Secure), caricamento ETS per autocomplete, monitor bus, diagnostica collegamento.
- **Configurazione chiave**: verificare raggiungibilità gateway, scegliere l'interfaccia, abilitare KNX Secure o ritardi tra telegrammi, importare il file gruppi.
- **Casi d'uso**: fondamento di ogni flusso KNX Ultimate, prerequisito per tutti gli altri nodi.

## hueConfig
- **Obiettivo**: collegare Node-RED alla bridge Philips Hue (REST + EventStream) e gestire token, TLS e fallback polling.
- **Funzioni principali**: pairing guidato, memorizzazione credenziali, sincronizzazione oraria, EventStream realtime.
- **Configurazione chiave**: preparare bridge aggiornata, generare token, scegliere la modalità di aggiornamento eventi.
- **Casi d'uso**: abilitare l'intera gamma di nodi Hue della suite.

---

## knxUltimate
- **Obiettivo**: nodo KNX universale per leggere/scrivere telegrammi con conversione DPT automatica.
- **Funzioni principali**: autocomplete GA, riconoscimento DPT, priorità telegrammi, filtri ETS, statistiche runtime.
- **Configurazione chiave**: selezionare gateway, scegliere DPT corretti, abilitare Node PINs se servono ingressi/uscite addizionali, impostare ACK.
- **Casi d'uso**: controllo luci, tapparelle, logiche HVAC, raccolta stati impianto.

## knxUltimateSceneController
- **Obiettivo**: orchestrare sequenze KNX multi-step con condizioni e override manuale.
- **Funzioni principali**: step programmabili, trigger condizionali, memorizzazione scene, interfaccia dashboard.
- **Configurazione chiave**: definire scene target, temporizzazioni, gestione PIN per ingressi/feedback.
- **Casi d'uso**: regia luci avanzata, scenari combinati luce/tende, interlock HVAC.

## knxUltimateWatchDog
- **Obiettivo**: sorvegliare dispositivi o GA con ping periodici e generare allarmi in caso di timeout.
- **Funzioni principali**: heartbeat, misura latenza, azioni di recovery, export verso logger/alerter.
- **Configurazione chiave**: scegliere GA da monitorare, definire soglie temporali, impostare escalation.
- **Casi d'uso**: monitor gateway KNX, sensori critici, supervisione siti remoti.

## knxUltimateLogger
- **Obiettivo**: registrare telegrammi KNX, filtrarli e condividerli con file, dashboard o servizi esterni.
- **Funzioni principali**: buffer circolare, filtri per GA/DPT, export CSV/JSON, salvataggio su context.
- **Configurazione chiave**: cartella di output, retention, soglie di notifica, formato export.
- **Casi d'uso**: audit impianto, diagnostica rapida, consegna report al cliente.

## knxUltimateGlobalContext
- **Obiettivo**: sincronizzare valori KNX nel context globale di Node-RED.
- **Funzioni principali**: binding automatico GA→context, sync bidirezionale opzionale, filtri DPT.
- **Configurazione chiave**: convenzioni di naming, direzione sincronizzazione, abilitazione PIN per aggiornamenti esterni.
- **Casi d'uso**: dashboard custom, API interne, logiche multi-flusso.

## knxUltimateAlerter
- **Obiettivo**: emettere alert quando valori KNX superano soglie o condizioni definite.
- **Funzioni principali**: comparatori multipli, isteresi, azioni su email/MQTT/log.
- **Configurazione chiave**: soglie e finestre temporali, reset automatico, wiring dei PIN.
- **Casi d'uso**: monitoraggio temperature critiche, luci dimenticate, aperture anomale.

## knxUltimateLoadControl
- **Obiettivo**: bilanciare carichi misurati dal bus e applicare logiche di shedding.
- **Funzioni principali**: soglie dinamiche, priorità carichi, ritardi di reinserimento, lettura GA potenza.
- **Configurazione chiave**: GA di misura, gruppi di carichi, tempi di shed/restore, auto restore.
- **Casi d'uso**: evitare distacchi, ottimizzare consumi, demand-response.

## knxUltimateViewer
- **Obiettivo**: dashboard HTML+JSON per visualizzare i telegrammi KNX in ascolto.
- **Funzioni principali**: tavola HTML, array JSON, queue analyzer, export.
- **Configurazione chiave**: scelta GA da visualizzare, stile tabella, periodicità refresh.
- **Casi d'uso**: collaudo impianto, control room, demo live.

## knxUltimateAutoResponder
- **Obiettivo**: rispondere automaticamente alle richieste di lettura KNX usando l'ultimo valore noto.
- **Funzioni principali**: cache valori, mapping multi-GA, supporto input esterni.
- **Configurazione chiave**: GA da ascoltare, durata cache, fallback.
- **Casi d'uso**: pannelli touch, supervisione, KNX logiche che richiedono feedback immediato.

## knxUltimateStaircase
- **Obiettivo**: temporizzare illuminazione scale con preavvisi, override e blocchi.
- **Funzioni principali**: timer multipli, pre-warning, override manuale, lettura stato iniziale.
- **Configurazione chiave**: GA di comando/stato, durata timer, pin di forzatura, opzioni reset.
- **Casi d'uso**: gestione luci scala condominiali, luci corridoio con segnalazione finale.

## knxUltimateGarage
- **Obiettivo**: controllare porte sezionali/basculanti con comandi impulsi, hold-open e sicurezza.
- **Funzioni principali**: comando impulso, stato porta, blocco, fotocellula, auto close.
- **Configurazione chiave**: GA di comando/stato/allarmi, tempi auto-chiusura, logica movimento.
- **Casi d'uso**: automazione autorimesse singole o condominiali, integrazione antifurto.

## knxUltimateIoTBridge
- **Obiettivo**: creare un bridge KNX ↔ MQTT/REST/Modbus con mapping bidirezionale.
- **Funzioni principali**: template payload, scaling valori, ack, buffer offline.
- **Configurazione chiave**: definizione mapping, protocolli target, gestione conferme.
- **Casi d'uso**: integrazione KNX con sistemi cloud/SCADA/PLC.

## knxUltimateHATranslator
- **Obiettivo**: trasformare telegrammi KNX in entità Home Assistant (e viceversa).
- **Funzioni principali**: mapping DPT→entity, discovery, normalizzazione booleani/numeri.
- **Configurazione chiave**: definire entità target, template discovery, riconciliazione stati.
- **Casi d'uso**: dashboard Home Assistant su impianti KNX senza logiche duplicate.

---

## knxUltimateHueLight
- **Obiettivo**: controllare lampade Hue (on/off, dimming, colore, Kelvin, scene dinamiche) dal bus KNX.
- **Funzioni principali**: mapping multi-GA, day/night, feedback stato, Node PIN opzionali.
- **Configurazione chiave**: GA luminosità/colore/stato, rampe, sincronizzazione EventStream.
- **Casi d'uso**: scenografie luminose, sincronizzazione pulsanti KNX ↔ Hue.

## knxUltimateHueButton
- **Obiettivo**: ricevere eventi da pulsanti Hue e mapparli su GA KNX.
- **Funzioni principali**: short/long press, multi risorsa, DPT 1.xxx/18.xxx.
- **Configurazione chiave**: resource ID, GA per evento, opzioni debounce.
- **Casi d'uso**: usare pulsanti Hue come input aggiuntivi per luci e scenari.

## knxUltimateHueMotion
- **Obiettivo**: integrare i motion sensor Hue classici.
- **Funzioni principali**: output booleano, filtri DPT 1.xx, PIN configurabili.
- **Configurazione chiave**: GA movimento/stato, timeout, comportamento in assenza.
- **Casi d'uso**: accensione luci, presenza, log sicurezza.

## knxUltimateHueTapDial
- **Obiettivo**: usare Hue Tap Dial come controller rotativo KNX.
- **Funzioni principali**: passi +/- configurabili, mapping DPT 3.007/5.001/custom, feedback.
- **Configurazione chiave**: GA target, sensibilità, esposizione PIN.
- **Casi d'uso**: dimming, regolazione volume o velocità ventilatori.

## knxUltimateHueLightSensor
- **Obiettivo**: portare i lux dei sensori Hue nel bus.
- **Funzioni principali**: conversione DPT 9.004, smoothing, read-on-start.
- **Configurazione chiave**: GA luce, filtri, range.
- **Casi d'uso**: automazioni su luminosità, controllo tende, energy management.

## knxUltimateHueTemperatureSensor
- **Obiettivo**: pubblicare temperature Hue in KNX (DPT 9.001).
- **Funzioni principali**: sincronizzazione all'avvio, offset, Node PIN opzionali.
- **Configurazione chiave**: GA temperatura, correzione, intervalli.
- **Casi d'uso**: HVAC, comfort, logging energetico.

## knxUltimateHueScene
- **Obiettivo**: richiamare scene Hue tramite KNX (modalità singola o multi scena).
- **Funzioni principali**: regole scena, mapping DPT 1.xxx/18.xxx, feedback opzionale.
- **Configurazione chiave**: GA trigger, definizione scene, loop prevenzione.
- **Casi d'uso**: automazioni giorno/notte, interfacce touch custom.

## knxUltimateHueBattery
- **Obiettivo**: esporre lo stato batteria dei dispositivi Hue.
- **Funzioni principali**: conversione device_power→DPT 5.001, lettura iniziale, alert soglia.
- **Configurazione chiave**: GA percentuale, soglie manutenzione, Node PIN.
- **Casi d'uso**: notifiche batteria bassa, manutenzione preventiva.

## knxUltimateHueZigbeeConnectivity
- **Obiettivo**: monitorare la connettività Zigbee dei dispositivi Hue.
- **Funzioni principali**: mapping booleano, lettura stato iniziale, fallback logici.
- **Configurazione chiave**: GA monitoraggio, DPT 1.001, policy disconnessione.
- **Casi d'uso**: diagnostica dispositivi offline, attivazione fallback KNX.

## knxUltimateHueCameraMotion
- **Obiettivo**: raccogliere eventi motion dalle Hue Secure Cam.
- **Funzioni principali**: EventStream in tempo reale, boolean mapping, read-on-start.
- **Configurazione chiave**: GA movimento, DPT, filtri antifalso.
- **Casi d'uso**: accensione luci, allarmi integrati, logging sicurezza.

## knxUltimateContactSensor
- **Obiettivo**: sincronizzare sensori magnetici Hue (aperto/chiuso) con KNX.
- **Funzioni principali**: filtro `contact`, mapping DPT 1.019, naming ETS.
- **Configurazione chiave**: GA stato, inversioni logiche, notifiche.
- **Casi d'uso**: supervisioni finestre/porte, logiche sicurezza e climatizzazione.

## knxUltimateHueHumiditySensor
- **Obiettivo**: inviare in KNX la % di umidità rilevata dai sensori Hue.
- **Funzioni principali**: scaling DPT 9.007, sincronizzazione iniziale, smoothing opzionale.
- **Configurazione chiave**: GA umidità, filtri, soglie.
- **Casi d'uso**: ventilazione controllata, allarmi condensa, dashboard climatici.

## knxUltimateHuePlug
- **Obiettivo**: comandare prese Hue e leggere stato/potenza.
- **Funzioni principali**: on/off, monitor power availability, feedback.
- **Configurazione chiave**: GA comando/stato/potenza, DPT, read status at startup.
- **Casi d'uso**: gestione carichi, controllo standby, monitor affidabilità.

## knxUltimateHuedevice_software_update
- **Obiettivo**: segnalare aggiornamenti firmware Hue disponibili.
- **Funzioni principali**: mapping `up_to_date/available/required`, notifiche, log.
- **Configurazione chiave**: GA di alert, soglie, sincronizzazione dashboard.
- **Casi d'uso**: pianificazione update, workflow manutenzione, compliance.

---