Handling Requests

This is Part Two of the Getting Started guide, so if you haven't done Part One, head over there now.

Introduction to Device Requests

Blecon routes requests from Bluetooth devices to your web application. You will see device requests appear as HTTP POST requests containing the JSON data from the device.

Your application will need to respond with an HTTP success code, which will tell the device its request has been successful.

The most common type of device request does not require a specific response, however, depending on the request type and the device, your application may need to respond with data in JSON format - for example, if a device makes a request to ask for configuration.

Requests

Example POST request from the KKM S5-BCN Device

{
  "network_headers": {
    "blecon_schema_version": "1.0.0",
    "message_type": "DEVICE_REQUEST",
    "account_id": "24SaTkAywpoQGIu9uHsLWqxIAQ0",
    "network_id": "2FRrXz41pKTzBk2DmIaEyexLXxX",
    "device_id": "795ec33c-636e-4468-957f-14734dd13355",
    "device_location": "52.1252556,0.1611406",
    "device_model_id": "8fd5ca49-cf11-4f93-be22-07125afacdd4",
    "device_schema_version": "0"
  },
  "request_data": {
    "payload": {
      "uptime": 202488,
      "events": [
        {
          "id": 153,
          "timestamp": 23777,
          "type": "MOTION_STOP"
        },
        {
          "id": 154,
          "timestamp": 23780,
          "type": "MOTION_START"
        },
        {
          "id": 155,
          "timestamp": 23783,
          "type": "MOTION_STOP"
        },
        {
          "id": 156,
          "timestamp": 23783,
          "type": "MOTION_VECTOR",
          "data": {
            "x": 918,
            "y": -241,
            "z": -54
          }
        },
        {
          "id": 157,
          "timestamp": 23784,
          "type": "MOTION_START"
        },
        {
          "id": 158,
          "timestamp": 23788,
          "type": "MOTION_STOP"
        },
        {
          "id": 159,
          "timestamp": 23790,
          "type": "MOTION_START"
        },
        {
          "id": 160,
          "timestamp": 23795,
          "type": "MOTION_STOP"
        },
        {
          "id": 161,
          "timestamp": 23798,
          "type": "MOTION_START"
        },
        {
          "id": 162,
          "timestamp": 23803,
          "type": "MOTION_STOP"
        },
        {
          "id": 163,
          "timestamp": 23803,
          "type": "MOTION_VECTOR",
          "data": {
            "x": 916,
            "y": 200,
            "z": -18
          }
        }
      ],
      "battery": 3596
    }
  }
}

Creating a response

For a successful request, your handler must respond to this device's requests with content-type application/json and this JSON document:

{
 "response_data": {}
}

It's a good idea to check your network logs to make sure your response is correctly decoded by the Blecon service.

Prepare your application

Introduction

Blecon is designed for web developers like you, so we won't spend much time explaining how to handle a POST request.

The basic flow your application needs to follow for a Blecon request is as follows:

1. Accept HTTP request on a URL you specify

2. Verify authentication of Blecon request

3. Determine the type of device and request

4. Handle the request, storing data as appropriate for your application

5. Send the request response back to Blecon

Blecon supports any cloud, any web framework and any language, so how you perform the above is up to you.

Creating a request handler

For this tutorial, we will use a simple service designed to show incoming requests called https://webhook.site/. It will create a unique URL for handling device requests.

Head over to https://webhook.site/ now and get your own URL. It should look something like this:

https://webhook.site/#!/a14c4803-8523-46a8-a067-350cf2b52n6f

Configure your network

In the previous step, we created a demonstration URL we can use to accept device requests. The next step is to route device requests to your new URL.

First, open the Blecon Console and navigate to the network you created in the previous Connecting a Device Getting Started section.

Now, open the Handlers tab. Here's where we will set your request handler.

Configuring a handler

Click edit then paste the webhook.site URL you created in the previous step.

For now, we will not use any authentication so leave the Headers section blank.

Hit Save and your network is now configured.

Check for requests

You will recall from the previous section of the Getting Started guide that your device was connected and making requests.

Check on your URL handler at webhook.site

If you open the webhook.site URL that was generated for you, you should start to see requests now being routed to the demonstration request handler you created.

Check your network activity

However, we're not quite finished. If you look at your network you should see something like the following:

Empty response error

Note that requests are still showing an error. This is because although requests are reaching the external endpoint, the URL handler is not returning any content. Blecon requires responses to be valid JSON. Let's fix that now.

Configure Response

Head over to webhook.site again and you should see the configuration screen for your test destination. Click Edit in the top right and the change the response as per the following:

Configuring a response

The response content type must be application/json and the content of the body is an empty JSON document.

Hit save, and now let's look at your network activity again. You should see something like the below, indicating that your device is successfully making requests to your example handler.

Successful requests