Handling requests

Device Requests are introduced in Device Communication. These are the requests devices make to your application to either report sensor readings or request information.

They are delivered as an HTTP POST to the URL specified in your Request Handler.

Example of a configured Request Handler in the Console

When Blecon sends a device request to your handler, it delivers a JSON document.

To learn how to use the Request Handler, follow one of our Getting Started guides.

Device request JSON format

A device request JSON document follows the following format:

Network Headers

The network_headers section contains metadata about the device and the network used.

Field	Function
message_type	Type of message, for example, DEVICE_REQUEST
account_id	The account is the mechanism used on Blecon for multi-tenancy. Devices and Networks belong to an Account
network_id	The ID of the network used
device_id	The unique ID of the device
device_location	Location of the device as reported by the nearest Access Point
device_model_id	The device model used.

Request Data

Read on for a look at the request data format.

Example of request

{
  "network_headers": {
    "message_type": "DEVICE_REQUEST",
    "account_id": "2AKvnTJlm4mtAORqiVobHXBV0Fb",
    "network_id": "2AKwJ5REoRZj1h3UsyPpgwI5EyK",
    "device_id": "81eee9a9-fe29-4df7-9b4a-e40b6ac22fe4",
    "device_location": "52.12519110941635,0.16142776655171814",
    "device_model_id: "0"
  },
  "request_data": {
    "payload": "48656c6c6f20426c65636f6e21"
  }
}

As you can see, the device_model_id is 0 and request_data contains a payload field which is the raw bytes from the device in hexadecimal form. This will be what you see from the Blecon modem when building a device and before setting the device model.

Response to Device Requests

The response to a Device Request must always be valid JSON with content-type application/json and status code 200 OK.

{
  "response_data":
   {
    "payload": "48656c6c6f20426c65636f6e21"
   }
}

Authentication of Device Requests

It is good security practice to authenticate requests. To do this, set up your API so it requires an API key in a header. You can then provide that API key when you configure your Handler in the Blecon Console.

Example API key