Reaalajas andmed (WebSocket)

WebSocketi abil saate seadmete näidud ja muutused nende toimumise hetkel. HAM rakendus kasutab sama ühendust. Ühe näidu korraga saamiseks on REST API lihtsam.

Aadress

wss://DEVICE_SERVER:9001

DEVICE_SERVER on iga seadme välja device_server väärtus. Selle leiate päringuga get_user_devices.php.
Ühe konto seadmed võivad olla erinevates serverites. Avage üks ühendus iga erineva serveri jaoks, mitte iga seadme jaoks.
Port 9001 peab olema väljaminevatele ühendustele avatud. Vaadake võrgunõuded.

Sõnumi vorming

Iga sõnum, mille saadate, on JSON massiiv:

[command_id, payload]

command_id on täisarv. Alustage väärtusest 1 ja suurendage seda iga sõnumiga. Vastusel on sama command_id.

Sõnumi maksimaalne suurus on 20 KiB. Kui saadate suurema sõnumi, sulgeb server ühenduse.

1. Autentimine

Esimene sõnum pärast ühendust on autentimine:

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

Võite saata ka {"access_token": "YOUR_ACCESS_TOKEN"}. Vaadake autentimine.

Vastus	Tähendus
`[]`	Õnnestus
`["Access Denied"]`	Vale võti või juurdepääsuluba. Server sulgeb ühenduse.
`[1,[{},"Rate limit"]]`	Liiga palju ühendusi lühikese aja jooksul

Ühenduste piirang: 15 iga 60 sekundi kohta ühe API võtme jaoks. 25 iga 60 sekundi kohta ühe juurdepääsuloa jaoks.

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

Väli	Tähendus
`c`	`SUBSCRIBE`
`server`	Alati `true`
`serialnos`	Selle serveri seadmete seerianumbrid
`unsubscribe-others`	`true`: server lõpetab selle ühenduse varasemad tellimused

Vastus: [2,[{},""]]. Server jätab vahele seadmed, millele teil ei ole juurdepääsu. Nende kohta see viga ei saada.

Kõigi tellimuste lõpetamiseks saatke [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Oleku uuendused

Kohe pärast tellimist saadab server iga seadme praeguse oleku. Seejärel saadab see uuenduse iga kord, kui midagi muutub.

Uuendused on JSON objektid, mitte massiivid:

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

Väli	Sisu
`serialno`	Seade
`R`	Näidud, töötlemata, võtmeks näidu kood
`O`	Väljundite väärtused, `output_names` järjekorras
`T`	Seadme ajakavad
`S`	Seadme sätted
`previous`	Eelmise perioodi kogunenud väärtused loenduritega seadmete jaoks
`alarms`	Aktiivsed alarmid
`is_local`	`true`, kui teie ühendus ja seade on samas võrgus

Uuendusel võivad olla ainult muutunud väljad. Ühendage see olekuga, mis teil juba on.
Server kogub muutusi umbes 100 ms enne, kui saadab uuenduse.
Eirake sõnumeid, mida te ei tunne.

Töötlemata väärtuste teisendamiseks kasutage perekondade definitsioone. Vaadake REST API.

Hoidke ühendus avatuna

Server saadab WebSocketi pinge. Teie teek peab vastama pongiga. Enamik teeke teeb seda automaatselt.
Kui ühendus sulgub, ühenduge uuesti. Rakendus ootab esimesel korral 100 ms ja seejärel 10 sekundit.
Pärast uut ühendust saatke uuesti autentimine ja tellimus.

Node.js näide

Node.js 22 sisaldab sisseehitatud WebSocket-i.

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

Täielik Node.js näide on failis nodejs_hamapi_example.zip. See sisaldab teeki hamapi.js ja faili example.js.

Määrake failis example.js väärtused server, api_key ja seerianumbrid.
Käivitage npm install, seejärel node example.js.

Teek ei ühendu uuesti, kui ühendus sulgub. Lisage see oma koodi.

Vaadake ka

Vestle toega