Date în timp real (WebSocket)

Cu WebSocket primiți măsurătorile și modificările dispozitivelor în momentul în care se produc. Aplicația HAM folosește aceeași conexiune. Pentru o singură măsurătoare, API REST este mai simplu.

Adresă

wss://DEVICE_SERVER:9001

DEVICE_SERVER este valoarea câmpului device_server al fiecărui dispozitiv. O găsiți cu get_user_devices.php.
Dispozitivele unui cont pot fi pe servere diferite. Deschideți o conexiune pentru fiecare server diferit, nu una pentru fiecare dispozitiv.
Portul 9001 trebuie să fie deschis pentru conexiuni de ieșire. Consultați cerințele de rețea.

Formatul mesajelor

Fiecare mesaj pe care îl trimiteți este o matrice JSON:

[command_id, payload]

command_id este un număr întreg. Începeți de la 1 și măriți-l la fiecare mesaj. Răspunsul are același command_id.

Dimensiunea maximă a unui mesaj este 20 KiB. Serverul închide conexiunea dacă trimiteți un mesaj mai mare.

1. Autentificare

Primul mesaj după conectare este autentificarea:

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

Puteți trimite și {"access_token": "YOUR_ACCESS_TOKEN"}. Consultați autentificare.

Răspuns	Semnificație
`[]`	Succes
`["Access Denied"]`	Cheie sau token greșit. Serverul închide conexiunea.
`[1,[{},"Rate limit"]]`	Prea multe conexiuni într-un timp scurt

Limita de conexiuni: 15 pe 60 de secunde pentru o cheie API. 25 pe 60 de secunde pentru un token de acces.

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

Câmp	Semnificație
`c`	`SUBSCRIBE`
`server`	Întotdeauna `true`
`serialnos`	Numerele de serie ale dispozitivelor de pe acest server
`unsubscribe-others`	`true`: serverul oprește abonările anterioare ale acestei conexiuni

Răspuns: [2,[{},""]]. Serverul omite dispozitivele la care nu aveți acces. Nu trimite o eroare pentru ele.

Pentru a opri toate abonările, trimiteți [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Actualizări de stare

Imediat după abonare, serverul trimite starea curentă a fiecărui dispozitiv. Apoi trimite o actualizare de fiecare dată când se schimbă ceva.

Actualizările sunt obiecte JSON, nu matrice:

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

Câmp	Conținut
`serialno`	Dispozitivul
`R`	Măsurătorile, brute, cu codul măsurătorii drept cheie
`O`	Valorile ieșirilor, în ordinea `output_names`
`T`	Programele dispozitivului
`S`	Setările dispozitivului
`previous`	Valorile acumulate ale perioadei anterioare, pentru dispozitive cu contoare
`alarms`	Alarmele active
`is_local`	`true` dacă conexiunea dumneavoastră și dispozitivul sunt în aceeași rețea

O actualizare poate conține numai câmpurile care s-au schimbat. Îmbinați-o în starea pe care o aveți deja.
Serverul grupează modificările timp de aproximativ 100 ms înainte să trimită o actualizare.
Ignorați mesajele pe care nu le recunoașteți.

Pentru a converti valorile brute, folosiți definițiile familiilor. Consultați API REST.

Mențineți conexiunea deschisă

Serverul trimite ping-uri WebSocket. Biblioteca dumneavoastră trebuie să răspundă cu un pong. Majoritatea bibliotecilor fac aceasta automat.
Dacă conexiunea se închide, conectați-vă din nou. Aplicația așteaptă 100 ms prima dată și apoi 10 secunde.
După o conexiune nouă, trimiteți din nou autentificarea și abonarea.

Exemplu Node.js

Node.js 22 are un WebSocket încorporat.

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

Un exemplu complet Node.js este în nodejs_hamapi_example.zip. Conține biblioteca hamapi.js și fișierul example.js.

În example.js, setați server, api_key și numerele de serie.
Rulați npm install, apoi node example.js.

Biblioteca nu se reconectează când conexiunea se închide. Adăugați acest lucru în codul dumneavoastră.

Consultați și

Chat cu suportul