Dati in tempo reale (WebSocket)

Con il WebSocket ottiene le misurazioni e le variazioni dei dispositivi nel momento in cui avvengono. L’app HAM usa la stessa connessione. Per una misurazione alla volta, l’API REST è più semplice.

Indirizzo

wss://DEVICE_SERVER:9001

• DEVICE_SERVER è il valore del campo device_server di ogni dispositivo. Lo trova con get_user_devices.php.
• I dispositivi di un account possono essere su server diversi. Apra una connessione per ogni server diverso, non una per ogni dispositivo.
• La porta 9001 deve essere aperta per le connessioni in uscita. Veda i requisiti di rete.

Formato dei messaggi

Ogni messaggio che invia è un array JSON:

[command_id, payload]

Il command_id è un numero intero. Parta da 1 e lo aumenti a ogni messaggio. La risposta ha lo stesso command_id.

La dimensione massima di un messaggio è 20 KiB. Il server chiude la connessione se invia un messaggio più grande.

1. Autenticazione

Il primo messaggio dopo la connessione è l’autenticazione:

[1, {"api_key": "YOUR_API_KEY"}]

Può anche inviare {"access_token": "YOUR_ACCESS_TOKEN"}. Veda l’autenticazione.

Risposta	Significato
[]	Operazione riuscita
["Access Denied"]	Chiave o token errato. Il server chiude la connessione.
[1,[{},"Rate limit"]]	Troppe connessioni in poco tempo

Limite di connessioni: 15 ogni 60 secondi per una chiave API. 25 ogni 60 secondi per un token di accesso.

2. Sottoscrivere i dispositivi (SUBSCRIBE)

[2, {"c": "SUBSCRIBE", "server": true, "serialnos": ["e11:123", "e9:456"], "unsubscribe-others": true}]

Campo	Significato
c	SUBSCRIBE
server	Sempre true
serialnos	I numeri di serie dei dispositivi su questo server
unsubscribe-others	true: il server interrompe le sottoscrizioni precedenti di questa connessione

Risposta: [2,[{},""]]. Il server salta i dispositivi a cui non ha accesso. Non invia un errore per essi.

Per interrompere tutte le sottoscrizioni, invii [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Aggiornamenti di stato

Subito dopo la sottoscrizione, il server invia lo stato attuale di ogni dispositivo. Poi invia un aggiornamento a ogni variazione.

Gli aggiornamenti sono oggetti JSON, non array:

{
  "serialno": "e11:123",
  "R": { "T": 2082, "GI": 1, "GIC": 0, "GI2": 1, "GI2C": 0 },
  "O": [],
  "alarms": [],
  "is_local": false
}

Campo	Contenuto
serialno	Il dispositivo
R	Le misurazioni, grezze, con il codice della misurazione come chiave
O	I valori delle uscite, nell’ordine di output_names
T	Le programmazioni del dispositivo
S	Le impostazioni del dispositivo
previous	I valori accumulati del periodo precedente, per i dispositivi con contatori
alarms	Gli allarmi attivi
is_local	true se la Sua connessione e il dispositivo sono sulla stessa rete

• Un aggiornamento può avere solo i campi che sono cambiati. Lo unisca allo stato che ha già.
• Il server raggruppa le variazioni per circa 100 ms prima di inviare un aggiornamento.
• Ignori i messaggi che non riconosce.

Per convertire i valori grezzi, usi le definizioni delle famiglie. Veda l’API REST.

Mantenere aperta la connessione

• Il server invia ping WebSocket. La Sua libreria deve rispondere con un pong. La maggior parte delle librerie lo fa automaticamente.
• Se la connessione si chiude, si connetta di nuovo. L’app attende 100 ms la prima volta e 10 secondi dopo.
• Dopo una nuova connessione, invii di nuovo l’autenticazione e la sottoscrizione.

Esempio Node.js

Node.js 22 ha un WebSocket integrato.

const ws = new WebSocket('wss://DEVICE_SERVER:9001');
let id = 1;

ws.onopen = () => {
  ws.send(JSON.stringify([id++, { api_key: 'YOUR_API_KEY' }]));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (Array.isArray(msg) && msg.length === 0) {
    ws.send(JSON.stringify([id++, {
      c: 'SUBSCRIBE', server: true,
      serialnos: ['e11:123'], 'unsubscribe-others': true
    }]));
  } else if (!Array.isArray(msg) && msg.serialno) {
    console.log(msg.serialno, msg.R);
  }
};

Un esempio completo Node.js è in nodejs_hamapi_example.zip. Contiene la libreria hamapi.js e il file example.js.

1. In example.js, impostate server, api_key e i numeri di serie.
2. Eseguite npm install, poi node example.js.

La libreria non si riconnette quando la connessione si chiude. Aggiungete questo nel vostro codice.

Vedere anche

• API REST
• Webhook dalle regole