node-red-contrib-knx-ultimate/nodes/locales/it/knxUltimate.html

Control your KNX and KNX Secure intallation via Node-Red! A bunch of KNX nodes, with integrated Philips HUE control and ETS group address importer. Easy to use and highly configurable.

<script type="text/markdown" data-help-name="knxUltimate">
## IMPOSTAZIONI DEL NODO KNX‑ULTIMATE (DEVICE)

Questo nodo controlla un Indirizzo di Gruppo KNX; è il nodo più utilizzato.

[<i class="fa fa-code"></i> Qui trovi alcuni esempi](https://github.com/Supergiovane/node-red-contrib-knx-ultimate/wiki/-SamplesHome)

**Configurazione**

|Proprietà|Descrizione|
|--|--|
| Gateway | Seleziona il gateway KNX da utilizzare |
| Elenco a discesa tipo GA | Tipo di indirizzo di gruppo. **3‑Livelli ** è il default, dove puoi digitare il GA a 3 livelli o il nome GA (se hai caricato il file ETS);**Global ** legge il GA da una variabile globale all'avvio;**Flow ** fa lo stesso a livello di flow. Seleziona**$Env variable ** per leggere il GA da una variabile d'ambiente. Seleziona**Modalità universale (ascolta tutti gli Indirizzi di Gruppo)** per reagire a TUTTI i GA. |
| Group Addr. | L'indirizzo di gruppo KNX da controllare. Se hai importato il file ETS, puoi iniziare a digitare il nome del dispositivo. Puoi lasciarlo vuoto se intendi impostarlo tramite messaggio di ingresso `msg.setConfig`. |
| Datapoint | Il Datapoint associato al nodo. |

<br/>
<br/>

### Pulsante di comando manuale

L’editor può mostrare, per ogni nodo, un pulsante che invia manualmente un comando KNX senza dover aggiungere nodi Inject.

|Proprietà|Descrizione|
|--|--|
| Mostra pulsante manuale | Se attivo, il piccolo pulsante viene visualizzato sul nodo nel workspace e nel pannello dei nodi. |
| Azione del pulsante | Definisce l’operazione eseguita al click. **Invia lettura KNX** invia un telegramma di lettura standard. **Inverti booleano (scrittura)** è disponibile per i datapoint di tipo 1.x e alterna i valori _true_/_false_ a ogni click. **Scrivi valore personalizzato** invia il valore inserito dall’utente (deve essere compatibile con il Datapoint configurato). |
| Stato iniziale del toggle | (Solo datapoint booleani) Imposta il valore iniziale utilizzato dalla modalità toggle. Lo stato viene aggiornato automaticamente in base ai telegrammi che il nodo riceve dal BUS. |
| Valore personalizzato | Payload utilizzato dalla modalità “Scrivi valore personalizzato”. È possibile inserire qualsiasi letterale JSON, ad esempio `42`, `true`, `"testo"` oppure `{ "red": 255 }`. |

Il pulsante è visibile soltanto se l’opzione è attiva. In modalità universale l’azione di lettura è disabilitata perché l’indirizzo di gruppo sarebbe sconosciuto.

<br/>
<br/>

## TAB Opzioni avanzate

|Proprietà|Descrizione|
|--|--|
|| **Proprietà generali** |
| Nome del nodo | Autoesplicativo. |
| Topic | Il topic del messaggio in uscita. Lascia vuoto per usare l'Indirizzo di Gruppo. |
| Passthrough | Se attivo, inoltra sul PIN di uscita il msg di ingresso. |
|| **Dal PIN di INGRESSO del nodo verso il BUS KNX** |
| Tipo telegramma | `write` per inviare un telegramma di scrittura (in genere è ciò che vuoi); in alternativa puoi scegliere a quale tipo di telegramma reagire. |
| Filtro RBE | Filtro "Report by change”. Se attivo, invia al BUS solo messaggi di ingresso con valore diverso dal precedente. Se devi inviare sempre lo stesso valore, disattivalo. Se attivo, verrà aggiunta l'indicazione "rbe” al nome del nodo. |
|| **Dal BUS KNX verso il PIN di USCITA del nodo** |
| Read status on start | Legge lo stato del GA ad ogni avvio di Node‑RED e a ogni riconnessione al Gateway KNX. Il nodo memorizza i valori su file, quindi puoi scegliere se leggere da file o dal BUS KNX. |
| Filtro RBE | Filtro "Report by change” sull'uscita: invia al flow solo quando il valore cambia. Se vuoi inviare anche valori ripetuti, lascialo disattivo. Se attivo, aggiunge "rbe” al nome del nodo. |
| React to write telegrams | Il nodo invia un msg al flow ogni volta che riceve un telegramma di tipo write dal BUS KNX. |
| React to response telegrams | Il nodo invia un msg al flow alla ricezione di un telegramma di risposta. Utile in scenari specifici. |
| React to read telegrams | Il nodo invia un msg al flow alla ricezione di un telegramma di lettura. Utile quando vuoi rispondere con un valore personalizzato al BUS. |
| Multiply | Moltiplica o divide il valore del payload. Funziona solo con numeri. |
| Decimals | Arrotonda o gestisce i decimali. Solo numeri. |
| Negatives | Gestisce i valori negativi. Solo numeri. |

<br/>
<br/>

## TAB KNX Function

Puoi usare JavaScript per modificare il comportamento del msg in ingresso (dal flow) e del telegramma in uscita (verso il BUS KNX).
L'editor integrato espone oggetti e funzioni utili per leggere il valore di qualsiasi GA, con o senza file ETS (in questo caso specificando il Datapoint).
Lo script viene eseguito a ogni msg in ingresso o a ogni telegramma ricevuto dal BUS. Se attivo, al nome del nodo viene aggiunta l'indicazione "f(x)”.

|Proprietà|Descrizione|
|--|--|
| Search GA | Disponibile solo se hai importato il file ETS. Inizia a digitare e seleziona il GA da inserire nel codice, poi incolla il campo completo nella funzione `getGAValue`. <br/> **getGAValue('0/0/1 table nord lamp')** |

<br/>

### Oggetti e funzioni disponibili nel codice

|Oggetto/Funzione|Descrizione|
|--|--|
| `msg` (object) | Il msg corrente ricevuto dal nodo. |
| `getGAValue` (string GA, string DPT opz.) | Restituisce il valore del GA, ad es. `'1/0/1'` o `'1/0/1 Bed table light'` (tutto dopo lo spazio viene ignorato). Con ETS importato, DPT è opzionale; altrimenti va specificato, per es. `'1.001'`. |
| `setGAValue` (string GA, any value, string DPT opz.) | Imposta il valore del GA indicato. Valgono le stesse regole di notazione del GA; il valore può essere boolean/number/string; DPT opzionale con ETS, altrimenti obbligatorio. |
| `self` (any) | Imposta il valore del nodo corrente e lo invia anche al BUS KNX (es.: `self(false)`). Attenzione nell'handler "From KNX BUS to OUTPUT”, per evitare loop. |
| `toggle`() | Inverte il valore del nodo e lo invia al BUS. Stesse cautele di `self`. |
| `node` | Oggetto nodo. |
| `RED` | Oggetto RED di Node‑RED. |
| `return (msg)` | È necessario `return msg;` per emettere il messaggio; `return;` non emette niente. |

### Dall'INPUT del flow al BUS KNX (esempi)

Invia al BUS solo se un altro GA ha valore opposto:

```javascript
const statusGA = getGAValue('0/0/09','1.001');
if (msg.payload !== statusGA){
  return msg;
} else {
  return;
}
```

Se qualcuno accende una luce, accendi 0/1/8 e dopo 2 s spegni il nodo:

```javascript
if (msg.payload){
  setGAValue('0/1/8', true)
  setTimeout(function() { self(off); }, 2000);
}
return msg;
```

### Dal BUS KNX al PIN di USCITA del nodo (esempi)

Allega all'output anche la temperatura esterna letta da un altro GA:

```javascript
// msg.payload contiene la temperatura interna; aggiungi la esterna
msg.externalTemperature = getGAValue('0/0/10'); // senza ETS: getGAValue('0/0/10','9.001')
return msg;
```

Non emettere nulla se `msg.payload` e un altro GA sono entrambi false:

```javascript
if (msg.payload === false && getGAValue('0/0/11','1.001') === false){
  return; // non emettere
} else {
  return msg;
}
```

<br/>
<br/>

### Inputs

**destination (string) ** : indirizzo di gruppo di destinazione (solo 3‑livelli), es. `1/1/0`.**payload (any) ** : valore da inviare (true/false/numero/stringa/oggetto).**event (string) ** : `GroupValue_Write` (scrive sul BUS), `GroupValue_Response` (risponde sul BUS), `Update_NoWrite` (non invia al BUS, aggiorna solo il valore interno del nodo).**readstatus (boolean) ** : invia un "Read” al BUS (usa sempre `true`).**dpt (string) ** : per es. `1.001`. Imposta il Datapoint.**writeraw (buffer) ** e**bitlenght (int) ** : invio RAW verso il BUS (vedi esempio). `bitlenght` è la lunghezza in bit del dato RAW.**resetRBE (boolean) ** : resetta i filtri RBE interni (`msg.resetRBE = true`).**setConfig (json)** : cambia via msg il GA e il DPT del nodo (vedi sotto).

### Dettagli setConfig

Puoi cambiare la configurazione del nodo inviando `msg.setConfig`.
Rimane attiva fino al prossimo `setConfig` o fino a riavvio/redeploy.
Le proprietà `setGroupAddress` e `setDPT` sono entrambe obbligatorie.

**Impostare GA e DPT**

```javascript
var config= { setGroupAddress: "0/1/2", setDPT: "1.001" };
msg.setConfig = config;
return msg;
```

**Impostare GA e leggere il DPT dal file ETS**

```javascript
var config= { setGroupAddress: "0/1/2", setDPT: "auto" };
msg.setConfig = config;
return msg;
```

### Outputs

1. Uscita standard: `payload (string|number|object)` sul PIN 1.
2. Errori: `error (object)` sul PIN 2 con il dettaglio dell'errore.

### Dettagli messaggio in uscita

`msg.payload` contiene il valore del GA (valore dell'indirizzo di gruppo).
Esempio di msg completo:

```json
msg = {
  topic: "0/1/2",
  payload: false,
  previouspayload: true,
  payloadmeasureunit: "%",
  payloadsubtypevalue: "Start",
  devicename: "Lampada tavolo pranzo",
  gainfo: {
    maingroupname: "Light actuators",
    middlegroupname: "First flow lights",
    ganame: "Table Light",
    maingroupnumber: "1",
    middlegroupnumber: "1",
    ganumber: "0"
  },
  echoed: true,
  knx: {
    event: "GroupValue_Write",
    dpt: "1.001",
    dptdesc: "Humidity",
    source: "15.15.22",
    destination: "0/1/2",
    rawValue: "<buffer>"
  }
}
```

---

# MESSAGGIO DAL FLOW IN INGRESSO

## Controllare dispositivi KNX

Il nodo accetta msg dal flow da inviare al BUS KNX e invia msg al flow quando riceve telegrammi dal BUS.<br/>
Se hai impostato GA e DPT (manualmente o tramite autocompilazione da ETS), puoi anche sovrascrivere via msg alcuni parametri della finestra di configurazione.
Tutte le proprietà sotto sono opzionali, tranne `payload`.

**msg.destination ** : ad es. `0/0/1`. GA a 3 livelli da aggiornare.**msg.payload ** : ad es. `true/false/21/"Hello"`. Valore da inviare al BUS.**msg.event** :<br/>
`GroupValue_Write`: scrive sul BUS.<br/>
`GroupValue_Response`: invia una risposta sul BUS.<br/>
`Update_NoWrite`: non invia sul BUS, aggiorna solo il valore interno del nodo.<br/>
ATTENZIONE: con `msg.event = "Update_NoWrite"` tutti i nodi con lo stesso GA emetteranno un msg con `event: 'Update_NoWrite'` e `eventdesc` descrittivo.

Se vuoi emettere un "read”, usa `msg.readstatus = true`.

**msg.readstatus = true ** : emette un comando di lettura verso il BUS.**msg.dpt ** : per es. `1.001` (accetta anche `9`, `"9"`, `"DPT9.001"`).**msg.writeraw ** e**msg.bitlenght ** : invio RAW al BUS (vedi esempio sotto). Se usi `writeraw`, il DPT impostato nel nodo viene ignorato.**msg.resetRBE = true** : resetta i filtri RBE di input e output del nodo.

## Cambiare la configurazione via msg

Puoi cambiare la configurazione del nodo inviando `msg.setConfig`.
[Vedi la pagina di esempio.](https://github.com/Supergiovane/node-red-contrib-knx-ultimate/wiki/-Sample-setConfig)

---

# QUICK HOW TO

Altri esempi [qui](https://github.com/Supergiovane/node-red-contrib-knx-ultimate/wiki/-SamplesHome)

**ACCENDERE UNA LAMPADA**

```javascript
msg.payload = true;
return msg;
```

**DIMMER ASSOLUTO DI UNA LAMPADA**

```javascript
msg.payload = 30;
return msg;
```

**INVIARE TESTO A UN DISPLAY**

```javascript
msg.payload = "Output Tem. 35°C";
return msg;
```

**LEGGERE LO STATO DI UNA LAVATRICE**

```javascript
// Invia una richiesta di lettura al BUS; seleziona l'opzione
// "React to response telegrams" per ricevere la risposta.
msg.readstatus = true;
return msg;
```

**INVIARE UN VALORE RAW AL BUS**
Inserisci un function node prima del nodo KNX‑Ultimate e usa questo codice:

```javascript
// Esempio DPT 1: luce ON = Buffer<01> con bitlength = 1
msg.writeraw = Buffer.from('01', 'hex');
msg.bitlenght = 1;
return msg;

// Esempio temperatura (DPT 9): 18.4 °C = Buffer<0730>
// msg.writeraw = Buffer.from('0730', 'hex');
// return msg;
```
</script>