6: Send message to devkit

In the following chapters you will learn how to send a downlink message from your application via the API of IoT Creator SCS to your devkit asynchronously. Asynchronously means in this context, that your devkit doesn't need to be attached to the network or even switched on while you post the downlink message. The downlink messages are queued in IoT Creators SCS and delivered to the device later on.

Because of the asynchronism of the downlink message delivery process you have to perform the following two tasks:

• Post the downlink message to the API of IoT Creators SCS
• Receive the downlink message on your devkit

Everything inbetween these two operations is handled by IoT Creators and the NB-IoT network and therefore stays easy for you.
How you receive the downlink message on your devkit will be subject of the next chapter Receive message on devkit

Post Downlink Message to the API of IoT Creators SCS

IoT Creators SCS provides an API to post downlink messages to the system and having them delivered asynchronously to the device.

In the simple case IoT Creators waits with the delivery of posted downlink messages for your device to send an uplink message to the IoT Creators. If the device is offline or doesn't send the uplink message IoT Creators queues up to 10 downlink messages. If multiple downlink messages are in the queue when the uplink message of the device arrives at IoT Creators, IoT Creators flushes the queue to the device by sending each second a downlink message.

It has proven itself in practice to encode the payload of uplink and downlink message to a hex string. By this you can make sure that no character or byte pattern in the data are misinterpreted by the processing chain.

The HTTP request to post a hex encoded Hello Device message to the IoT Creators looks like the following:

PUT https://api.scs.iot.telekom.com/m2m/endpoints/<My Device Id>/downlinkMsg/0/data 
Content-Type: application/json
Authorization: Basic base64(<username>:<password>)

{
  "resourceValue" : "48656c6c6f20446576696365"
}

Be aware that you

• need to replace the brackets in the url with your device id such as "IMEI:867997030586266"
• add your base64 encoded authentication string ":" to the Basic authentication in the header.
  For base64 encoding you can use the online tool https://www.base64encode.org/. The encoded base64 version of "myusername:mypassword" is "bXl1c2VybmFtZTpteXBhc3N3b3Jk".

If the downlink message has been posted successfully to the IoT Creators (not to the device) the request returns a 202 HTTP status code with the following body.

{
    "msg": "Accepted", 
    "code": 1002, 
    "requestId": "a6cd40a2-e5bf-4192-8f3f-f801e6ca22f7"
}

In case you are using postman to post the REST request the response would look similar to the following two images.

📘

Beside the simple API function to post messages without any special treatment IoT Creators API provides a function to post binary downlink messages as base64 encoded ones. Additionally there are functions available to post downlink messages to eDRX devices. Those messages are directly delivered to the NB-IoT network and they are not queued in the IoT Creators and not waiting for an uplink message of the device.

In the next chapter you work with your devkit to receive the downlink message which you just posted to the API of IoT Creators SCS.