Дані в реальному часі (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, {"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.

У example.js задайте server, api_key і серійні номери.
Виконайте npm install, потім node example.js.

Бібліотека не підключається знову, коли з’єднання закривається. Додайте це у ваш код.

Див. також

Чат із підтримкою