Živé údaje (WebSocket)

Cez WebSocket dostávate merania a zmeny zariadení v okamihu, keď nastanú. Aplikácia HAM používa to isté pripojenie. Pre jedno meranie naraz je REST API jednoduchšie.

Adresa

wss://DEVICE_SERVER:9001

• DEVICE_SERVER je hodnota poľa device_server každého zariadenia. Nájdete ju cez get_user_devices.php.
• Zariadenia jedného účtu môžu byť na rôznych serveroch. Otvorte jedno pripojenie pre každý iný server, nie jedno pre každé zariadenie.
• Port 9001 musí byť otvorený pre odchádzajúce pripojenia. Pozrite požiadavky na sieť.

Formát správy

Každá správa, ktorú pošlete, je pole JSON:

[command_id, payload]

command_id je celé číslo. Začnite od 1 a zvýšte ho pri každej správe. Odpoveď má to isté command_id.

Najväčšia veľkosť správy je 20 KiB. Ak pošlete väčšiu správu, server zatvorí pripojenie.

1. Overenie

Prvá správa po pripojení je overenie:

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

Môžete poslať aj {"access_token": "YOUR_ACCESS_TOKEN"}. Pozrite overenie.

Odpoveď	Význam
[]	Úspech
["Access Denied"]	Nesprávny kľúč alebo token. Server zatvorí pripojenie.
[1,[{},"Rate limit"]]	Príliš veľa pripojení za krátky čas

Limit pripojení: 15 za 60 sekúnd pre jeden API kľúč. 25 za 60 sekúnd pre jeden prístupový token.

2. Odber zariadení (SUBSCRIBE)

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

Pole	Význam
c	SUBSCRIBE
server	Vždy true
serialnos	Sériové čísla zariadení na tomto serveri
unsubscribe-others	true: server zastaví predchádzajúce odbery tohto pripojenia

Odpoveď: [2,[{},""]]. Server preskočí zariadenia, ku ktorým nemáte prístup. Pre ne neposiela chybu.

Ak chcete zastaviť všetky odbery, pošlite [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Aktualizácie stavu

Hneď po odbere server pošle aktuálny stav každého zariadenia. Potom pošle aktualizáciu pri každej zmene.

Aktualizácie sú objekty JSON, nie polia:

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

Pole	Obsah
serialno	Zariadenie
R	Merania, surové, s kódom merania ako kľúčom
O	Hodnoty výstupov v poradí output_names
T	Plány zariadenia
S	Nastavenia zariadenia
previous	Nahromadené hodnoty predchádzajúceho obdobia, pre zariadenia s počítadlami
alarms	Aktívne alarmy
is_local	true, ak sú vaše pripojenie a zariadenie v tej istej sieti

• Aktualizácia môže mať iba polia, ktoré sa zmenili. Zlúčte ju so stavom, ktorý už máte.
• Server zoskupuje zmeny približne 100 ms a potom pošle aktualizáciu.
• Ignorujte správy, ktoré nepoznáte.

Na prevod surových hodnôt použite definície rodín. Pozrite REST API.

Udržanie otvoreného pripojenia

• Server posiela pingy WebSocket. Vaša knižnica musí odpovedať pongom. Väčšina knižníc to robí automaticky.
• Ak sa pripojenie zatvorí, pripojte sa znova. Aplikácia čaká prvýkrát 100 ms a potom 10 sekúnd.
• Po novom pripojení pošlite znova overenie a odber.

Príklad pre Node.js

Node.js 22 má zabudovaný WebSocket.

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);
  }
};

Úplný príklad pre Node.js je v nodejs_hamapi_example.zip. Obsahuje knižnicu hamapi.js a súbor example.js.

1. V example.js nastavte server, api_key a sériové čísla.
2. Spustite npm install a potom node example.js.

Knižnica sa znova nepripojí, keď sa pripojenie zatvorí. Pridajte to do svojho kódu.

Pozrite aj

• REST API
• Webhooky z pravidiel