Skip to main content

Downlink — queue data for sending

Queues a data frame for sending to a device. A downlink_data_resp with status: 1 means "accepted into the queue", not "delivered": when the frame goes on air depends on the device class. The server sends the frame to a class A device right after its next uplink, and to a class C device right after queuing.

Track the frame by the dataId from the response: the server sends downlink_status messages, and downlink_ack_req returns the current status on request.

Request and response: downlink_data_req → downlink_data_resp.
Access: a token of any level — the devices of its application and of applications that granted it access.

Request​

Fields not marked as required may be omitted.

FieldTypeDescription
cmdstringdownlink_data_req
operation_idstringAny string; the server returns it in the response to match the request and the response
devEuistringdevEui or devAddr is required. Device DevEUI, 16 hex characters
devAddrstringdevEui or devAddr is required. Device DevAddr, 8 hex characters
datastringdata or object is required. Payload in hex. The size must not exceed the limit from max_dl_data_req
objectobjectdata or object is required. Data as an object. The server converts it to hex with the application codec; the codec may choose fport itself
fportuint8Application port: the server accepts 0–255; use 1–223 for application data. Default 2
ttluint32How many seconds the frame may wait in the queue. Default 3600 (1 hour). A frame that is not sent in time gets status 8 (Expired)
realTimeboolSend only in the nearest receive window, no later than 2 seconds after the request; otherwise the server drops the frame with status 5 (Realtime Late). Default false
drstringData rate as a string, e.g. SF9BW125. Without the field the server chooses the data rate
freqfloatTransmission frequency, MHz, within the device frequency plan. Without the field the server chooses the frequency
gatewayEuistringGateway to transmit through. Applies to class C devices only
poweruint8Transmit power, dBm, not above the frequency plan maximum. The server currently only validates the value, see "Good to know"
lwClassuint8Not used: the server takes the class from the device settings
{
    "cmd": "downlink_data_req",
    "operation_id": "xyz",
    "devEui": "6F1E570FFE14DBFC",
    "fport": 2,
    "data": "FFFFFFFFFFFF",
    "ttl": 86400
}

Response​

FieldTypeDescription
cmdstringdownlink_data_resp
operation_idstringValue from the request
statusuint81 — the frame is queued, 2 — error
dataIduint32Frame identifier, from 1 to 4294967295. Needed for downlink_ack_req and included in downlink_status
devEuistringDevEUI from the request; null if the device was addressed by devAddr
devAddrstringDevice DevAddr
timestringQueuing time, UTC
dataInQueueuint8Always 1 — this is not the queue length
error_code, error_textuint8, stringOnly on error, see below
{
    "cmd": "downlink_data_resp",
    "operation_id": "xyz",
    "status": 1,
    "dataId": 3046127811,
    "devEui": "6F1E570FFE14DBFC",
    "devAddr": "78130AE1",
    "time": "2026-10-08 09:15:03",
    "dataInQueue": 1
}

Errors​

error_codeerror_textWhat happened
1Device not foundThe device was not found or is not available with your token
3error detailsInvalid data: operation_id is not a string, devEui or devAddr is not hex, both data and object are given or neither is, data is not hex, or the codec failed to encode object
4Payload max size exceed for current SFThe data does not fit into a frame at this data rate — see max_dl_data_req
5Impossible datarate valuedr holds a data rate that is not in the device frequency plan
6Frequency must be floatfreq is not a number
7Frequency not in band rangefreq is outside the device frequency plan
8—power is not a positive integer or exceeds the frequency plan maximum

Good to know​

  • The device does not acknowledge reception. The frame is sent as Unconfirmed Data Down. The final status 3 (Delivered) means the gateway radiated the frame, not that the device received it. The only way to make sure the device executed a command is its reply in an uplink.
  • Class A waits for an uplink. The frame goes out after the device's next uplink — minutes or hours later, depending on how often the device reports. If the device reports less often than once an hour, increase ttl; otherwise the frame expires before it goes out. A device receives no downlink before its first uplink after joining the network.
  • One frame per window. After an uplink the device receives one frame. If more frames remain in the queue, the server signals this to the device with the FPending flag. The most recently queued frame leaves the queue first.
  • realTime is for replying right after an uplink and for class C. The flag makes sense in two cases: the request is sent right after receiving realtime_data from a class A device, or the frame is intended for a class C device. A late frame is dropped rather than kept for the next window.
  • dr and freq set the transmission parameters for the window the server chooses. Without them the server takes the parameters from the device settings and the frequency plan.
  • Class B is not supported by the server yet: no frame will be sent to such a device.
Current ONS version

The object, ttl and power fields were added to the server in June 2026 and are not in the v0.17 description. The server validates power, but the current version does not apply it to the transmission: the gateway uses the default power of the frequency plan.

See also​