Send device requests and events to your web service

Delivering events and requests to your cloud environment

For data from Blecon devices to be delivered to your cloud application, you will need to configure an integration that delivers events to the desired destination,

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

This guide will show you how to set up a Webhook Integration to capture requests and forward the result on an external web endpoint.

Set up a reciever 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 Integration

1. Open the network you created in the Blecon Console.

2. Navigate to the Integrations tab, and add a Webhook integration

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

4. Tick both Select Events checkboxes, to capture all event types

5. Click Save to add the integration

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 .

If you are using 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