Downlink Message

Original message

The following Downlink message must be used by all connections from IoT cloud platforms to ThingPark X IoT Flow, regardless of their types.

{
    "DevEUI_downlink": {
        "Time": "2029-07-10T15:38:46.882+02:00",
        "DevEUI": "0018B20000000B20",
        "FPort": 1,
        "payload_hex": "9e1c4852512000220020e3831071"
    }
}

The following Downlink message also includes optional fields.

{
    "DevEUI_downlink": {
        "Time": "2029-07-10T15:38:46.882+02:00",
        "DevEUI": "0018B20000000B20",
        "FPort": 1,
        "payload": {
            "downMessageType": "SET_PARAM",
            "ackToken": 10,
            "setParameters": {
                "collectionBleFilterType": "EDDYSTONE_UID",
                "collectionBleFilterMain1": 51966,
                "collectionBleFilterMain2": 57005,
                "collectionBleFilterSecValue": 47834,
                "collectionBleFilterSecMask": 47806
            }
        },
        "Confirmed": "1",
        "ValidityTime": "2029-07-10T16:38:46.882+02:00",
        "FlushDownlinkQueue": "1",
        "CorrelationID": "4434704901C7450B",
        "DriverCfg": {
            "app": {
                "pId": "abeeway",
                "mId": "asset-tracker",
                "ver": "2"
            }
        }
    }
}

Important note

There must be the payload field or the payload_hex field, but not both in the same message.

Field	Description
`Time`	ISO 8601 time of the request. Time is mandatory when the Application server authentication has been activated in the AS Profile. In this case the LRC will verify the time deviation between the generation and the reception of the request. The deviation must be lower than Max Time Deviation defined in the AS Profile. Syntax: STRING (ISO date/time).
`DevEUI`	Target device IEEE EUI64 in hexadecimal format (representing 8 octets). Syntax: STRING (Hexadecimal representation).
`FPort`	Target port (in decimal format). Syntax: NUMBER (Unsigned integer: 1..224).
`payload_hex`	The hexadecimal payload. The hexadecimal payload will be encrypted by the LRC cluster if the FCntDn parameter is absent, and if the LRC has been configured with an AppSKey for the specified LoRaWAN® port. Otherwise, the payload must be encrypted by the Application Server according to the LoRaWAN® specification, and the FCntDn parameter must be present. The Application Server encryption uses the downlink counter, which is why the FCntDn query parameter is required in this case. Syntax: STRING (Hexadecimal representation). IMPORTANT This field must not appear if there is already the payload field.
`payload`	The payload is the decoded payload_hex. Syntax: STRING. IMPORTANT This field must not appear if there is already the payload_hex field.
`FCntDn`	The LoRaWAN® Downlink Counter value is used to encrypt the payload. This query parameter is needed only if the Application server (not the LRC) encrypts the payload. If present, FCntDn will be copied in the LoRaWAN® header field FCnt, and the encrypted payload will be copied as-is to the LoRaWAN® downlink frame by the LRC. Only applicable to LoRaWAN® 1.0. Syntax: NUMBER (32 bits unsigned integer).
`AFCntDn`	The LoRaWAN® Applicative Downlink Counter value is used to encrypt the payload. This query parameter is needed only if the Application server (not the LRC) encrypts the payload. If present, AFCntDn will be copied in the LoRaWAN® header field FCnt, and the encrypted payload will be copied as-is to the LoRaWAN® downlink frame by the LRC. Only applicable to LoRaWAN® 1.1. Syntax: NUMBER (32 bits unsigned integer).
`Confirmed`	A value of Confirmed=0 requests transmission of an UNCONFIRMED downlink frame. A value of Confirmed=1 requests transmission of a CONFIRMED downlink frame. Default value is Confirmed=0 (UNCONFIRMED). Support of Confirmed frame transmission is subject to Connectivity plan feature flag ackedDownlinkFrame. If the Confirmed flag is set on the HTTP POST and the device is associated with a Connectivity plan where the ackedDownlinkFrame feature flag is set, the downlink packet is processed. Otherwise the processing is aborted, and a specific error code is returned to the AS in the HTTP response. When targeting a multicast device, only unconfirmed frame is supported. Syntax: NUMBER (Unsigned integer: 0..1).
`FlushDownlinkQueue`	Empties the device AS downlink queue of the device (Boolean). When this parameter is set to FlushDownlinkQueue=1, the AS requests the LRC to purge the AS downlink queue of the device prior to add the downlink payload transported by this HTTP POST. Syntax: NUMBER (Unsigned integer: 0..1).
`ValidityTime`	Associates the AS downlink payload with an expiration date (ISO 8601 timestamp or Duration in seconds) in the device AS downlink queue. If the AS downlink payload has not yet been sent to the device, the AS downlink payload will be discarded by the LRC when the expiration date is reached. Syntax: STRING (ISO date/time) or NUMBER (Unsigned integer).
`AS_ID`	Application Server ID, as provisioned in the AS Profile. AS_ID is mandatory if the Application server authentication has been activated in the AS Profile. In this case, the LRC will check that the Application Server is authorized to send downlink command to the device. Syntax: STRING.
`AS_KEY`	Application Server Key. Syntax: STRING.
`Token`	Security token to sign the downlink frame. Token is mandatory when the Application server authentication has been activated in the AS Profile. Syntax: STRING (256 bits hexadecimal).
`CorrelationID`	64 bits ID used to correlate the downlink frame with the associated downlink frame sent report or multicast summary reports. When this parameter is provided, it is sent back in the associated downlink frame sent report for unicast downlink frame or in the associated multicast summary reports for multicast downlink frame. Syntax: STRING (64 bits hexadecimal).
`RetryIneligibleGateways`	When set to 1 or not provided, non eligible gateways (GPS out of sync for Class B, gateway down for Class B/C…) are retried during each retransmission attempt. When set to 0, non eligible gateways are excluded at the beginning of the multicast campaign and not retried during each retransmission attempt. This parameter is only applicable to multicast downlink transmission. Syntax: NUMBER (Unsigned integer: 0..1).
`Repeated`	Indicates that the muslitcast downlink is a repetition. If the payload is encrypted: The FCntDn or AFCntDn value must be the same as the one used for the previous multicast downlink. If the Payload is not encrypted: The LRC will re-use the previous downlink counter. This parameter is only applicable to multicast downlink transmission. Syntax: NUMBER (32 bits integer: default 0).

Downlink Sent Message

Once the downlink is sent, you should receive the following message, it's not the guarantee that the device received it well.

{
    "DevEUI_downlink_Sent": {
        "Time": "2019-08-22T16:48:02.000+02:00",
        "DevEUI": "0018B20000000D48",
        "FPort": 1,
        "FCntDn": 47,
        "FCntUp": 39,
        "Lrcid": "0000000F",
        "SpFact": 7,
        "SubBand": "G1",
        "Channel": "LC2",
        "Lrrid": "FF0106DE",
        "DeliveryStatus": 0,
        "DeliveryFailedCause1": "B0",
        "DeliveryFailedCause2": "00",
        "DeliveryFailedCause3": "00",
        "CustomerID": "199983788",
        "CustomerData": {
            "alr": {
                "pro": "ADRF/DEMO",
                "ver": "2"
            }
        },
        "TransmissionSlot": 1,
        "Frequency": 868.3,
        "CorrelationID": "4434704901C7450B"
    }
}

warning

TPW users, please make sure that your connectivityPlan options allow it.

Property	Description
`Time`	LRR Timestamp for the packet. Syntax: STRING (ISO date/time)
`DevEUI`	Device unique ID. Syntax: STRING (Hexadecimal representation)
`FPort`	LoRaWAN® FPort used by the device for this packet. Only set if present in the uplink packet. Syntax: NUMBER (Unsigned integer: 0..224)
`FCntDn`	The downlink counter to be used for the next downlink frame. If the downlink queue contains at least one payload encrypted by AS: The reported counter is the highest downlink counter in the downlink queue + 1 Else: The reported counter is the last downlink counter used by the LRC to transmit a downlink + 1 Only applicable to LoRaWAN® 1.0. Syntax: NUMBER (32 bits unsigned integer)
`FCntUp`	The uplink counter for this packet. Syntax: NUMBER (32 bits unsigned integer)
`Lrcid`	ID of the LRC that processed the packet. Syntax: STRING (Hexadecimal representation)
`SpFact`	SF used by the device. Syntax: NUMBER (Unsigned integer: 7..12)
`SubBand`	Sub-band used by the device. Syntax: STRING
`Channel`	LC used by the device. Syntax: STRING ("LC0".."LC255")
`Lrrid`	The ID of the LRR that received the packet with the best SNR. This LRR is flagged as "best LRR". Syntax: STRING (Hexadecimal representation)
`DeliveryStatus`	RF transmission status: 1: Downlink frame was sent over the air (either on RX1 or RX2). This means that the downlink frame was transmitted over the air by the LRR. But the downlink frame may not have been received by the device. 0: Downlink frame was not sent over the air (neither on RX1 nor RX2). The downlink frame is not retransmitted by the network server. Accordingly, the downlink frame will have to be reinitiated by the Application Server. Syntax: NUMBER (Unsigned integer: 0..1)
`DeliveryFailedCause1`	The over the air delivery error cause for RX1 downlink slot. Class A device: Transmission slot busy on RX1: A0: "Radio stopped" A1: "Downlink radio stopped" A3: "Radio busy" A4: "Listen before talk" A5: "Radio board error" Class A device: Received too late for RX1: B0: "Too late for RX1" Class A device: LRC selects RX2: C0: "LRC selected RX2" Class A device: DC or Gateway constraint on RX1: D0: "Duty cycle constraint detected by LRR" DA: "Duty cycle constraint detected by LRC" DB: "Max dwell time constraint detected by the LRC" DE: "DC not allowed by the peering operator" DeliveryFailedCause1 is set to 00 when no error occurs on RX1. Syntax: STRING (Hexadecimal representation)
`DeliveryFailedCause2`	The over the air delivery error cause for RX2 downlink slot. Class A device: Transmission slot busy on RX2: A0: "Radio stopped" A1: "Downlink radio stopped" A3: "Radio busy" A4: "Listen before talk" A5: "Radio board error" Class A device: Received too late for RX2: B0: "Too late for RX2" Class A device: DC or Gateway constraint on RX2: DA: "Duty cycle constraint detected by LRC" DB: "Max dwell time constraint detected by the LRC" DE: "DC not allowed by the peering operator" Class C device: Frame expired before transmission: E0: "Max delay for Class C" (60 seconds) DeliveryFailedCause2 is set to 00 when no error occurs on RX2. Syntax: STRING (Hexadecimal representation)
`DeliveryFailedCause3`	The over the air delivery error cause for downlink ping slot. Class B device: Transmission slot busy on ping slot: A0: "Radio stopped" A1: "Downlink radio stopped" A2: "Ping slot not available" A3: "Radio busy" A4: "Listen before talk" A5: "Radio board error" Class B device: Received too late for ping slot: B0: "Too late for ping slot" Class B device: DC or Gateway constraint on ping slot: D0: "Duty cycle constraint detected by LRR" DA: "Duty cycle constraint detected by LRC" DB: "Max dwell time constraint detected by the LRC" DC: "No GPS-synchronized LRR detected by the LRC" DD: "No LRR connected detected by the LRC" DF: "Wrong NetID" DeliveryFailedCause3 is set to 00 when no error occurs on ping slot. Syntax: STRING (Hexadecimal representation)
`CustomerID`	Customer ID associated to the ThingPark Enterprise account. Syntax: STRING
`CustomerData`	JSON customer data set by provisioning: "loc": administrative location (OPTIONAL) "lat" (latitude) and "lon" (longitude) subattributes. "alr": application layer (OPTIONAL) "pro" (product) and "ver" (version) subattributes. XML Syntax: STRING. JSON Syntax: OBJECT
`TransmissionSlot`	Slot used for downlink frame transmission: 0 (Unknown), 1 (RX1), 2 (RX2) or 3 (Ping Slot). Syntax: NUMBER (Unsigned integer: 0..3)
`Frequency`	Frequency in MHz of the radio channel used to receive the frame. Syntax: NUMBER (Float)
`CorrelationID`	64 bits ID used to correlate the downlink sent. Syntax: STRING (64 bits hexadecimal).

Important Note

For more informations, please refer to the full documentation, check the only endpoint documentation, you can found example and description of all fields.

Downlink Rejected Message

In case the downlink is rejected, you should receive the following message.

{
    "DevEUI_downlink_Rejected": {
        "Time": "2019-08-22T16:48:02.000+02:00",
        "DevEUI": "0018B20000000D48",
        "FPort": 1,
        "DeliveryStatus": 350,
        "DownlinkRejectionCause": "Downlink counter value already used. Expected=1238",
        "CustomerID": "199983788",
        "CorrelationID": "4434704901C7450B"
    }
}

Property	Description
`Time`	LRR Timestamp for the packet. Syntax: STRING (ISO date/time)
`DevEUI`	Device unique ID. Syntax: STRING (Hexadecimal representation)
`FPort`	LoRaWAN® FPort used by the device for this packet. Only set if present in the uplink packet. Syntax: NUMBER (Unsigned integer: 0..224)
`DeliveryStatus`	LRC applicative error code indicating why the downlink was rejected. LRC v1: The HTTP status code returned by the LRC is the applicative code (e.g., `350` for "Downlink counter value already used"). Syntax: NUMBER
`DownlinkRejectionCause`	Human-readable description of the rejection cause. Syntax: STRING
`CustomerID`	Customer ID associated to the ThingPark Enterprise account. Syntax: STRING
`CorrelationID`	64 bits ID used to correlate the downlink sent. Syntax: STRING (64 bits hexadecimal).

Possible `DownlinkRejectionCause` values

The following values are returned by the ThingPark AS to LRC Tunnel API for LoRaWAN® POST /downlink endpoint. The /v2/downlink endpoint is not used by ThingPark X IoT Flow.

DeliveryStatus	DownlinkRejectionCause	Description
`350`	`Invalid DevEUI`	The provided DevEUI does not match an existing device or multicast group.
`350`	`Downlink counter value already used. Expected=<expected counter>`	The downlink counter value was already used, for example due to a race condition with another application server. The expected downlink counter value is provided in the message.
`350`	`Downlink counter value increment too large. Expected=<expected counter>`	The downlink counter value supplied by the application server is much larger than the expected value and was rejected by the LRC. The expected downlink counter value is provided in the message.
`350`	`Confirmed downlink is not authorized for this device`	Confirmed downlink transmission is not authorized because the `ackedDownlinkFrame` feature flag is not available in the connectivity plan associated with the device.
`350`	`Invalid LoRa port`	The LoRaWAN® port is outside the authorized `1..224` range for the tunneling interface.
`350`	`Security Check. AS_ID is mandatory`	The application server authorization is activated for this device and the application must be identified.
`350`	`Security Check. missing timestamp/token`	`Time` and `Token` query parameters are mandatory when application server authentication is activated.
`350`	`Security Check. bad AS_ID`	`AS_ID` is not declared in the database or is not authorized for the targeted device.
`350`	`Security Check. Server Decrypt Error`	The security token is missing or badly formatted.
`350`	`Security Check. malformed ISO8601 time`	`Time` must be an ISO 8601 date/time using the `YYYY-MM-DDThh:mm:ss.s+
`350`	`Security Check. Invalid downlink frame timestamp`	The time deviation between the frame generation by the application server and the reception by the LRC exceeds the maximum deviation configured in the AS profile.
`350`	`Security Check. bad token`	The token was not accepted by the LRC.
`350`	`ValidityTime expired or invalid`	The `ValidityTime` date or duration is incorrectly formatted or invalid, for example because it is in the past.
`350`	`Payload too big or invalid size`	The payload size is greater than 5000 characters or is not a multiple of 2.
`350`	`Downlink transmission disabled`	Downlink transmission is rejected because the `downlinkTransmission` feature flag is missing from the connectivity plan associated with the device.
`350`	`Invalid payload size according to currents DR`	The payload is too big to be transmitted according to the data rate currently used by the device.
`350`	`Invalid CorrelationID. Must be a 64 bits hexadecimal value encoded as string`	The correlation ID must be a 64-bit hexadecimal string.
`350`	`Invalid payload. Must not be empty`	The payload is empty.
`350`	`Payload must be provided encrypted with the downlink counter value`	The payload is provided unencrypted but the LRC cannot encrypt it because the `AppSKey` is not available.
`350`	`Token bucket limit reached`	The downlink packet cannot be sent because the downlink token bucket limit is reached and the `DROP` strategy is used.
`350`	`The DL cannot be sent because the LNS is awaiting an RXParamSetupAns. Please retry in a few seconds.`	The downlink packet cannot be sent because an `RXParamSetupReq` has been sent by the LRC but the `RXParamSetupAns` has not yet been received.
`350`	`The DL cannot be sent because the LNS is awaiting the completion of a Join procedure. Please retry in a few seconds.`	The downlink packet cannot be sent because a Join procedure is in progress. The device must send an uplink packet to complete the Join procedure.
`404`	`No Base Station Available`	No base station near the device is connected.

Sending a Downlink

Open your connection in Thingpark X.
Copy the URL inside the banner saying "You can send your downlink by using the following end-point".

Open a new Postman window. Create a new empty request.
Select POST as the request type, and paste the downlink URL inside the URL bar.

Click on the Body section and paste the downlink body. Then, click on Send.

Go back to your connection. Click on Open ThingPark X IoT Flow.

You should be able to see if the downlink is successful.

Note

For more information about the downlink's content, please refer to the section above.

Payload must be provided encrypted

If you see this message:

"DownlinkRejectionCause" : "Payload must be provided encrypted with the downlink counter value"

You need to provide the FcntDn field in your downlink.

Original message​

Downlink Sent Message​

Downlink Rejected Message​

Possible DownlinkRejectionCause values​

Sending a Downlink​

Payload must be provided encrypted​