Данни на живо (WebSocket)

С WebSocket получавате измерванията и промените на устройствата в момента, в който се случват. Приложението HAM използва същата връзка. За едно измерване наведнъж REST API е по-лесен.

Адрес

wss://DEVICE_SERVER:9001

• DEVICE_SERVER е стойността на полето device_server на всяко устройство. Намирате я с get_user_devices.php.
• Устройствата на един акаунт може да са на различни сървъри. Отворете по една връзка за всеки различен сървър, не за всяко устройство.
• Порт 9001 трябва да е отворен за изходящи връзки. Вижте Мрежови изисквания (за IT).

Формат на съобщенията

Всяко съобщение, което изпращате, е 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
• Webhooks от правила