Подаци уживо (WebSocket)

Преко WebSocket-а добијате очитавања и промене уређаја у тренутку када се десе. HAM апликација користи исту везу. За једно очитавање у неком тренутку REST API је једноставнији.

Адреса

wss://DEVICE_SERVER:9001

• DEVICE_SERVER је вредност поља device_server сваког уређаја. Добијате је из get_user_devices.php.
• Уређаји једног налога могу да буду на различитим серверима. Отворите једну везу за сваки различит сервер, а не једну за сваки уређај.
• Порт 9001 мора да буде отворен за одлазне везе. Погледајте Мрежни захтеви (за ИТ).

Формат поруке

Свака порука коју шаљете је JSON низ:

[command_id, payload]

command_id је цео број. Почните од 1 и повећајте га са сваком поруком. Одговор има исти command_id.

Највећа величина поруке је 20 KiB. Сервер затвара везу ако пошаљете већу поруку.

1. Аутентификација

Прва порука после повезивања је аутентификација:

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

Можете да пошаљете и {"access_token": "YOUR_ACCESS_TOKEN"}. Погледајте аутентификацију.

Одговор	Значење
[]	Успех
["Access Denied"]	Погрешан кључ или токен. Сервер затвара везу.
[1,[{},"Rate limit"]]	Превише веза за кратко време

Ограничење веза: 15 у 60 секунди за један API кључ. 25 у 60 секунди за један токен за приступ.

2. Претплата на уређаје (SUBSCRIBE)

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

Поље	Значење
c	SUBSCRIBE
server	Увек true
serialnos	Серијски бројеви уређаја на овом серверу
unsubscribe-others	true: сервер зауставља раније претплате ове везе

Одговор: [2,[{},""]]. Сервер прескаче уређаје којима немате приступ. За њих не шаље грешку.

Да зауставите све претплате, пошаљите [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Ажурирања стања

Одмах после претплате сервер шаље тренутно стање сваког уређаја. Затим шаље ажурирање сваки пут када се нешто промени.

Ажурирања су JSON објекти, а не низови:

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

Поље	Садржај
serialno	Уређај
R	Очитавања, сирова, са кодом очитавања као кључем
O	Вредности излаза, по редоследу output_names
T	Распореди уређаја
S	Подешавања уређаја
previous	Сабране вредности претходног периода, за уређаје са бројачима
alarms	Активни аларми
is_local	true ако су ваша веза и уређај на истој мрежи

• Ажурирање може да има само поља која су се променила. Спојите га са стањем које већ имате.
• Сервер групише промене око 100 ms пре него што пошаље ажурирање.
• Занемарите поруке које не препознајете.

За конверзију сирових вредности користите дефиниције породица. Погледајте REST API.

Одржавање везе

• Сервер шаље WebSocket ping поруке. Ваша библиотека мора да одговори са pong. Већина библиотека то ради аутоматски.
• Ако се веза затвори, поново се повежите. Апликација чека 100 ms први пут и 10 секунди после тога.
• После нове везе поново пошаљите аутентификацију и претплату.

Пример за Node.js

Node.js 22 има уграђен 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);
  }
};

Потпун пример за Node.js је у nodejs_hamapi_example.zip. Садржи библиотеку hamapi.js и датотеку example.js.

1. У example.js подесите server, api_key и серијске бројеве.
2. Покрените npm install, затим node example.js.

Библиотека се не повезује поново када се веза затвори. Додајте ово у свој код.

Погледајте и

• REST API
• Webhook позиви из правила