Tiešsaistes dati (WebSocket)

Ar WebSocket jūs saņemat ierīču mērījumus un izmaiņas tajā brīdī, kad tās notiek. HAM lietotne izmanto to pašu savienojumu. Vienam mērījumam reizē REST API ir vienkāršāks.

Adrese

wss://DEVICE_SERVER:9001

DEVICE_SERVER ir katras ierīces lauka device_server vērtība. Jūs to atrodat ar get_user_devices.php.
Viena konta ierīces var būt dažādos serveros. Atveriet vienu savienojumu katram atšķirīgam serverim, nevis katrai ierīcei.
Portam 9001 jābūt atvērtam izejošajiem savienojumiem. Skatiet Tīkla prasības (IT nodaļai).

Ziņojuma formāts

Katrs ziņojums, ko jūs sūtāt, ir JSON masīvs:

[command_id, payload]

command_id ir vesels skaitlis. Sāciet ar 1 un palieliniet to ar katru ziņojumu. Atbildei ir tas pats command_id.

Ziņojuma maksimālais izmērs ir 20 KiB. Serveris aizver savienojumu, ja jūs sūtāt lielāku ziņojumu.

1. Autentifikācija

Pirmais ziņojums pēc savienošanas ir autentifikācija:

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

Jūs varat sūtīt arī {"access_token": "YOUR_ACCESS_TOKEN"}. Skatiet autentifikāciju.

Atbilde	Nozīme
`[]`	Sekmīgi
`["Access Denied"]`	Nepareiza atslēga vai marķieris. Serveris aizver savienojumu.
`[1,[{},"Rate limit"]]`	Pārāk daudz savienojumu īsā laikā

Savienojumu limits: 15 uz 60 sekundēm vienai API atslēgai. 25 uz 60 sekundēm vienam piekļuves marķierim.

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

Lauks	Nozīme
`c`	`SUBSCRIBE`
`server`	Vienmēr `true`
`serialnos`	Šī servera ierīču sērijas numuri
`unsubscribe-others`	`true`: serveris aptur šī savienojuma iepriekšējos abonementus

Atbilde: [2,[{},""]]. Serveris izlaiž ierīces, kurām jums nav piekļuves. Tas par tām nesūta kļūdu.

Lai apturētu visus abonementus, sūtiet [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Stāvokļa atjauninājumi

Uzreiz pēc abonēšanas serveris sūta katras ierīces pašreizējo stāvokli. Tad tas sūta atjauninājumu katru reizi, kad kaut kas mainās.

Atjauninājumi ir JSON objekti, nevis masīvi:

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

Lauks	Saturs
`serialno`	Ierīce
`R`	Mērījumi, neapstrādāti, ar mērījuma kodu kā atslēgu
`O`	Izeju vērtības `output_names` secībā
`T`	Ierīces grafiki
`S`	Ierīces iestatījumi
`previous`	Iepriekšējā perioda uzkrātās vērtības ierīcēm ar skaitītājiem
`alarms`	Aktīvās trauksmes
`is_local`	`true`, ja jūsu savienojums un ierīce ir tajā pašā tīklā

Atjauninājumā var būt tikai tie lauki, kas mainījās. Apvienojiet to ar stāvokli, kas jums jau ir.
Serveris grupē izmaiņas apmēram 100 ms, pirms sūta atjauninājumu.
Ignorējiet ziņojumus, ko jūs neatpazīstat.

Lai pārvērstu neapstrādātās vērtības, izmantojiet saimju definīcijas. Skatiet REST API.

Uzturiet savienojumu atvērtu

Serveris sūta WebSocket ping. Jūsu bibliotēkai jāatbild ar pong. Lielākā daļa bibliotēku to dara automātiski.
Ja savienojums aizveras, savienojieties vēlreiz. Lietotne pirmo reizi gaida 100 ms un pēc tam 10 sekundes.
Pēc jauna savienojuma sūtiet autentifikāciju un abonementu vēlreiz.

Node.js piemērs

Node.js 22 ir iebūvēts 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);
  }
};

Pilns Node.js piemērs ir failā nodejs_hamapi_example.zip. Tajā ir bibliotēka hamapi.js un fails example.js.

Failā example.js iestatiet server, api_key un sērijas numurus.
Palaidiet npm install, tad node example.js.

Bibliotēka nesavienojas vēlreiz, kad savienojums aizveras. Pievienojiet to savam kodam.

Skatiet arī

Tērzēt ar atbalstu