Il sistema TapHome è in grado di integrarsi con altri sistemi tramite un semplice protocollo di integrazione ASCII. Questo permette ad altri sistemi di ottenere informazioni e controllare i dispositivi TapHome.
Livelli di comunicazione supportati
- RS485
- TCP/IP
- UDP/IP
Descrizione del protocollo
Il protocollo supporta i seguenti comandi:
HELP, LIST, GET, SET, ACTION, HEADER, AUTOSEND
Ogni comando deve terminare con i caratteri CRLF (0x0D 0x0A, \r\n).
Comando HELP
Il comando HELP visualizza informazioni di base sui comandi supportati.
HEADER [ON/OFF] attiva o disattiva l’intestazione nelle risposte.
LIST visualizza tutti i dispositivi esposti.
GET [ID] ottiene lo stato del dispositivo con l’ID specificato.
SET [ID ST VAL1 .. VALN] imposta lo stato del dispositivo con ID indicato e i valori ST e VAL1..VALN.
ACTION [ID NUM VAL] esegue sul dispositivo con ID indicato l’azione numero NUM con valore VAL.
PUSHALL [ON/OFF] abilita l’invio delle modifiche di tutti i dispositivi.
Comando HEADER
Il comando HEADER commuta tra due possibili formati di uscita dati. Se l’intestazione è ON, i dati sono inviati insieme a informazioni descrittive. Se l’intestazione è OFF vengono inviati solo i dati.
HEADER senza parametri restituisce informazioni sullo stato attuale dell’intestazione.
HEADER ON attiva l’intestazione nelle risposte.
HEADER OFF disattiva l’intestazione nelle risposte.
Comando LIST
Il comando LIST mostra tutti i dispositivi esposti.
Le seguenti informazioni vengono visualizzate:
ID del dispositivo: un identificatore numerico.
Tipo di dispositivo: la descrizione testuale del tipo di dispositivo (Tenda, Interruttore, …).
Nome dispositivo: così come impostato nel sistema TapHome.
Stato del dispositivo: come informazione testuale.
Esempio di output di LIST:
|
|
Comando GET
Il comando GET richiede un parametro: l’ID del dispositivo. Restituisce lo stato del dispositivo e i valori come numeri.
Esempio di output del comando GET 137:
|
|
Esempio quando l’intestazione è disattivata:
|
|
Comando SET
Il comando SET richiede almeno tre parametri: prima l’ID del dispositivo, poi lo stato del dispositivo da impostare e quindi almeno un valore da impostare. Per i dispositivi con più di un valore tutti i valori devono essere specificati – ad esempio una tenda richiede sia il nuovo livello che l’angolo delle lamelle.
Esempio di output del comando SET 137 0 35 80 con intestazione attivata e disattivata:
|
|
Comando ACTION
Il comando ACTION esegue un’azione sul dispositivo con ID e valore forniti. Le azioni sono definite solo per le tende. Ci sono tre azioni numeriche per le tende:
0 ferma la tenda
1 regola il livello rispetto alla posizione attuale di +/- valore
2 regola l’angolo delle lamelle rispetto alla posizione attuale di +/- valore
Esempio di output del comando ACTION 137 1 -20:
|
|
Comando PUSHALL
Il comando PUSHALL abilita l’invio delle modifiche di tutti i dispositivi. Le informazioni sono inviate nello stesso formato della risposta al comando GET. Si noti che, quando usato sulla linea RS485, potrebbero verificarsi conflitti sul bus che causano incoerenze dei dati. Si consiglia quindi di utilizzare questo comando solo su linee full duplex, come RS232 o RS422. È possibile attivarlo anche sulla linea RS485 in sistemi dove non verranno usati i comandi SET o ACTION, cioè solo in sistemi di monitoraggio. Sulle linee RS485 dove sono richiesti i comandi SET e ACTION si consiglia di utilizzare un polling periodico tramite il comando GET invece del monitoraggio automatico.
Modalità indirizzo
Quando è impostato un ID interfaccia univoco, è possibile utilizzare tutti i comandi in modalità indirizzo. In questa modalità l’intestazione di indirizzo precede il comando stesso. L’intestazione di indirizzo è una sequenza !InterfaceID: dove InterfaceID è impostato nella configurazione dell’interfaccia. Ogni riga di risposta è quindi anch’essa preceduta dalla stessa intestazione. Solo l’interfaccia con l’indirizzo corretto risponderà: un indirizzamento errato non può essere riconosciuto dalla risposta.
Esempio di richiesta in modalità indirizzo con il comando !2:LIST:
|
|
Configurazione
Per esporre i dispositivi nel protocollo di integrazione, prima vai su Esponi dispositivi e scegli Aggiungi nuova interfaccia. Dalle interfacce offerte scegli una tra Protocollo di integrazione RS485, Protocollo di integrazione TCP o Protocollo di integrazione UDP:
Dopo aver aggiunto l’interfaccia del tipo desiderato, compila gli altri parametri. Imposta un ID interfaccia univoco per ogni interfaccia se vuoi utilizzare la modalità indirizzo.
Scegli il terminale per la comunicazione e compila i parametri di comunicazione per RS485. Imposta tutti i parametri della linea seriale come richiesto dal client collegato.
Imposta la porta TCP dell’interfaccia slave:
Imposta la porta UDP dell’interfaccia slave:
Poi usa Aggiungi dispositivo per aggiungere i tuoi dispositivi all’elenco dei dispositivi esposti:
Scegli un dispositivo dall’elenco dei dispositivi disponibili. Si noti che i dispositivi già aggiunti sono disabilitati (in grigio).
Dopo aver aggiunto il dispositivo, questo viene visualizzato nell’elenco dispositivi per l’interfaccia del protocollo di integrazione:
Fai clic sul dispositivo per visualizzare le informazioni su di esso, modificare l’ID dispositivo generato automaticamente o eliminare il dispositivo dall’elenco dei dispositivi esposti.
Dispositivi supportati
Di seguito i dispositivi attualmente supportati per l’esposizione nel protocollo di integrazione:
Termostato, Interruttore, Interruttore multivalore, Pulsante, Contatto Reed, Dimmer / Uscita analogica, Variabile, Persiana, Luce RGB.
| Tipo dispositivo | Comandi di scrittura | Comandi di lettura |
|---|---|---|
| Termostato | SET <DEVICE_ID> Es. “SET 1 0 24.5” Imposta il termostato con ID=1 a nessun errore, set point 24,5ºC. |
GET <DEVICE_ID> Risposta: Set point | Temperatura | Umidità Es. “GET 1” |
| Interruttore | SET <DEVICE_ID> Es. “SET 1 0 1” Accende l’interruttore con ID=1. Nessuno stato di errore. |
GET <DEVICE_ID> Risposta: Stato interruttore (0 o 1) |
| Interruttore multivalore | SET <DEVICE_ID> Es. “SET 1 0 3” Imposta l’interruttore multivalore con ID=1 al valore 3. Nessuno stato di errore. |
GET <DEVICE_ID> Risposta: Valore |
| Pulsante | SET <DEVICE_ID> Es. “SET 1 0 1” Simula una breve pressione del pulsante con ID=1. Nessuno stato di errore. |
GET <DEVICE_ID> Risposta: BUTTON_PRESSED (1 .. 4) |
| Contatto Reed | non disponibile | GET <DEVICE_ID> Risposta: Stato (0 o 1) |
| Dimmer / Uscita analogica | SET <DEVICE_ID> Es. “SET 1 0 55.5” Imposta il dimmer con ID=1 al valore 55,5%. Nessuno stato di errore. |
GET <DEVICE_ID> Risposta: Valore di uscita analogica (DDD.D) |
| Variabile | SET <DEVICE_ID> Es. “SET 1 0 1234.5” Imposta la variabile con ID=1 al valore 1234,5. Nessuno stato di errore. |
GET <DEVICE_ID> Risposta: Valore variabile (VVV.V) |
| Luce RGB | SET <DEVICE_ID> Es. “SET 1 0 180 100 50” Imposta la luce RGB con ID=1 al colore ciano, saturazione piena, luminosità al 50%. Nessuno stato di errore. |
GET <DEVICE_ID> Risposta: Hue | Saturation | Brightness |
| Persiana | SET <DEVICE_ID> LLL … LIVELLO DELLE PERSIANE AAA … ANGOLO DELLE LAMELLE Es. “SET 1 0 100 50” Imposta la persiana con ID=1 al livello 100%, con angolo delle lamelle 50°. ACTION <DEVICE_ID> 1 <+/->LLL Es. “ACTION 1 1 -10” Muove la persiana del 10% verso l’alto. ACTION <DEVICE_ID> 2 <+/->AAA Es. “ACTION 1 2 +25” Imposta l’angolo delle lamelle a +25% (direzione verso il basso). ACTION <DEVICE_ID> 0 Ferma la persiana. |
GET <DEVICE_ID> Risposta: Livello | Angolo |
| Gruppo di persiane | Come la Persiana, senza supporto per l’azione 0 (Stop). | |
| Slitta, Gruppo di slitte | non supportato | non supportato |
| Allarme, Contatore elettrico, Sensore di luminosità, Contatore impulso | non supportato | non supportato |
DEVICE_ID
Assegnato in modo incrementale a ogni dispositivo nell’elenco dei dispositivi esposti. Può essere modificato manualmente a qualsiasi valore.
ERRORE
0 … OK
1 … Batteria bassa
2 … Batteria critica
3 … Danneggiato
4 … Errore di comunicazione
5 … Errore sconosciuto
6 … Errore di autorizzazione
7 … Errore di configurazione
PULSANTE PREMUTO
1 … Pressione breve
2 … Pressione prolungata
3 … Doppia pressione
4 … Tripla pressione
Debugging della comunicazione RS485
Per le connessioni RS485 è possibile collegare un adattatore USB–RS485 al PC. Richieste e risposte saranno visibili nell’applicazione console.
Convertitore USB–RS485 standard
http://sk.farnell.com/ftdi/usb-rs485-we-1800-bt/cable-usb-rs485-serial-converter/dp/1740357
Nota: questo convertitore non è isolato galvanicamente, quindi dovresti collegare il GND del convertitore al GND del Core.
Software terminale per Windows
HTerm: http://www.der-hammer.info/terminal/
Come impostare il terminale HTerm
- Impostare correttamente le proprietà di connessione per corrispondere alle impostazioni dell’interfaccia TapHome Integration Protocol (nota che la velocità di trasmissione predefinita è 9600).
- Impostare New line su LF.
- Impostare Send on enter su CR-LF.
- Digitare il comando (es. “HELP”).
- Leggere la risposta.
Nota: se vuoi vedere le modifiche dei dispositivi TapHome nella console, usa il comando PUSHALL ON.
Debug della comunicazione TCP
Per il debug della comunicazione TCP è possibile utilizzare PuTTY (https://putty.org/) come terminale. Utilizza le seguenti impostazioni per la connessione TCP:
Per prima cosa imposta il tipo di connessione su Raw, quindi inserisci l’indirizzo IP del Core e la porta impostata nelle impostazioni esposte del protocollo di integrazione TCP.