Podatki v živo (WebSocket)

Z WebSocket prejmete odčitke in spremembe naprav v trenutku, ko nastanejo. Aplikacija HAM uporablja isto povezavo. Za en odčitek naenkrat je REST API enostavnejši.

Naslov

wss://DEVICE_SERVER:9001

• DEVICE_SERVER je vrednost polja device_server vsake naprave. Najdete ga z get_user_devices.php.
• Naprave enega računa so lahko na različnih strežnikih. Odprite eno povezavo za vsak različen strežnik, ne eno za vsako napravo.
• Vrata 9001 morajo biti odprta za odhodne povezave. Glejte Omrežne zahteve.

Oblika sporočila

Vsako sporočilo, ki ga pošljete, je polje JSON:

[command_id, payload]

command_id je celo število. Začnite z 1 in ga povečajte z vsakim sporočilom. Odgovor ima isti command_id.

Največja velikost sporočila je 20 KiB. Strežnik zapre povezavo, če pošljete večje sporočilo.

1. Overitev

Prvo sporočilo po povezavi je overitev:

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

Pošljete lahko tudi {"access_token": "YOUR_ACCESS_TOKEN"}. Glejte overitev.

Odgovor	Pomen
[]	Uspeh
["Access Denied"]	Napačen ključ ali žeton. Strežnik zapre povezavo.
[1,[{},"Rate limit"]]	Preveč povezav v kratkem času

Omejitev povezav: 15 na 60 sekund za en API ključ. 25 na 60 sekund za en dostopni žeton.

2. Naročnina na naprave (SUBSCRIBE)

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

Polje	Pomen
c	SUBSCRIBE
server	Vedno true
serialnos	Serijske številke naprav na tem strežniku
unsubscribe-others	true: strežnik ustavi prejšnje naročnine te povezave

Odgovor: [2,[{},""]]. Strežnik preskoči naprave, do katerih nimate dostopa. Zanje ne pošlje napake.

Za ustavitev vseh naročnin pošljite [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Posodobitve stanja

Takoj po naročnini strežnik pošlje trenutno stanje vsake naprave. Nato pošlje posodobitev ob vsaki spremembi.

Posodobitve so objekti JSON, ne polja:

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

Polje	Vsebina
serialno	Naprava
R	Odčitki, neobdelani, po kodi odčitka
O	Vrednosti izhodov, v vrstnem redu output_names
T	Urniki naprave
S	Nastavitve naprave
previous	Zbrane vrednosti prejšnjega obdobja, za naprave s števci
alarms	Aktivni alarmi
is_local	true, če sta vaša povezava in naprava v istem omrežju

• Posodobitev ima lahko samo polja, ki so se spremenila. Združite jo s stanjem, ki ga že imate.
• Strežnik zbira spremembe približno 100 ms, preden pošlje posodobitev.
• Prezrite sporočila, ki jih ne prepoznate.

Za pretvorbo neobdelanih vrednosti uporabite definicije družine. Glejte REST API.

Povezavo ohranite odprto

• Strežnik pošilja WebSocket ping. Vaša knjižnica mora odgovoriti s pong. Večina knjižnic to naredi samodejno.
• Če se povezava zapre, se znova povežite. Aplikacija prvič počaka 100 ms, nato 10 sekund.
• Po novi povezavi znova pošljite overitev in naročnino.

Primer za Node.js

Node.js 22 ima vgrajen 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);
  }
};

Popoln primer za Node.js je v nodejs_hamapi_example.zip. Vsebuje knjižnico hamapi.js in datoteko example.js.

1. V example.js nastavite server, api_key in serijske številke.
2. Zaženite npm install, nato node example.js.

Knjižnica se ne poveže znova, ko se povezava zapre. To dodajte v svojo kodo.

Glejte tudi

• REST API
• Webhooki iz pravil