Подписаться на данные в реальном времени

Подписывает соединение на данные устройств. После подписки сервер присылает сообщение realtime_data на каждый принятый uplink — подтверждаемый и неподтверждаемый. Приходят данные устройств приложения, к которому выполнено подключение, и приложений, которые открыли ему доступ.

Пока у приложения нет подписанных соединений, сервер копит его данные в очереди и присылает их после подписки. Поэтому после переподключения придут и те uplink, которые сервер принял, пока клиент был отключён.

С флагом "downlink_status": true сервер присылает ещё и сообщения downlink_status о статусе отправленных кадров downlink.

Запрос и ответ: consume_req → consume_resp, затем сообщения realtime_data.
Доступ: токен любого уровня. Уровень токена на поток данных не влияет.

Текущая версия ONS

Флага downlink_status в описании v0.17 нет.
В consume_resp приходит operation_id из запроса.
Состав realtime_data изменился. Новые поля: battery_level, margin, join_request_time, а внутри data — packet_loss_rate, tags и результат JS-кодека (execResult, execError). Поля status, data.id и data.gateway_available из примера v0.17 сервер не присылает. data.time приходит в формате ISO 8601 без часового пояса, а не 2018-02-17 13:06:22+0000.

Запрос

Поля без пометки «обязательно» можно не передавать.

Поле	Тип	Описание
`cmd`	string	`consume_req`
`operation_id`	string	Произвольная строка; сервер вернёт её в ответе — по ней сопоставляют запрос и ответ
`downlink_status`	bool	`true` — присылать ещё и сообщения `downlink_status`. По умолчанию `false`

{
    "cmd": "consume_req",
    "operation_id": "sub1",
    "downlink_status": true
}

Ответ

Поле	Тип	Описание
`cmd`	string	`consume_resp`
`operation_id`	string	Значение из запроса
`status`	uint8	1 — соединение подписано, 2 — ошибка
`consumer_count`	uint16	Сколько соединений приложения подписано, считая это. При ошибке 1 — сколько подписано сейчас; при ошибках 2 и 3 поля нет
`error_code`, `error_text`	uint8, string	Только при ошибке, см. ниже

{
    "cmd": "consume_resp",
    "operation_id": "sub1",
    "status": 1,
    "consumer_count": 1
}

Ошибки

`error_code`	`error_text`	Что случилось
1	Consumer limit reached	У приложения уже подписано максимальное число соединений. Найдите лишние командой `connections_list` и отключите их или отпишите
2	Already consumed	Это соединение уже подписано: раньше командой `consume_req` или автоматически при подключении
3	Disabled application	У приложения не осталось ни одного неотозванного токена — например, токены отозвали после подключения

Сообщение `realtime_data`

Поле	Тип	Описание
`cmd`	string	`realtime_data`
`devEui`	string	DevEUI устройства
`devAddr`	string	DevAddr устройства
`data`	object	Кадр и параметры приёма, см. ниже
`battery_level`	float	Заряд батареи из последнего ответа устройства на запрос статуса (DevStatusAns): 0 — внешнее питание, 255 — устройство не может измерить заряд, иначе — проценты, от 0,4 до 100. `null`, пока сервер не получил такой ответ
`margin`	int8	Запас по SNR из того же ответа, дБ, от −32 до 31. `null`, пока сервер не получил ответ
`join_request_time`	string	Время последнего Join Request устройства по часам шлюза, UTC, ISO 8601. `null`, если сервер не видел активации (join) устройства, например у ABP-устройства

Поля data:

Поле	Тип	Описание
`fcnt`	uint32	Счётчик кадров uplink
`fport`	int16	Порт приложения. 0 — в `data` MAC-команды; −1 — в кадре нет порта и данных
`data`	string	Полезная нагрузка в hex, уже расшифрованная
`mtype`	uint8	Тип кадра: 2 — неподтверждаемый (Unconfirmed Data Up), 4 — подтверждаемый (Confirmed Data Up)
`adr`	bool	У устройства включён ADR (бит ADR в заголовке кадра)
`ack`	bool	Устройство запросило подтверждение ADR (бит ADRACKReq). Это не подтверждение downlink
`fopts`	string	MAC-команды из поля FOpts в hex; пустая строка, если их нет
`datr`	uint8	Номер скорости передачи (DR) в частотном плане устройства
`freq`	float	Частота приёма, МГц
`rssi`	int16	RSSI, дБм
`lsnr`	float	SNR, дБ
`size`	uint16	Размер принятого кадра LoRaWAN целиком (PHYPayload), байт
`time`	string	Время приёма по часам шлюза, UTC, ISO 8601 без часового пояса, например `2026-10-08T09:47:18.528002`
`gatewayId`	string	EUI шлюза, через который сервер принял кадр, 16 hex-символов
`packet_loss_rate`	float	Потери кадров по пропускам счётчика `fcnt` за последние 20 uplink, %
`tags`	object	Теги приложения и устройства; при совпадении ключей действует тег устройства. Пустой объект, если тегов нет
`execResult`	object	Только если у приложения настроен JS-кодек. Результат `decodeUplink`: `data` — разобранные данные, `errors` и `warnings` — сообщения кодека. `null`, если кодек завершился ошибкой
`execError`	string	Только с JS-кодеком: текст ошибки кодека или `null`, если ошибки нет

{
    "cmd": "realtime_data",
    "devEui": "6F1E570FFE14DBFC",
    "devAddr": "78130AE1",
    "data": {
        "datr": 5,
        "rssi": -97,
        "lsnr": 8.5,
        "data": "0A1B2C3D4E5F6071",
        "freq": 868.9,
        "time": "2026-10-08T09:47:18.528002",
        "ack": false,
        "size": 21,
        "gatewayId": "0000B827EBFD64DE",
        "adr": true,
        "fcnt": 1542,
        "mtype": 2,
        "fopts": "",
        "fport": 2,
        "packet_loss_rate": 0,
        "execResult": {
            "errors": [],
            "warnings": [],
            "data": {
                "temperature": 21.5
            }
        },
        "execError": null,
        "tags": {
            "building": "A"
        }
    },
    "battery_level": 100.0,
    "margin": 9,
    "join_request_time": "2026-10-01T06:12:40.114233Z"
}

Что важно знать

Одна очередь на приложение. Если подписано несколько соединений одного приложения, каждое сообщение realtime_data получит только одно из них: сервер раздаёт сообщения соединениям поочерёдно. Чтобы один клиент получал все данные, держите одно подписанное соединение на приложение.
Данные копятся, пока никто не подписан. Uplink, пришедшие без подписчиков, сервер хранит и присылает после подписки — сначала накопленные, потом новые. По умолчанию очередь удаляется вместе с данными, если на неё 14 дней никто не подписывался.
При обрыве сообщение может потеряться. Сервер считает сообщение доставленным, как только отправил его в соединение. Если соединение в этот момент оборвалось, сообщение в очередь не вернётся. Пропущенное можно забрать командой get_data_req.
Подписка живёт, пока открыто соединение. После переподключения подпишитесь снова.
Автоподписка. Если в настройках приложения включена автоподписка, сервер подписывает соединение сам сразу после connected и присылает consume_resp без operation_id. Тогда на consume_req сервер ответит ошибкой 2. Автоподписка не включает downlink_status: чтобы получать статусы, отпишитесь командой unconsume_req и подпишитесь снова с "downlink_status": true.
Флаг downlink_status учитывается только при оформлении подписки. Если соединение уже подписано без него, сначала отпишитесь командой unconsume_req.

См. также

unconsume_req — отписаться от данных.
Отправка данных на устройство — сообщения downlink_status и ответ устройству после его uplink.
get_data_req — данные устройств за период, если сообщения пропущены.

Запрос​

Ответ​

Ошибки​

Сообщение realtime_data​

Что важно знать​

См. также​