Tiesioginiai duomenys (WebSocket)

Su WebSocket gaunate įrenginių rodmenis ir pokyčius tą akimirką, kai jie įvyksta. HAM programėlė naudoja tą patį ryšį. Vienam rodmeniui vienu metu paprastesnis yra REST API.

Adresas

wss://DEVICE_SERVER:9001

• DEVICE_SERVER yra kiekvieno įrenginio lauko device_server reikšmė. Ją rasite su get_user_devices.php.
• Vienos paskyros įrenginiai gali būti skirtinguose serveriuose. Atidarykite po vieną ryšį kiekvienam skirtingam serveriui, ne kiekvienam įrenginiui.
• Prievadas 9001 turi būti atidarytas išeinantiems ryšiams. Žr. Tinklo reikalavimai.

Pranešimų formatas

Kiekvienas Jūsų siunčiamas pranešimas yra JSON masyvas:

[command_id, payload]

command_id yra sveikasis skaičius. Pradėkite nuo 1 ir didinkite jį su kiekvienu pranešimu. Atsakymas turi tą patį command_id.

Didžiausias pranešimo dydis yra 20 KiB. Jei siunčiate didesnį pranešimą, serveris uždaro ryšį.

1. Autentifikavimas

Pirmasis pranešimas po prisijungimo yra autentifikavimas:

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

Taip pat galite siųsti {"access_token": "YOUR_ACCESS_TOKEN"}. Žr. autentifikavimas.

Atsakymas	Reikšmė
[]	Sėkmė
["Access Denied"]	Neteisingas raktas arba žetonas. Serveris uždaro ryšį.
[1,[{},"Rate limit"]]	Per daug prisijungimų per trumpą laiką

Prisijungimų riba: 15 per 60 sekundžių vienam API raktui. 25 per 60 sekundžių vienam prieigos žetonui.

2. Įrenginių prenumerata (SUBSCRIBE)

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

Laukas	Reikšmė
c	SUBSCRIBE
server	Visada true
serialnos	Šio serverio įrenginių serijos numeriai
unsubscribe-others	true: serveris sustabdo ankstesnes šio ryšio prenumeratas

Atsakymas: [2,[{},""]]. Serveris praleidžia įrenginius, prie kurių neturite prieigos. Jis nesiunčia dėl jų klaidos.

Kad sustabdytumėte visas prenumeratas, siųskite [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Būsenos atnaujinimai

Iš karto po prenumeratos serveris siunčia kiekvieno įrenginio dabartinę būseną. Tada jis siunčia atnaujinimą kiekvieną kartą, kai kas nors pasikeičia.

Atnaujinimai yra JSON objektai, ne masyvai:

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

Laukas	Turinys
serialno	Įrenginys
R	Rodmenys, neapdoroti, pagal rodmens kodą
O	Išvesčių reikšmės output_names tvarka
T	Įrenginio tvarkaraščiai
S	Įrenginio nustatymai
previous	Ankstesnio laikotarpio sukauptos reikšmės įrenginiams su skaitikliais
alarms	Aktyvūs aliarmai
is_local	true, jei Jūsų ryšys ir įrenginys yra tame pačiame tinkle

• Atnaujinimas gali turėti tik pasikeitusius laukus. Sujunkite jį su būsena, kurią jau turite.
• Serveris grupuoja pokyčius maždaug 100 ms prieš siųsdamas atnaujinimą.
• Ignoruokite pranešimus, kurių neatpažįstate.

Kad konvertuotumėte neapdorotas reikšmes, naudokite šeimų apibrėžtis. Žr. REST API.

Ryšio palaikymas

• Serveris siunčia WebSocket ping. Jūsų biblioteka turi atsakyti pong. Dauguma bibliotekų tai daro automatiškai.
• Jei ryšys užsidaro, prisijunkite dar kartą. Programėlė pirmą kartą laukia 100 ms, o po to 10 sekundžių.
• Po naujo prisijungimo dar kartą siųskite autentifikavimą ir prenumeratą.

Node.js pavyzdys

Node.js 22 turi integruotą 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);
  }
};

Pilnas Node.js pavyzdys yra faile nodejs_hamapi_example.zip. Jame yra biblioteka hamapi.js ir failas example.js.

1. Faile example.js nustatykite server, api_key ir serijos numerius.
2. Paleiskite npm install, tada node example.js.

Biblioteka neprisijungia dar kartą, kai ryšys užsidaro. Pridėkite tai į savo kodą.

Taip pat žr.

• REST API
• Webhooks iš taisyklių