Downlink — поставить данные в очередь на отправку

Ставит кадр с данными в очередь на отправку устройству. Ответ downlink_data_resp со status: 1 означает «принято в очередь», а не «доставлено»: когда кадр уйдёт в эфир, зависит от класса устройства. Устройству класса A сервер передаёт кадр сразу после его очередного uplink, устройству класса C — сразу после постановки в очередь.

Статус кадра отслеживают по dataId из ответа: сервер присылает сообщения downlink_status, а downlink_ack_req возвращает текущий статус по запросу.

Запрос и ответ: downlink_data_req → downlink_data_resp.
Доступ: с токеном любого уровня — устройства своего приложения и приложений, которые открыли ему доступ.

Запрос

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

Поле	Тип	Описание
cmd	string	downlink_data_req
operation_id	string	Произвольная строка; сервер вернёт её в ответе — по ней сопоставляют запрос и ответ
devEui	string	Обязательно devEui или devAddr. DevEUI устройства, 16 hex-символов
devAddr	string	Обязательно devEui или devAddr. DevAddr устройства, 8 hex-символов
data	string	Обязательно data или object. Полезная нагрузка в hex. Размер — не больше предела из max_dl_data_req
object	object	Обязательно data или object. Данные в виде объекта. Сервер преобразует их в hex кодеком приложения; кодек может сам выбрать fport
fport	uint8	Порт приложения: сервер принимает 0–255, для данных приложения используйте 1–223. По умолчанию 2
ttl	uint32	Сколько секунд кадр может ждать в очереди. По умолчанию 3600 (1 час). Если кадр не успел уйти, он получает статус 8 (Expired)
realTime	bool	Отправить только в ближайшее окно приёма, не позже чем через 2 секунды после запроса; иначе сервер отбросит кадр со статусом 5 (Realtime Late). По умолчанию false
dr	string	Скорость передачи строкой, например SF9BW125. Без поля сервер выбирает скорость сам
freq	float	Частота передачи, МГц, в пределах частотного плана устройства. Без поля сервер выбирает частоту сам
gatewayEui	string	Шлюз для передачи. Учитывается только для устройств класса C
power	uint8	Мощность передачи, дБм, не выше максимума частотного плана. Сервер сейчас значение только проверяет, см. «Что важно знать»
lwClass	uint8	Не используется: сервер берёт класс из настроек устройства

{
    "cmd": "downlink_data_req",
    "operation_id": "xyz",
    "devEui": "6F1E570FFE14DBFC",
    "fport": 2,
    "data": "FFFFFFFFFFFF",
    "ttl": 86400
}

Ответ

Поле	Тип	Описание
cmd	string	downlink_data_resp
operation_id	string	Значение из запроса
status	uint8	1 — кадр поставлен в очередь, 2 — ошибка
dataId	uint32	Идентификатор кадра, от 1 до 4294967295. Нужен для downlink_ack_req и приходит в downlink_status
devEui	string	DevEUI из запроса; null, если устройство задано через devAddr
devAddr	string	DevAddr устройства
time	string	Время постановки в очередь, UTC
dataInQueue	uint8	Всегда 1 — это не длина очереди
error_code, error_text	uint8, string	Только при ошибке, см. ниже

{
    "cmd": "downlink_data_resp",
    "operation_id": "xyz",
    "status": 1,
    "dataId": 3046127811,
    "devEui": "6F1E570FFE14DBFC",
    "devAddr": "78130AE1",
    "time": "2026-10-08 09:15:03",
    "dataInQueue": 1
}

Ошибки

error_code	error_text	Что случилось
1	Device not found	Устройство не найдено или недоступно с вашим токеном
3	подробности ошибки	Неверные данные: operation_id не строка, devEui или devAddr не в hex, переданы оба поля data и object или ни одного, data не в hex, кодек не смог закодировать object
4	Payload max size exceed for current SF	Данные не помещаются в кадр на этой скорости — см. max_dl_data_req
5	Impossible datarate value	В dr скорость, которой нет в частотном плане устройства
6	Frequency must be float	freq — не число
7	Frequency not in band range	freq вне частотного плана устройства
8	—	power — не положительное целое или выше максимума частотного плана

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

• Устройство не подтверждает приём. Кадр уходит как неподтверждаемый (Unconfirmed Data Down). Итоговый статус 3 (Delivered) означает, что шлюз излучил кадр, а не что устройство его приняло. Убедиться, что устройство выполнило команду, можно только по его ответу в uplink.
• Класс A ждёт uplink. Кадр уйдёт после очередного uplink устройства — через минуты или часы, в зависимости от того, как часто оно выходит на связь. Если устройство выходит на связь реже одного раза в час, увеличьте ttl, иначе срок ожидания истечёт раньше, чем кадр уйдёт. До первого uplink после подключения к сети устройство downlink не получит.
• Один кадр на одно окно. После uplink устройство получает один кадр. Если в очереди остались ещё кадры, сервер сообщает об этом устройству флагом FPending. Из очереди первым уходит последний поставленный кадр.
• realTime — для ответа сразу после uplink и для класса C. Флаг имеет смысл в двух случаях: запрос отправлен сразу после получения realtime_data от устройства класса A или кадр предназначен устройству класса C. Опоздавший кадр отбрасывается, а не ждёт следующего окна.
• dr и freq задают параметры передачи для окна, которое выберет сервер. Без них сервер берёт параметры из настроек устройства и частотного плана.
• Класс B сервер пока не поддерживает: такому устройству кадр не будет отправлен.

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

Поля object, ttl и power добавлены в сервер в июне 2026 и в описании v0.17 их нет. Значение power сервер проверяет, но в текущей версии при передаче его не применяет: шлюз использует мощность по умолчанию из частотного плана.

См. также

• Отправка данных на устройство — сценарий целиком и статусы кадра.
• cancel_downlink_req — отозвать запланированные кадры устройства, которые ещё не ушли.