Данные в реальном времени (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
• Вебхуки из правил