Skip to main content

Отправка данных на устройство

Downlink — это данные от сервера к устройству: команда, новая настройка, ответ на запрос. Отправка асинхронная: сервер принимает кадр в очередь, сразу отвечает идентификатором dataId и передаёт кадр, когда у устройства открыто окно приёма. О том, что стало с кадром дальше, сервер уведомляет отдельными сообщениями.

Когда устройство может принять кадр​

КлассКогда принимаетКогда уйдёт кадр
AТолько в двух коротких окнах (RX1, RX2) сразу после своего uplinkПосле очередного uplink устройства — через минуты или часы
CПриёмник включён постоянноСразу после постановки в очередь
B—Сервер класс B пока не поддерживает

Подробнее о классах — в разделе Классы устройств. Класс конкретного устройства возвращает dev_lw_class_req.

Порядок команд​

  1. Подпишитесь на данные и статусы кадров: consume_req с "downlink_status": true. Флаг учитывается только при оформлении подписки: если соединение уже подписано без него, сначала отпишитесь командой unconsume_req.
  2. Проверьте, поместятся ли данные: max_dl_data_req.
  3. Поставьте кадр в очередь: downlink_data_req. Сохраните dataId из ответа: по нему узнают статус кадра.
  4. Дождитесь сообщения downlink_status с итоговым статусом. Если сообщение не пришло, запросите статус командой downlink_ack_req.
  5. Если кадры ещё не ушли, а отправлять их уже не нужно, отзовите все запланированные кадры устройства: cancel_downlink_req с devEui и "allScheduled": true. Отозвать один кадр по dataId из шага 3 нельзя.

Устройство класса A — кадр ждёт в очереди до очередного uplink:

Устройство класса C — сервер передаёт кадр сразу, не дожидаясь uplink:

Кадр устройству класса C уходит через шлюз, который лучше всех принял последний uplink устройства. Пока устройство после подключения к сети не прислало ни одного uplink, сервер не знает, через какой шлюз передавать, и кадр остаётся в очереди.

Статус кадра​

Статус кадра виден в трёх местах:

  • в сообщении downlink_status, которое сервер присылает сам, если подписка оформлена с "downlink_status": true;
  • в ответе downlink_ack_req — по запросу;
  • в истории get_downlink_data_req — за период.
КодНазваниеЧто значитИтоговый
0ScheduledКадр в очереди, ждёт окна приёманет
4Realtime ScheduledКадр с realTime ждёт ближайшего окнанет
1SentКадр передан шлюзу, сервер ждёт подтверждения передачинет
14DC LimitИсчерпан бюджет эфирного времени шлюза; кадр остался в очереди и уйдёт позженет
3DeliveredШлюз излучил кадр. Это подтверждение от шлюза, а не от устройствада
2LateШлюз отклонил кадр: слишком поздно для окна приёмада
9Too EarlyШлюз отклонил кадр: слишком рано для передачида
10CollisionШлюз отклонил кадр: на это время уже запланирована другая передачада
11TX Freq RejectedШлюз не поддерживает частоту передачида
12TX Power RejectedШлюз не поддерживает мощность передачида
13GPS UnlockedШлюз без GPS-синхронизации не может передать в назначенное времяда
7TX_ACK TimeoutШлюз не подтвердил передачу за 10 секундда
5Realtime LateКадр с realTime не успел в окно за 2 секунды и отброшенда
8ExpiredИстёк ttl (по умолчанию 1 час) — кадр отброшенда
6CanceledКадр отозван командой cancel_downlink_req или downlink_purge_reqда

Сервер присылает его при каждой смене статуса, кроме постановки в очередь (0 и 4) и отзыва (6).

  • Статусы приходят в приложение, которому принадлежит устройство, — по кадрам, отправленным любым способом, не только через WebSocket API.
  • Очередь статусов одна на приложение. Если подписано несколько соединений одного приложения, каждое сообщение получит только одно из них — так же, как сообщения realtime_data.
  • Неполученные сообщения сервер хранит 5 минут. Если соединения не было дольше, запросите статус командой downlink_ack_req.
  • В текущей версии сервера подписка на статусы не снимается при отписке и закрытии соединения, поэтому после переподключения часть сообщений downlink_status может не дойти. Итоговый статус важных кадров проверяйте командой downlink_ack_req.
ПолеТипОписание
cmdstringdownlink_status
devEui, devAddrstringУстройство
dataIduint32Идентификатор кадра из downlink_data_resp
downlink_statusuint8Код статуса, см. таблицу выше
downlink_status_textstringНазвание статуса
downlink_status_timestringКогда статус установлен, UTC, ISO 8601
emit_tsstringКогда сервер отправил сообщение, UTC, ISO 8601. Помогает упорядочить сообщения, если они пришли не по порядку
{
    "cmd": "downlink_status",
    "devEui": "6F1E570FFE14DBFC",
    "devAddr": "78130AE1",
    "dataId": 3046127811,
    "downlink_status": 3,
    "downlink_status_text": "Delivered",
    "downlink_status_time": "2026-10-08T09:47:21.402113+00:00",
    "emit_ts": "2026-10-08T09:47:21.415870+00:00"
}

Если кадр не дошёл​

СтатусЧто сделать
8 ExpiredУстройство не выходило на связь, пока кадр ждал. Увеличьте ttl до интервала, с которым устройство присылает uplink, с запасом
5 Realtime LateОкно приёма не открылось за 2 секунды. Для отложенной отправки не ставьте realTime
2 Late, 9 Too Early, 10 CollisionШлюз не смог передать в назначенное время. Отправьте кадр повторно
11 TX Freq RejectedЧастота передачи не подходит шлюзу. Уберите freq из запроса или проверьте частотный план устройства
12 TX Power RejectedМощность передачи не подходит шлюзу. Проверьте частотный план устройства и настройки шлюза
13 GPS UnlockedПроверьте GPS-антенну и синхронизацию шлюза
7 TX_ACK TimeoutПроверьте связь шлюза с сервером
14 DC LimitНичего делать не нужно: кадр остался в очереди и уйдёт позже

Устройство приём кадра не подтверждает: сервер отправляет кадры неподтверждаемыми (Unconfirmed Data Down). Убедиться, что устройство выполнило команду, можно только по его ответу в uplink.

Команды группы​

КомандаЗачем
dev_lw_class_reqУзнать класс устройства — от него зависит, когда уйдёт кадр
max_dl_data_reqУзнать, сколько байт поместится в кадр
downlink_data_reqПоставить кадр в очередь
downlink_ack_reqУзнать статус кадра по запросу
cancel_downlink_reqОтозвать запланированные кадры устройства, которые ещё не ушли
downlink_purge_reqОчистить очередь устройства: отменить кадры в статусе 0 (токен высокого уровня)