Élő adatok (WebSocket)

A WebSockettel az eszközök méréseit és változásait abban a pillanatban kapja meg, amikor történnek. A HAM alkalmazás ugyanezt a kapcsolatot használja. Egy-egy méréshez a REST API egyszerűbb.

Cím

wss://DEVICE_SERVER:9001

• A DEVICE_SERVER az egyes eszközök device_server mezőjének értéke. A get_user_devices.php végponttal találja meg.
• Egy fiók eszközei különböző szervereken lehetnek. Minden különböző szerverhez egy kapcsolatot nyisson, ne minden eszközhöz egyet.
• A 9001-es portnak nyitva kell lennie a kimenő kapcsolatokhoz. Lásd: hálózati követelmények.

Üzenetformátum

Minden elküldött üzenet egy JSON tömb:

[command_id, payload]

A command_id egy egész szám. Kezdje 1-gyel, és minden üzenettel növelje. A válasz ugyanazt a command_id értéket tartalmazza.

Egy üzenet legnagyobb mérete 20 KiB. Ha nagyobb üzenetet küld, a szerver bezárja a kapcsolatot.

1. Hitelesítés

A kapcsolat utáni első üzenet a hitelesítés:

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

Ezt is küldheti: {"access_token": "YOUR_ACCESS_TOKEN"}. Lásd: hitelesítés.

Válasz	Jelentés
[]	Sikeres
["Access Denied"]	Hibás kulcs vagy token. A szerver bezárja a kapcsolatot.
[1,[{},"Rate limit"]]	Túl sok kapcsolat rövid idő alatt

Kapcsolatkorlát: egy API kulcsnál 15 kapcsolat 60 másodpercenként. Egy hozzáférési tokennél 25 kapcsolat 60 másodpercenként.

2. Feliratkozás eszközökre (SUBSCRIBE)

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

Mező	Jelentés
c	SUBSCRIBE
server	Mindig true
serialnos	Az ezen a szerveren lévő eszközök sorozatszámai
unsubscribe-others	true: a szerver leállítja ennek a kapcsolatnak a korábbi feliratkozásait

Válasz: [2,[{},""]]. A szerver kihagyja azokat az eszközöket, amelyekhez nincs hozzáférése. Ezekre nem küld hibát.

Az összes feliratkozás leállításához küldje ezt: [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Állapotfrissítések

Közvetlenül a feliratkozás után a szerver elküldi az egyes eszközök aktuális állapotát. Ezután minden változáskor frissítést küld.

A frissítések JSON objektumok, nem tömbök:

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

Mező	Tartalom
serialno	Az eszköz
R	A mérések, nyers értékként, mérési kód szerint
O	A kimenetek értékei, az output_names sorrendjében
T	Az eszköz ütemezései
S	Az eszköz beállításai
previous	Az előző időszak összesített értékei, számlálóval rendelkező eszközöknél
alarms	Az aktív riasztások
is_local	true, ha a kapcsolata és az eszköz ugyanazon a hálózaton van

• Egy frissítés csak a megváltozott mezőket is tartalmazhatja. Fésülje össze a már meglévő állapottal.
• A szerver kb. 100 ms-ig gyűjti a változásokat, mielőtt frissítést küld.
• Hagyja figyelmen kívül azokat az üzeneteket, amelyeket nem ismer fel.

A nyers értékek átváltásához használja a családdefiníciókat. Lásd: REST API.

A kapcsolat nyitva tartása

• A szerver WebSocket pingeket küld. A könyvtárának ponggal kell válaszolnia. A legtöbb könyvtár ezt automatikusan elvégzi.
• Ha a kapcsolat bezárul, csatlakozzon újra. Az alkalmazás először 100 ms-ot, utána 10 másodpercet vár.
• Új kapcsolat után küldje el újra a hitelesítést és a feliratkozást.

Node.js példa

A Node.js 22 beépített WebSocket osztállyal rendelkezik.

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

Egy teljes Node.js példa itt található: nodejs_hamapi_example.zip. Tartalmazza a hamapi.js könyvtárat és az example.js fájlt.

1. Az example.js fájlban állítsa be a server, az api_key értéket és a sorozatszámokat.
2. Futtassa az npm install, majd a node example.js parancsot.

A könyvtár nem csatlakozik újra, amikor a kapcsolat bezárul. Ezt adja hozzá a kódjához.

Lásd még

• REST API
• Webhookok szabályokból