Blackpoint.io // Developers

# API Reference

There are currently 2 type of connections to send in your data. At the moment the prefered connection is the MQTT API, but you can also use the HTTP API.

# Authentication

# MQTT

The MQTT broker accepts both standard port 1883 and SSL port 8883 connections. Use your public key as username and your MQTT enabled secret API key as password.

Standard connection

mqtt.blackpoint.io port 1883
1

SSL connection

mqtt.blackpoint.io port 8883
1

Make sure you use the topic with your vanity name included like showed below. You can use json or msgpack payload.

Json Topic

data/v1.0/prod/<VANITY>/json
1

MsgPack Topic

data/v1.0/prod/<VANITY>/msgpack
1

# HTTPS

It is possible to send your data by making a POST call to the HTTP API. The server will only accept json payloads with Content-Type = application/json. To make a connection you need to use your secret API key in a header named authorization that you generated in the Blackpoint portal. Send your data with Json payload to the following HTTP url with a POST request and the correct headers.

Data url

https://api.blackpoint.io/api/v1.1/data/prod/json
1

Headers Json payload

  • Content-Type = application/json
  • Authorization = your HTTP enabled API token

WARNING

Use the secret API token in the authorization header. The public key is not used in the HTTP Data API.

# Data API

It is possible to send single or multiple datapoint packets formatted in json. The json formatted packets can also be encoded in MsgPack with the MQTT API. The HTTP API is not supporting this at this moment.

There are 4 types of packets that you can use.

  • SS = Single packet // Single timestamp
  • MM = Multiple packets // Multiple timestamps
  • MS = Multiple packets // Single timestamp
  • SM = Single packet // Multiple timestamps

# SS Packet

In each datapoint packet send to the API the following key values are required. At least the unique identifier, timestamp and data point name are needed to be able to save the data in the database. And an extra value, location or description key is needed to give the packet meaning.

  • u = unique device number (string)
  • t = timestamp in seconds (utc timestamp)
  • n = datapoint name (string)
  • v = value (double)

Additionally it is also possible to use extra keys in the packet described below.

# Optional addition: Description

You can add a string description to the send data. This will be visible as a description comment in the portal.

  • d = description (string)

# Optional addition: Reference

You can add the keys for reference. You can use this if you have multiple sensors of the same type. FE: Multiple Temperature sensors. The server handles them as new sensor, but defines it as an existing data point.

  • r = reference number (int)

# Optional addition: Slave

You can add the keys for slaves. You can use this if you have multiple devices connected to the cloud by one gateway. The data points will be handled as separate devices and the new created device will get a suffix like for example: UNIQUE_NUMBER@SLAVE_ID. This way you can split up your data over multiple devices instead of combining all the data to the one gateway.

  • s = slave id (string)

For example if you have a gateway with multiple device units connected to it over Modbus or Zigbee you can handle these slave devices as individual unique devices. The advantage of adding a slave id instead of creating your own unique device names is that the device slave devices are attached in the database to the master automatically. This way you don’t have to manually connect the slave devices to the master anymore. And you can use the callbacks throught the master.

WARNING

It is important if you want to use this feature that you program the gateway so it will redirect the received callback packet to the slave. FE over modbus.

# Optional addition: Hastags (labels)

You can add a array of hashtags that will be used to connect the device to labels in the database. If the label does not exist, they will be created when the server received the message. After the first packet it is not needed to send in the hashtags again since they are not processed by the server after the creation of the device. Best practise will be to implement a first (registration) packet with the hashtags included. Upon the following packets not to include the hashtags to save data.

  • h = hashtags (string)

WARNING

The label attachment will only happen on the first received packet of a device. So only when the device is registered in the database.

# Optional addition: Location

You can add the location as two extra keys in a key called l = location. Below you see an example of a packet with location data.

  • lt = latitude
  • lg = longitude

There is no need to specify the packet as a SS packet in contrast to the other packet structures like MM, MS and SM where this is required.

{
 "u": "UNIQUE_NUMBER",
 "s": 2,
 "h": ["thermostat"],
 "t": 1507289784,
 "n": "temperature",
 "r": 3,
 "v": 15,
 "d": "some string",
 "l": {
    "lt": 52.167515,
    "lg": 5.614997
   }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# MM packet

In each MM (Multiple packets // Multiple timestamps) packet send to the API the following key values are required and the optional addition keys can be added if needed:

  • u = unique number
  • mm = array with datapoints with different names and different timestamps
  • t = timestamp in seconds
  • n = name​​
  • v = value

An example packet is shown below.

{
 "u": "UNIQUE_NUMBER",
 "mm": [
    {
      "n": "temperature",
      "t": 1508240712,
      "v": 21
   },
   {
      "n": "humidity",
      "t": 1508240713,
      "v": 64
   },
   {
      "n": "co2",
      "t": 1508240714,
      "v": 3000
   }
   ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# MS packet

In each MS (Multiple packets // Single timestamp) packet send to the API the following key values are required and the optional addition keys can be added if needed:

  • u = unique number
  • t = timestamp in seconds
  • ms = array with datapoints with same timestamps
  • n = name​​
  • v = value

An example packet is shown below.

{
 "u": "UNIQUE_NUMBER",
 "t": 1508240712,
 "ms": [
    {
      "n": "temperature",
      "v": 21
   },
   {
      "n": "humidity",
      "v": 64
   },
   {
      "n": "co2",
      "v": 3000
   }
   ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# SM packet

In each SM (Single packet // Multiple timestamps) packet send to the API the following key values are required and the optional addition keys can be added if needed:

  • u = unique number
  • n = name​​
  • sm = array with datapoints with same name
  • t = timestamp in seconds
  • v = value

An example packet is shown below.

{
 "u": "UNIQUE_NUMBER",
 "n": "temperature",
 "sm": [
    {
      "t": 1508240712,
      "v": 1
   },
   {
      "t": 1508240713,
      "v": 1
   },
   {
      "t": 1508240714,
      "v": 1
   }
   ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Callback API

It is possible to send data back to devices. Currently this is only possible for devices that are connected by MQTT and use the Blackpoint communication protocol. This way packets van be send back to a device from the callback widgets on a dashboard or from the data list on the device details.

WARNING

It is important that the data point that you want to send to the device is available in the platform. Besides that it is important that the data point is enabled for callback functionality. This can be done by editing the data point within the portal.

To use the callback functionality of the platform you currently have to use the MQTT API connection. The device has to subscribe to the callback topic to be able to receive packets. The handling of the packets have to be implemented in the embedded firmware of the device.

The packets can be send with json or MsgPack payloads. It depends on the device configuration setting how the data is send to the callback topic.

Json topic

callback/v1.0/prod/<VANITY>/json/device/<UNIQUE_NUMBER>
1

MsgPack topic

callback/v1.0/prod/<VANITY>/msgpack/device/<UNIQUE_NUMBER>
1

# Callback packet

The callback packet has the following key/values:

First the message object:

  • m = message

with a couple of key values:

  • u = unique device number (string)
  • t = timestamp (utc timestamp)
  • n = name of data point (string)
  • r = reference number (default = 0) (int)
  • v = value (not used in a get action) (double)

And an action that can be used to set or get a parameter:

  • a = action (set or get) (string)

TIP

A best practice to see immediately the changed value in the callback widget is to send a single packet back to the data API as confirmation of the received value. This way the set value is directly visualised in the dashboard and live list of the device details. So when the callback topic is called and the device receives this packet on the callback topic it should ping the value right back to its data API to be able to see the changed value directly in the portal.

An example packet is shown below and is send to the callback topic:

Device subscribed to topic

callback/v1.0/prod/<VANITY>/json/device/<SAMPLE_GATEWAY_KDKHYG>
1

Packet

{
   "m":{
      "u":"SAMPLE_GATEWAY_KDKHYG",
      "t":1560424705,
      "n":"TEMPERATURE_SETPOINT",
      "r":0,
      "v":28.5
   },
   "a":"set"
}
1
2
3
4
5
6
7
8
9
10

Directly after the packet is received on the device , it should send back a confirmation to the normal data topic like shown below.

Device published to topic

data/v1.0/prod/<VANITY>/json
1

Packet

{
   "u":"SAMPLE_GATEWAY_KDKHYG",
   "t":1560424715,
   "n":"TEMPERATURE_SETPOINT",
   "r":0,
   "v":28.5
}
1
2
3
4
5
6
7

# Firmware update packet

In case a firmware file is uploaded in the portal, this file can be pushed to the device with the same workflow as a callback packet or callback widget. In this case instead of setting up the workflow yourself inside a widget it can be done directly from the firmware page. The packet will be named FIRMWARE and has a f for firmware. In that atribute there are 2 extra key value's. A d for description where the system will send the uuid plus and e for the extension of the firmware file. After receiving the packet the device can do a normal callback packet with only a d to update the portal so the system can show the last updated file of the target device. The device can ofcorse also send extra firmware packets back to the system when it is upgraded. This is up to the embedded device developer to setup and determine.

The message object:

  • m = message

with a couple of key values:

  • u = unique device number (string)
  • t = timestamp (utc timestamp)
  • n = name of data point (string) always FIRMWARE
  • f = firmware object
    • d = UUID of the uploaded file (string)
    • e = extension of the file (fe zip or bin) (string)

And an action that can be used to set or get a parameter:

  • a = action (set or get) (string)

Device subscribed to topic

callback/v1.0/prod/<VANITY>/json/device/<SAMPLE_GATEWAY_KDKHYG>
1

Packet

{
   "m":{
      "u":"SAMPLE_GATEWAY_KDKHYG",
      "t":1560424705,
      "n":"FIRMWARE",
      "f":{
         "d":"ec004d17-eb49-4af6-971f-73bfcfd78561",
         "e":"zip"
      }
   },
   "a":"set"
}
1
2
3
4
5
6
7
8
9
10
11
12

Once the device has received the FIRMWARE packet it can then download it and use the file according to its internal firmware updating process. It doesnt matter waht kind of file is uploaded and presented to the device. This can be whatever is needed for the device. It can be a zip, paramater CSV file or a bin, etc. The platform will just inform the device of the file so it can be downloaded. The url the device should use to download is based on this structure and the device should use the d in the packet as the UUID in the download link.

Firmware download link

https://<VANITY>.blpt.io/fw/<UUID>
1

# Export API

It is possible to export data from the portal with the Export API. This can be done by you HTTP enabled API token. Use the following API GET call to retreive data from the platform.

# Get data

Send a request to this endpoint to export data from the platform and authenticate with your API token in a authorization header.

Data url

https://api.blackpoint.io/api/v1.1/export/prod/json
1

Headers

  • Authorization = your HTTP enabled API token

WARNING

Use the secret API token in the authorization header. The public key is not used in the HTTP Data API.

Add the following parameters to the request to get data for the right device, datapoint and reference. Make sure you add the aggregation type and time window.

Parameters

You have to add these parameters to get a respons:

  • start_date = timestamp in seconds
  • end_date = timestamp in seconds
  • device = device (optional)
  • datapoint = datapoint (optional)
  • reference = reference number (optional)
  • aggregation = aggregation type
  • page = page number

The aggregation type can be one of the following: none, hour, day, month. The page is used for pagination. This is by default page 1 with a result limit of 1000 rows.