homebridge-plugin-klares4 1.1.7-beta1

package/config.schema.json

@@ -0,0 +1,801 @@
+{
+    "pluginAlias": "Lares4Complete",
+    "pluginType": "platform",
+    "singular": true,
+    "customUi": false,
+    "headerDisplay": "<div class='text-center mb-3'><h3>klares4 - Ksenia Lares4 per Homebridge</h3><p class='text-muted'>Integrazione professionale per sistemi di sicurezza Ksenia Lares 4.0</p></div><div class='alert alert-info'><strong>Prima di iniziare, verifica che:</strong><ul class='mb-0 mt-2'><li>La centrale Lares4 sia raggiungibile in rete locale</li><li>L'accesso WebSocket sia abilitato sulla centrale</li><li>Tu disponga di un PIN utente</li></ul></div>",
+    "footerDisplay": "<div class='text-center mt-4 pt-3 border-top'><p class='text-muted mb-2'>Versione 1.1.6 • Sviluppato da Paolo Trivisonno</p><a href='https://github.com/paolo-trivi/homebridge-plugin-klares4' target='_blank' class='btn btn-sm btn-outline-primary mr-2'>Documentazione</a> <a href='https://github.com/paolo-trivi/homebridge-plugin-klares4/issues' target='_blank' class='btn btn-sm btn-outline-secondary mr-2'>Segnala Bug</a> <a href='https://github.com/sponsors/paolo-trivi' target='_blank' class='btn btn-sm btn-outline-success'>Supporta</a></div>",
+    "schema": {
+        "type": "object",
+        "properties": {
+            "name": {
+                "title": "Nome Piattaforma",
+                "type": "string",
+                "default": "Lares4",
+                "description": "Nome identificativo che apparirà nei log di Homebridge",
+                "minLength": 1,
+                "maxLength": 50
+            },
+            "ip": {
+                "title": "Indirizzo IP Centrale",
+                "type": "string",
+                "format": "ipv4",
+                "placeholder": "192.168.1.x",
+                "description": "Indirizzo IP locale della centrale Ksenia Lares4",
+                "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
+            },
+            "port": {
+                "title": "Porta WebSocket",
+                "type": "integer",
+                "default": 443,
+                "minimum": 1,
+                "maximum": 65535,
+                "description": "Porta di comunicazione (443 per HTTPS, 80 per HTTP)"
+            },
+            "https": {
+                "title": "Connessione Sicura (HTTPS)",
+                "type": "boolean",
+                "default": true,
+                "description": "Usa connessione crittografata - raccomandata per la sicurezza"
+            },
+            "sender": {
+                "title": "Identificativo Client",
+                "type": "string",
+                "default": "homebridge",
+                "placeholder": "homebridge",
+                "description": "Nome univoco per identificare questa connessione sulla centrale",
+                "pattern": "^[a-zA-Z0-9_-]+$",
+                "minLength": 1,
+                "maxLength": 32
+            },
+            "pin": {
+                "title": "PIN di Accesso",
+                "type": "string",
+                "placeholder": "123456",
+                "description": "PIN utente abilitato all'uso delle API WebSocket sulla centrale",
+                "pattern": "^[0-9]+$",
+                "minLength": 4,
+                "maxLength": 8
+            },
+            "showAdvanced": {
+                "title": "Mostra Configurazione Avanzata",
+                "type": "boolean",
+                "default": false,
+                "description": "Abilita per personalizzare timing, heartbeat e parametri di rete"
+            },
+            "debug": {
+                "title": "Modalita Debug (Legacy)",
+                "type": "boolean",
+                "default": false,
+                "description": "Deprecated: usa logLevel invece. Attiva logging dettagliato"
+            },
+            "logLevel": {
+                "title": "Livello Log",
+                "type": "integer",
+                "default": 1,
+                "oneOf": [
+                    {
+                        "title": "0 - Minimal (solo errori e allarmi)",
+                        "const": 0
+                    },
+                    {
+                        "title": "1 - Normal (funzionamento standard)",
+                        "const": 1
+                    },
+                    {
+                        "title": "2 - Debug (dettagliato per diagnostica)",
+                        "const": 2
+                    }
+                ],
+                "description": "Controlla la quantita di messaggi nei log"
+            },
+            "maxSeconds": {
+                "title": "Tempo Massimo Movimento Tapparelle",
+                "type": "integer",
+                "default": 30,
+                "minimum": 5,
+                "maximum": 300,
+                "description": "Secondi necessari per apertura/chiusura completa delle tapparelle"
+            },
+            "reconnectInterval": {
+                "title": "Intervallo Base Riconnessione",
+                "type": "integer",
+                "default": 5000,
+                "minimum": 1000,
+                "maximum": 60000,
+                "description": "Millisecondi prima del primo tentativo di riconnessione (raddoppia ad ogni tentativo)"
+            },
+            "heartbeatInterval": {
+                "title": "Intervallo Heartbeat",
+                "type": "integer",
+                "default": 30000,
+                "minimum": 10000,
+                "maximum": 300000,
+                "description": "Millisecondi tra i ping di keep-alive per verificare la connessione"
+            },
+            "coverStepSize": {
+                "title": "Step Animazione Tapparelle",
+                "type": "integer",
+                "default": 5,
+                "minimum": 1,
+                "maximum": 20,
+                "description": "Percentuale di movimento per ogni step di animazione in HomeKit"
+            },
+            "scenarioAutoOffDelay": {
+                "title": "Ritardo Auto-Off Scenari",
+                "type": "integer",
+                "default": 500,
+                "minimum": 100,
+                "maximum": 5000,
+                "description": "Millisecondi prima che uno scenario torni automaticamente a OFF"
+            },
+            "devicesSummaryDelay": {
+                "title": "Ritardo Sommario Dispositivi",
+                "type": "integer",
+                "default": 2000,
+                "minimum": 500,
+                "maximum": 10000,
+                "description": "Millisecondi di attesa prima di stampare il sommario dispositivi nei log"
+            },
+            "excludeZones": {
+                "title": "Zone da Escludere",
+                "type": "array",
+                "items": {
+                    "type": "string",
+                    "pattern": "^[0-9]+$"
+                },
+                "default": []
+            },
+            "excludeOutputs": {
+                "title": "Output da Escludere",
+                "type": "array",
+                "items": {
+                    "type": "string",
+                    "pattern": "^[0-9]+$"
+                },
+                "default": []
+            },
+            "excludeSensors": {
+                "title": "Sensori da Escludere",
+                "type": "array",
+                "items": {
+                    "type": "string",
+                    "pattern": "^[0-9]+$"
+                },
+                "default": []
+            },
+            "excludeScenarios": {
+                "title": "Scenari da Escludere",
+                "type": "array",
+                "items": {
+                    "type": "string",
+                    "pattern": "^[0-9]+$"
+                },
+                "default": []
+            },
+            "customNames": {
+                "type": "object",
+                "properties": {
+                    "zones": {
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "string"
+                        }
+                    },
+                    "outputs": {
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "string"
+                        }
+                    },
+                    "sensors": {
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "string"
+                        }
+                    },
+                    "scenarios": {
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "string"
+                        }
+                    }
+                }
+            },
+            "temperatureDefaults": {
+                "type": "object",
+                "properties": {
+                    "target": {
+                        "title": "Temperatura Target Default",
+                        "type": "number",
+                        "default": 21,
+                        "minimum": 5,
+                        "maximum": 35
+                    },
+                    "min": {
+                        "title": "Temperatura Minima",
+                        "type": "number",
+                        "default": 10,
+                        "minimum": 5,
+                        "maximum": 20
+                    },
+                    "max": {
+                        "title": "Temperatura Massima",
+                        "type": "number",
+                        "default": 38,
+                        "minimum": 25,
+                        "maximum": 40
+                    },
+                    "step": {
+                        "title": "Step Regolazione",
+                        "type": "number",
+                        "default": 0.5,
+                        "enum": [
+                            0.5,
+                            1
+                        ]
+                    }
+                }
+            },
+            "mqtt": {
+                "type": "object",
+                "properties": {
+                    "enabled": {
+                        "title": "Abilita Bridge MQTT",
+                        "type": "boolean",
+                        "default": false,
+                        "description": "Pubblica stati e riceve comandi via MQTT"
+                    },
+                    "broker": {
+                        "title": "URL Broker MQTT",
+                        "type": "string",
+                        "placeholder": "mqtt://192.168.1.x:1883",
+                        "description": "Indirizzo completo del broker (es: mqtt://host:1883 o mqtts://host:8883)"
+                    },
+                    "username": {
+                        "title": "Username",
+                        "type": "string",
+                        "placeholder": "mqtt_user",
+                        "description": "Credenziali di accesso al broker (opzionale)"
+                    },
+                    "password": {
+                        "title": "Password",
+                        "type": "string",
+                        "placeholder": "password",
+                        "description": "Password per l'autenticazione MQTT"
+                    },
+                    "clientId": {
+                        "title": "Client ID",
+                        "type": "string",
+                        "default": "homebridge-klares4",
+                        "placeholder": "homebridge-klares4",
+                        "description": "Identificativo univoco per il broker MQTT"
+                    },
+                    "topicPrefix": {
+                        "title": "Prefisso Topic",
+                        "type": "string",
+                        "default": "homebridge/klares4",
+                        "placeholder": "homebridge/klares4",
+                        "description": "Prefisso per tutti i topic pubblicati"
+                    },
+                    "qos": {
+                        "title": "Quality of Service",
+                        "type": "integer",
+                        "default": 1,
+                        "oneOf": [
+                            {
+                                "title": "0 - At most once (fastest)",
+                                "const": 0
+                            },
+                            {
+                                "title": "1 - At least once (recommended)",
+                                "const": 1
+                            },
+                            {
+                                "title": "2 - Exactly once (slowest)",
+                                "const": 2
+                            }
+                        ],
+                        "description": "Livello di garanzia consegna messaggi"
+                    },
+                    "retain": {
+                        "title": "Retain Messages",
+                        "type": "boolean",
+                        "default": true,
+                        "description": "Il broker memorizza l'ultimo stato per i nuovi subscriber"
+                    }
+                }
+            },
+            "roomMapping": {
+                "type": "object",
+                "properties": {
+                    "enabled": {
+                        "title": "Abilita Mappatura Stanze",
+                        "type": "boolean",
+                        "default": false,
+                        "description": "Organizza i topic MQTT per stanza invece che per tipo dispositivo"
+                    },
+                    "rooms": {
+                        "title": "Stanze",
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "roomName": {
+                                    "title": "Nome Stanza",
+                                    "type": "string",
+                                    "placeholder": "soggiorno",
+                                    "pattern": "^[a-z0-9_]+$",
+                                    "description": "Usare solo lettere minuscole, numeri e underscore"
+                                },
+                                "devices": {
+                                    "title": "Dispositivi",
+                                    "type": "array",
+                                    "items": {
+                                        "type": "object",
+                                        "properties": {
+                                            "deviceId": {
+                                                "title": "ID Dispositivo",
+                                                "type": "string",
+                                                "pattern": "^(light_|cover_|sensor_temp_|sensor_hum_|sensor_light_|zone_|thermostat_|scenario_)[0-9]+$"
+                                            },
+                                            "deviceName": {
+                                                "title": "Nome Dispositivo",
+                                                "type": "string",
+                                                "readOnly": true
+                                            }
+                                        },
+                                        "required": [
+                                            "deviceId"
+                                        ]
+                                    }
+                                }
+                            },
+                            "required": [
+                                "roomName"
+                            ]
+                        }
+                    }
+                }
+            },
+            "generateDebugFile": {
+                "title": "Genera File Debug",
+                "type": "boolean",
+                "default": false,
+                "description": "Attiva per generare un file di diagnostica completo al prossimo riavvio (si disabilita automaticamente dopo la generazione)"
+            }
+        },
+        "required": [
+            "ip",
+            "pin"
+        ]
+    },
+    "layout": [
+        {
+            "type": "section",
+            "title": "Connessione & Autenticazione",
+            "expandable": true,
+            "expanded": true,
+            "items": [
+                {
+                    "type": "help",
+                    "helpvalue": "<div class='alert alert-success'><strong>Configurazione Essenziale</strong><p class='mb-0'>Inserisci i dati di connessione alla tua centrale Ksenia Lares4. Puoi trovare l'IP nella configurazione di rete della centrale.</p></div>"
+                },
+                {
+                    "key": "ip",
+                    "type": "string",
+                    "title": "Indirizzo IP Centrale",
+                    "placeholder": "192.168.1.x",
+                    "validationMessage": "Inserisci un indirizzo IP valido (es: 192.168.1.100)"
+                },
+                {
+                    "type": "flex",
+                    "flex-flow": "row wrap",
+                    "items": [
+                        {
+                            "key": "port",
+                            "flex": "1 1 120px"
+                        },
+                        {
+                            "key": "https",
+                            "flex": "1 1 180px"
+                        }
+                    ]
+                },
+                {
+                    "key": "pin",
+                    "type": "password",
+                    "title": "PIN di Accesso",
+                    "placeholder": "Solo numeri (4-8 cifre)",
+                    "validationMessage": "Il PIN deve contenere solo numeri (4-8 cifre)"
+                },
+                {
+                    "type": "flex",
+                    "flex-flow": "row wrap",
+                    "items": [
+                        {
+                            "key": "sender",
+                            "flex": "1 1 200px"
+                        },
+                        {
+                            "key": "name",
+                            "flex": "1 1 200px"
+                        }
+                    ]
+                }
+            ]
+        },
+        {
+            "type": "section",
+            "title": "Preferenze Dispositivi",
+            "expandable": true,
+            "expanded": false,
+            "items": [
+                {
+                    "type": "help",
+                    "helpvalue": "<div class='alert alert-info'><strong>Personalizza il Comportamento</strong><p class='mb-0'>Configura i parametri di funzionamento per tapparelle, termostati e scenari.</p></div>"
+                },
+                {
+                    "type": "fieldset",
+                    "title": "Tapparelle & Cover",
+                    "expandable": false,
+                    "items": [
+                        {
+                            "type": "flex",
+                            "flex-flow": "row wrap",
+                            "items": [
+                                {
+                                    "key": "maxSeconds",
+                                    "flex": "1 1 200px",
+                                    "description": "Tempo totale apertura/chiusura"
+                                },
+                                {
+                                    "key": "coverStepSize",
+                                    "flex": "1 1 200px",
+                                    "description": "Fluidità animazione (5 = fluido)"
+                                }
+                            ]
+                        }
+                    ]
+                },
+                {
+                    "type": "fieldset",
+                    "title": "Termostati",
+                    "expandable": false,
+                    "items": [
+                        {
+                            "type": "flex",
+                            "flex-flow": "row wrap",
+                            "items": [
+                                {
+                                    "key": "temperatureDefaults.target",
+                                    "title": "Temp. Target Default (°C)",
+                                    "flex": "1 1 150px"
+                                },
+                                {
+                                    "key": "temperatureDefaults.min",
+                                    "title": "Temp. Minima (°C)",
+                                    "flex": "1 1 150px"
+                                },
+                                {
+                                    "key": "temperatureDefaults.max",
+                                    "title": "Temp. Massima (°C)",
+                                    "flex": "1 1 150px"
+                                },
+                                {
+                                    "key": "temperatureDefaults.step",
+                                    "title": "Step (°C)",
+                                    "flex": "1 1 100px"
+                                }
+                            ]
+                        }
+                    ]
+                },
+                {
+                    "type": "fieldset",
+                    "title": "Scenari",
+                    "expandable": false,
+                    "items": [
+                        {
+                            "key": "scenarioAutoOffDelay",
+                            "description": "Dopo l'attivazione, lo switch torna OFF automaticamente"
+                        }
+                    ]
+                }
+            ]
+        },
+        {
+            "type": "section",
+            "title": "Esclusioni Dispositivi",
+            "expandable": true,
+            "expanded": false,
+            "items": [
+                {
+                    "type": "help",
+                    "helpvalue": "<div class='alert alert-warning'><strong>Come Trovare gli ID</strong><ol class='mb-0 mt-2'><li>Avvia il plugin una volta</li><li>Apri il file <code>~/.homebridge/klares4-devices.json</code></li><li>Trova gli ID numerici dei dispositivi da escludere</li><li>Aggiungili qui sotto usando il pulsante <strong>+ Aggiungi</strong></li></ol></div>"
+                },
+                {
+                    "key": "excludeOutputs",
+                    "type": "array",
+                    "title": "Output Esclusi (Luci, Tapparelle, Termostati)",
+                    "description": "Inserisci solo il numero ID, senza prefissi",
+                    "orderable": false,
+                    "buttonText": "+ Aggiungi Output",
+                    "items": [
+                        {
+                            "key": "excludeOutputs[]",
+                            "notitle": true,
+                            "placeholder": "ID numerico (es: 18)"
+                        }
+                    ]
+                },
+                {
+                    "key": "excludeZones",
+                    "type": "array",
+                    "title": "Zone Escluse (Sensori di sicurezza)",
+                    "description": "Zone che non vuoi vedere come sensori contatto in HomeKit",
+                    "orderable": false,
+                    "buttonText": "+ Aggiungi Zona",
+                    "items": [
+                        {
+                            "key": "excludeZones[]",
+                            "notitle": true,
+                            "placeholder": "ID numerico (es: 5)"
+                        }
+                    ]
+                },
+                {
+                    "key": "excludeSensors",
+                    "type": "array",
+                    "title": "Sensori Esclusi (Ambientali)",
+                    "description": "Sensori temperatura/umidità/luminosità da nascondere",
+                    "orderable": false,
+                    "buttonText": "+ Aggiungi Sensore",
+                    "items": [
+                        {
+                            "key": "excludeSensors[]",
+                            "notitle": true,
+                            "placeholder": "ID numerico (es: 1)"
+                        }
+                    ]
+                },
+                {
+                    "key": "excludeScenarios",
+                    "type": "array",
+                    "title": "Scenari Esclusi",
+                    "description": "Scenari che non vuoi attivare da HomeKit",
+                    "orderable": false,
+                    "buttonText": "+ Aggiungi Scenario",
+                    "items": [
+                        {
+                            "key": "excludeScenarios[]",
+                            "notitle": true,
+                            "placeholder": "ID numerico (es: 3)"
+                        }
+                    ]
+                }
+            ]
+        },
+        {
+            "type": "section",
+            "title": "Integrazione MQTT",
+            "expandable": true,
+            "expanded": false,
+            "items": [
+                {
+                    "type": "help",
+                    "helpvalue": "<div class='alert alert-primary'><strong>Bridge MQTT</strong><p class='mb-1'>Pubblica gli stati su MQTT e ricevi comandi per integrazione con Home Assistant, Node-RED, o altri sistemi.</p><small><strong>Topic:</strong> <code>{prefix}/{type}/{slug}/state</code> e <code>.../{type}/{slug}/set</code></small></div>"
+                },
+                {
+                    "key": "mqtt.enabled",
+                    "title": "Abilita Bridge MQTT"
+                },
+                {
+                    "key": "mqtt.broker",
+                    "condition": {
+                        "functionBody": "return model.mqtt && model.mqtt.enabled === true;"
+                    },
+                    "placeholder": "mqtt://192.168.1.x:1883"
+                },
+                {
+                    "type": "flex",
+                    "flex-flow": "row wrap",
+                    "condition": {
+                        "functionBody": "return model.mqtt && model.mqtt.enabled === true;"
+                    },
+                    "items": [
+                        {
+                            "key": "mqtt.username",
+                            "flex": "1 1 200px"
+                        },
+                        {
+                            "key": "mqtt.password",
+                            "type": "password",
+                            "flex": "1 1 200px"
+                        }
+                    ]
+                },
+                {
+                    "type": "flex",
+                    "flex-flow": "row wrap",
+                    "condition": {
+                        "functionBody": "return model.mqtt && model.mqtt.enabled === true;"
+                    },
+                    "items": [
+                        {
+                            "key": "mqtt.clientId",
+                            "flex": "1 1 200px"
+                        },
+                        {
+                            "key": "mqtt.topicPrefix",
+                            "flex": "1 1 200px"
+                        }
+                    ]
+                },
+                {
+                    "type": "flex",
+                    "flex-flow": "row wrap",
+                    "condition": {
+                        "functionBody": "return model.mqtt && model.mqtt.enabled === true;"
+                    },
+                    "items": [
+                        {
+                            "key": "mqtt.qos",
+                            "flex": "1 1 200px"
+                        },
+                        {
+                            "key": "mqtt.retain",
+                            "flex": "1 1 200px"
+                        }
+                    ]
+                },
+                {
+                    "type": "section",
+                    "title": "Mappatura Stanze",
+                    "expandable": true,
+                    "expanded": false,
+                    "condition": {
+                        "functionBody": "return model.mqtt && model.mqtt.enabled === true;"
+                    },
+                    "items": [
+                        {
+                            "type": "help",
+                            "helpvalue": "<div class='alert alert-success'><strong>Organizza per stanza:</strong> invece di <code>klares4/light/luce_sala</code> ottieni <code>soggiorno/light/luce_sala</code></div>"
+                        },
+                        {
+                            "key": "roomMapping.enabled",
+                            "title": "Abilita Mappatura Stanze"
+                        },
+                        {
+                            "key": "roomMapping.rooms",
+                            "type": "array",
+                            "title": "Configurazione Stanze",
+                            "orderable": true,
+                            "buttonText": "+ Aggiungi Stanza",
+                            "condition": {
+                                "functionBody": "return model.roomMapping && model.roomMapping.enabled === true;"
+                            },
+                            "items": [
+                                {
+                                    "type": "fieldset",
+                                    "items": [
+                                        {
+                                            "key": "roomMapping.rooms[].roomName",
+                                            "title": "Nome Stanza (minuscolo)",
+                                            "placeholder": "soggiorno"
+                                        },
+                                        {
+                                            "key": "roomMapping.rooms[].devices",
+                                            "type": "array",
+                                            "title": "Dispositivi",
+                                            "orderable": false,
+                                            "buttonText": "+ Dispositivo",
+                                            "items": [
+                                                {
+                                                    "key": "roomMapping.rooms[].devices[].deviceId",
+                                                    "title": "ID Dispositivo",
+                                                    "placeholder": "light_9 o sensor_temp_1"
+                                                }
+                                            ]
+                                        }
+                                    ]
+                                }
+                            ]
+                        }
+                    ]
+                }
+            ]
+        },
+        {
+            "type": "section",
+            "title": "Configurazione Avanzata",
+            "expandable": true,
+            "expanded": false,
+            "items": [
+                {
+                    "type": "help",
+                    "helpvalue": "<div class='alert alert-danger'><strong>Solo per Utenti Esperti</strong><p class='mb-0'>Modifica questi parametri solo se sai cosa stai facendo. Valori errati possono causare disconnessioni frequenti o comportamenti anomali.</p></div>"
+                },
+                {
+                    "key": "showAdvanced",
+                    "title": "Sblocca Parametri Avanzati",
+                    "description": "Abilita per modificare timing e parametri di rete"
+                },
+                {
+                    "type": "fieldset",
+                    "title": "Parametri di Rete",
+                    "condition": {
+                        "functionBody": "return model.showAdvanced === true;"
+                    },
+                    "items": [
+                        {
+                            "type": "flex",
+                            "flex-flow": "row wrap",
+                            "items": [
+                                {
+                                    "key": "reconnectInterval",
+                                    "flex": "1 1 200px",
+                                    "description": "Base per exponential backoff (v1.1.6)"
+                                },
+                                {
+                                    "key": "heartbeatInterval",
+                                    "flex": "1 1 200px",
+                                    "description": "Frequenza ping keep-alive con timeout PONG (v1.1.6)"
+                                }
+                            ]
+                        }
+                    ]
+                },
+                {
+                    "type": "fieldset",
+                    "title": "Debug & Diagnostica",
+                    "condition": {
+                        "functionBody": "return model.showAdvanced === true;"
+                    },
+                    "items": [
+                        {
+                            "type": "flex",
+                            "flex-flow": "row wrap",
+                            "items": [
+                                {
+                                    "key": "debug",
+                                    "flex": "1 1 200px"
+                                },
+                                {
+                                    "key": "devicesSummaryDelay",
+                                    "flex": "1 1 200px",
+                                    "description": "Ritardo stampa lista dispositivi"
+                                }
+                            ]
+                        }
+                    ]
+                },
+                {
+                    "type": "section",
+                    "title": "🔧 Diagnostica & Debug",
+                    "expandable": true,
+                    "expanded": false,
+                    "items": [
+                        {
+                            "type": "help",
+                            "helpvalue": "<div class='alert alert-warning'><strong>⚠️ Strumento di Diagnostica Completa</strong><p class='mb-2'>Genera un file di debug con TUTTO il necessario per diagnosticare problemi:</p><ul class='mb-2'><li><strong>Tutti i messaggi WebSocket RAW</strong> per 60 secondi</li><li><strong>Lista completa dispositivi</strong> dalla centrale Ksenia</li><li><strong>Tutti i comandi disponibili</strong> (ZONES, OUTPUTS, BUS_HAS, SCENARIOS, STATUS)</li><li><strong>Stati in tempo reale</strong> durante la cattura</li></ul><p class='mb-0 text-danger'><strong>IMPORTANTE:</strong> Durante i 60 secondi di cattura, <strong>prova tutte le entità che non funzionano usando l'app Ksenia</strong> (accendi/spegni luci, apri/chiudi tapparelle, cambia zone, ecc). Questo ci permetterà di vedere esattamente come la centrale risponde ai comandi.</p></div>"
+                        },
+                        {
+                            "key": "generateDebugFile",
+                            "title": "Genera File Debug al Prossimo Avvio",
+                            "description": "Si disattiverà automaticamente dopo la generazione del file"
+                        },
+                        {
+                            "type": "help",
+                            "helpvalue": "<div class='alert alert-info'><strong>📋 Procedura consigliata:</strong><ol class='mb-0'><li><strong>Attiva</strong> l'opzione sopra e <strong>salva</strong> la configurazione</li><li><strong>Riavvia Homebridge</strong> (il debug inizierà automaticamente)</li><li><strong>Nei prossimi 60 secondi</strong>: apri l'app Ksenia e <strong>testa TUTTE le entità che non funzionano</strong> (luci on/off, tapparelle su/giù, scenari, zone, ecc)</li><li><strong>Attendi</strong> che la cattura finisca (vedrai conferma nei log con il percorso del file)</li><li><strong>Trova il file</strong> usando il pulsante qui sotto o nei log</li><li><strong>Condividi</strong> il file per supporto (PIN già mascherati automaticamente)</li></ol></div>"
+                        },
+                        {
+                            "type": "help",
+                            "helpvalue": "<div class='alert alert-success'><strong>📂 Percorso File Debug:</strong><p class='mb-2'>I file di debug vengono salvati in:</p><p class='mb-2'><code>~/.homebridge/klares4-debug-*.json</code></p><p class='mb-2'>oppure su macOS:</p><p class='mb-2'><code>/Users/[tuo-username]/.homebridge/klares4-debug-*.json</code></p><p class='mb-0'><strong>💡 Suggerimento:</strong> Cerca il file più recente con nome <code>klares4-debug-</code> seguito dalla data/ora. Il percorso esatto viene mostrato nei log di Homebridge quando il file viene generato.</p></div>"
+                        }
+                    ]
+                }
+            ]
+        }
+    ]
+}