Živá data (WebSocket)

Přes WebSocket získáte měření a změny zařízení v okamžiku, kdy nastanou. Aplikace HAM používá stejné připojení. Pro jedno měření najednou je jednodušší REST API.

Adresa

wss://DEVICE_SERVER:9001

• DEVICE_SERVER je hodnota pole device_server každého zařízení. Najdete ji pomocí get_user_devices.php.
• Zařízení jednoho účtu mohou být na různých serverech. Otevřete jedno připojení pro každý jiný server, ne jedno pro každé zařízení.
• Port 9001 musí být otevřený pro odchozí připojení. Viz síťové požadavky.

Formát zprávy

Každá zpráva, kterou pošlete, je pole JSON:

[command_id, payload]

command_id je celé číslo. Začněte od 1 a s každou zprávou ho zvyšte. Odpověď má stejné command_id.

Maximální velikost zprávy je 20 KiB. Server zavře připojení, pokud pošlete větší zprávu.

1. Ověření

První zpráva po připojení je ověření:

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

Můžete také poslat {"access_token": "YOUR_ACCESS_TOKEN"}. Viz ověření.

Odpověď	Význam
[]	Úspěch
["Access Denied"]	Chybný klíč nebo token. Server zavře připojení.
[1,[{},"Rate limit"]]	Příliš mnoho připojení za krátkou dobu

Limit připojení: 15 za 60 sekund pro jeden API klíč. 25 za 60 sekund pro jeden přístupový token.

2. Odběr zařízení (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 zařízení na tomto serveru
unsubscribe-others	true: server zastaví dřívější odběry tohoto připojení

Odpověď: [2,[{},""]]. Server přeskočí zařízení, k nimž nemáte přístup. Pro ně neposílá chybu.

Chcete-li zastavit všechny odběry, pošlete [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Aktualizace stavu

Ihned po odběru server pošle aktuální stav každého zařízení. Pak pošle aktualizaci při každé změně.

Aktualizace jsou objekty JSON, ne pole:

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

Pole	Obsah
serialno	Zařízení
R	Měření, surová, podle kódu měření
O	Hodnoty výstupů v pořadí output_names
T	Plány zařízení
S	Nastavení zařízení
previous	Nasbírané hodnoty předchozího období, u zařízení s počítadly
alarms	Aktivní alarmy
is_local	true, pokud jsou vaše připojení a zařízení ve stejné síti

• Aktualizace může obsahovat jen pole, která se změnila. Sloučte ji se stavem, který už máte.
• Server seskupuje změny asi 100 ms, než pošle aktualizaci.
• Ignorujte zprávy, které nepoznáte.

Pro převod surových hodnot použijte definice rodiny. Viz REST API.

Udržení připojení

• Server posílá ping WebSocket. Vaše knihovna musí odpovědět pongem. Většina knihoven to dělá automaticky.
• Pokud se připojení zavře, připojte se znovu. Aplikace čeká poprvé 100 ms a poté 10 sekund.
• Po novém připojení pošlete ověření a odběr znovu.

Příklad v Node.js

Node.js 22 má vestavěný 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ý příklad v Node.js je v souboru nodejs_hamapi_example.zip. Obsahuje knihovnu hamapi.js a soubor example.js.

1. V souboru example.js nastavte server, api_key a sériová čísla.
2. Spusťte npm install a potom node example.js.

Knihovna se po zavření spojení znovu nepřipojí. Doplňte to do svého kódu.

Viz také

• REST API
• Webhooky z pravidel