Podaci uživo (WebSocket)

WebSocketom dobivate mjerenja i promjene uređaja u trenutku kada se dogode. HAM aplikacija koristi istu vezu. Za jedno mjerenje odjednom jednostavniji je REST API.

Adresa

wss://DEVICE_SERVER:9001

• DEVICE_SERVER je vrijednost polja device_server svakog uređaja. Pronalazite ga pomoću get_user_devices.php.
• Uređaji jednog računa mogu biti na različitim poslužiteljima. Otvorite jednu vezu za svaki različiti poslužitelj, a ne jednu za svaki uređaj.
• Port 9001 mora biti otvoren za odlazne veze. Pogledajte mrežne zahtjeve.

Format poruke

Svaka poruka koju šaljete je JSON polje:

[command_id, payload]

command_id je cijeli broj. Počnite s 1 i povećavajte ga sa svakom porukom. Odgovor ima isti command_id.

Najveća veličina poruke je 20 KiB. Poslužitelj zatvara vezu ako pošaljete veću poruku.

1. Autentikacija

Prva poruka nakon spajanja je autentikacija:

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

Možete poslati i {"access_token": "YOUR_ACCESS_TOKEN"}. Pogledajte autentikaciju.

Odgovor	Značenje
[]	Uspjeh
["Access Denied"]	Pogrešan ključ ili token. Poslužitelj zatvara vezu.
[1,[{},"Rate limit"]]	Previše veza u kratkom vremenu

Ograničenje veza: 15 u 60 sekundi za jedan API ključ. 25 u 60 sekundi za jedan pristupni token.

2. Pretplata na uređaje (SUBSCRIBE)

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

Polje	Značenje
c	SUBSCRIBE
server	Uvijek true
serialnos	Serijski brojevi uređaja na ovom poslužitelju
unsubscribe-others	true: poslužitelj zaustavlja ranije pretplate ove veze

Odgovor: [2,[{},""]]. Poslužitelj preskače uređaje do kojih nemate pristup. Za njih ne šalje grešku.

Za zaustavljanje svih pretplata pošaljite [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Ažuriranja stanja

Odmah nakon pretplate poslužitelj šalje trenutačno stanje svakog uređaja. Zatim šalje ažuriranje svaki put kada se nešto promijeni.

Ažuriranja su JSON objekti, a ne polja:

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

Polje	Sadržaj
serialno	Uređaj
R	Mjerenja, sirova, po kodu mjerenja
O	Vrijednosti izlaza, redoslijedom output_names
T	Rasporedi uređaja
S	Postavke uređaja
previous	Akumulirane vrijednosti prethodnog razdoblja, za uređaje s brojačima
alarms	Aktivni alarmi
is_local	true ako su vaša veza i uređaj na istoj mreži

• Ažuriranje može imati samo polja koja su se promijenila. Spojite ga sa stanjem koje već imate.
• Poslužitelj grupira promjene oko 100 ms prije slanja ažuriranja.
• Zanemarite poruke koje ne prepoznajete.

Za pretvorbu sirovih vrijednosti koristite definicije obitelji. Pogledajte REST API.

Održavanje veze otvorenom

• Poslužitelj šalje WebSocket pingove. Vaša biblioteka mora odgovoriti pongom. Većina biblioteka to radi automatski.
• Ako se veza zatvori, ponovno se spojite. Aplikacija čeka 100 ms prvi put, a poslije toga 10 sekundi.
• Nakon nove veze ponovno pošaljite autentikaciju i pretplatu.

Primjer za Node.js

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

Potpuni primjer za Node.js nalazi se u nodejs_hamapi_example.zip. Sadrži biblioteku hamapi.js i datoteku example.js.

1. U example.js upišite server, api_key i serijske brojeve.
2. Pokrenite npm install, zatim node example.js.

Biblioteka se ne spaja ponovno kada se veza zatvori. Dodajte to u svoj kod.

Pogledajte i

• REST API
• Webhookovi iz pravila