Route device events to your web application

Delivering events and requests to your cloud environment

In order for data from Blecon devices to be delivered to your cloud application, you will need to configure an event route for device events. Event routes allow specific events to be forwarded to a URL of your choosing.

Everything that happens on Blecon is an Event. Events are produced when devices send requests and messages, but also when other things happen, like when the network spots one of your devices.

This guide will show you how to set up an event route to handle request messages and see the result on a external web endpoint.

Set up a Web endpoint

First, you will need to set up a web endpoint for the Blecon service to send events to. For this example we will use https://webhook.site to quickly create a temporary endpoint for testing.

When you visit https://webhook.site, you will see the unique URL that has been created for you:

Click on the URL to copy it to the clipboard. You will use this URL for your event route.

Configure an Event Route

1. In the Network Information page for the network you are configuring, go to the "Event Routes" tab and click the blue "Add route" button.

2. In the URL field, enter your unique URL that you copied above.

3. In the Filter Pattern field enter device.*. This pattern means that all device messages will be handled by this event route.

4. Click the "Add Route" button to finish adding the Event Route

Send a request

Now that an event route is configured, requests sent from the device will be routed to your unique URL at https://webhook.site .

In the Blecon CLI use the request subcommand with a payload. In the example below, we send a 4-byte message with values 4b 1e c0 17 :

$ ./blecon-cli request 4b1ec017
Waiting for connection...
Connected
Terminating connection
Response:

You will see your request appear on the sidebar at https://webhook.site. When you click on the incoming request you can see your payload in the Raw Data window.

Here is a snippet of the data:

"device_id": "64c89eef-9dc1-427d-add0-d98b598adac4",
"payload": "4b1ec017",

Sending a request with a structured data type

Device requests can optionally include a request data type. On the CLI, this is specified using the -x option. If the request data type is application/json the Blecon network will decode the binary data and pass it to your web endpoint.

For example, if you make the request:

./blecon-cli request -t '{ "my message" : "hello cloud!" }' -x application/json

Note that on some terminals you need to quote the command differently. On Windows Command Prompt, try:

blecon-cli request -t "{ \"my message\" : \"hello cloud!\" }" -x application/json

Receiving events at your Event Route URL

The web endpoint will receive an event similar to this:

"device_id": "64c89eef-9dc1-427d-add0-d98b598adac4",
"payload": "7b226d79206d657373616765223a2268656c6c6f20636c6f756421227d",
"converted_payload": {
        "my message": "hello cloud!"
},

If you included a request data type, the network adds a converted_payload field, which contains the decoded payload.

Sending back a response

You will notice that the CLI command still outputs a blank response. Also, if you check the "Recent Events" for your network, you will see a device.request_failed error.

This is because your web integration isn't sending a properly formatted response to the request. Requests are the only event type that require a response. Other events like one-way device messages do not.

Let's fix that now by configuring a response. Like payloads from devices, responses back to the device are sent as bytes encoded as a hexadecimal string. We will send the following 7-byte response: 67 6f 74 20 69 74 21

1. In https://webhook.site, click "Edit" in the toolbar at the top of the page

2. In the popup, set the response content type to application/json

3. In the popup, set the body to {"payload":"676f7420697421"}

Configuration for https://webhook.site URL response

1. Rerun the request from the CLI and you will see the response displayed.

Generating hexadecimal-encoded strings

Below is sample code in various languages to encode binary data as a hexadecimal string suitable for responding to devices.

Node.js

// Encoding a text string
Buffer.from('example text', 'utf8').toString('hex');

// Encoding binary data
data = [ 0xaa, 0xbb, 0xcc, 0xdd ];
Buffer.from(data).toString('hex');

Python

# Encoding text
'example text'.encode('utf-8').hex()

# Encoding binary data
data = b'\xaa\xbb\xcc\xdd'
data.hex()

PHP

// encoding text
bin2hex("example text");

// encoding binary data
$data = pack("C*", 0xaa, 0xbb, 0xcc, 0xdd);
bin2hex($data);

Next Steps

• Read more about events and their format