Developers

Customer documentation blukii Hub

In this documentation the api functions of the blukii Hub are described.

Push interface

The blukii Hub received data of all blukii Sensor Beacons or blukii Smart Beacons and sends it to your configured server. You must ensure that your server correctly interprets and processes the data from the blukii Hub. The data is sent from the blukii Hub via a HTTP POST or HTTP PUT interface in JSON format. The following is a structure of a JSON record. The structure of a data record depends on the hardware variant and the configuration of the blukii Sensor Beacon or blukii Smart Beacon. In the example below, the following configuration was used:

blukii Hub
- Serial number: SMAA9ET9WL
blukii Smart Beacon
- blukii_address: CC78AB6FFEBF
- Frames iBeacon, Eddystone UID, Eddystone URL and Eddystone TLM enabled
blukii Sensor Beacon
- blukii_address: CC78AB6FD698
- all sensor readings are sent

Output example of the push interface

{
    "id": "SMAA9ET9WL",
    "data": [
        {
            "blukiiId": "CC78AB6FFEBF",
            "macAddress": "CC78AB6FFEBF",
            "rssi": [
                {
                    "rssi": -55,
                    "timestamp": 1584449211921
                },
                {
                    "rssi": -54,
                    "timestamp": 1584449212522
                },
                {
                    "rssi": -55,
                    "timestamp": 1584449212829
                },
                {
                    "rssi": -56,
                    "timestamp": 1584449212929
                }
            ],
            "iBeaconData": [
                {
                    "uuid": "626C756B-6969-2E63-6F6D-626561636F6E",
                    "major": 3,
                    "minor": 3124,
                    "measuredPower": -57,
                    "timestamp": 1584449211921
                }
            ],
            "eddystoneUID": [
                {
                    "uidNamespace": "626C756B626561636F6E",
                    "uidInstance": "00000003000A",
                    "timestamp": 1584449212522
                }
            ],
            "eddystoneTLM": [
                {
                    "battery": 3000,
                    "temperature": 0,
                    "packets": 38591923,
                    "activeTime": 40524260,
                    "timestamp": 1584449212829
                }
            ],
            "eddystoneURL": [
                {
                    "url": "https://myin.fo/Iuaf8",
                    "timestamp": 1584449212929
                }
            ]
        },
        {
            "blukiiId": "CC78AB6FD698",
            "macAddress": "CC78AB6FD698",
            "type": "SENSOR_BEACON",
            "battery": 94,
            "advInterval": 100,
            "firmware": "003.007",
            "rssi": [
                {
                    "rssi": -59,
                    "timestamp": 1584449212158
                },
                {
                    "rssi": -62,
                    "timestamp": 1584449212470
                },
                {
                    "rssi": -58,
                    "timestamp": 1584449212088
                }
            ],
            "beaconSensorData": {
                "acceleration": [
                    {
                        "x": 551,
                        "y": 988,
                        "z": 457,
                        "timestamp": 1584449212158
                    }
                ],
                "magnetism": [
                    {
                        "x": 1388,
                        "y": -3539,
                        "z": 321,
                        "timestamp": 1584449212470
                    }
                ],
                "environment": [
                    {
                        "airPressure": 954.7,
                        "light": 0,
                        "humidity": 32,
                        "temperature": 21.234375,
                        "timestamp": 1584449212088
                    }
                ]
            }
        }
    ]
}

Basically, a new block is added per blukii from which the Hub receives data. Such a block always consists of:

macAddress: MAC Address of the blukii.
rssi: Returns a list of records with information about the Bluetooth connection.

Depending on the configuration and hardware variant of the blukii, the following parts may be added:

beaconSensorData: Returns a list of data with magnetism, acceleration and/or environment data.
iBeaconData: Returns a list of datasets with the iBeacon Data such as UUID, Major, Minor and measured Power.
eddystoneUID: Returns a list of datasets with uidNamespace and uidInstance.
eddystoneURL: Returns a list of URLs.
eddystoneTLM: Returns a list of datasets with the Eddystone TLM data.

Detailed description of the values

General

"blukiiId": "CC78AB6FD698"
"macAddress": "CC78AB6FD698",
"type": "SENSOR_BEACON",
"battery": 94,
"advInterval": 100,
"firmware": "003.007",

blukiiId: blukii Id of the current blukii. This field is always available.
macAddress: Bluetooth MAC address of the current blukii. This field is always available.
type: The type of the blukii Beacon. Valid values: “SENSOR_BEACON”, “SMART_BEACON”, “UNKNOWN”, “SMART_KEY”. This field is only included, when it was received.
battery: Battery state of the last received Frame. Value is in [%]. This field is only included, when it was received.
advInterval: Advertising interval of the Beacon. This field is only included, when it was received.
firmware: Firmware version of the beacon. This field is only included, when it was received.

Rssi

Rssi contains a list of records, in JSON format, with the following content:

"rssi": [
          {
            "rssi": -55,
            "timestamp": 1584449211921
          },
          {
            "rssi": -57,
            "timestamp": 1584449212829
          }
        ]

timestamp: Time of data acquisition in the form of a Unix timestamp in milliseconds.
rssi: RSSI measured value in [dBm].

The records are sorted in ascending order according to timestamp.

Beacon Sensor Data

"beaconSensorData": [
                      "magnetism": [ ... ],
                      "acceleration": [ ... ],
                      "environment": [ ... ]
]

Entries that are available depending on the configuration of the blukiis:

magnetism: Returns a list of data sets with measured values of the magnetic sensor.
acceleration: Returns a list of data records with measured values of the acceleration sensor.
environment: Returns a list of datasets with environmental metrics such as barometric pressure, light, humidity, and temperature.

Magnetism

Magnetism contains a list of records, in JSON format, with the following content:

"magnetism": [
            {
              "timestamp": 1519734268623,
              "x": 4035,
              "y": -2220,
              "z": 5621
            },
            {
              "timestamp": 1519734266497,
              "x": 4013,
              "y": -2168,
              "z": 5690
            }
          ]

timestamp: Time of data acquisition in the form of a Unix timestamp in milliseconds.
x: Magnetic flux density through the X-axis of the sensor in [mGauss].
y: Magnetic flux density through the Y-axis of the sensor in [mGauss].
z: Magnetic flux density through the Z-axis of the sensor in [mGauss].

The records are sorted in ascending order according to timestamp.

Acceleration

"acceleration": [
                  {
                    "timestamp": 1519734269152,
                    "x": -24,
                    "y": -30,
                    "z": 1167
                  },
                  {
                    "timestamp": 1519734268602,
                    "x": -27,
                    "y": -29,
                    "z": 1172
                  }
                ]

timestamp: Time of data acquisition in the form of a Unix timestamp in milliseconds.
x: acceleration in the X direction in [mg].
y: acceleration in the Y direction in [mg].
z: acceleration in the Z direction in [mg].

The records are sorted in ascending order according to timestamp.

Environment

"environment": [
                  {
                    "timestamp": 1519734268362,
                    "airPressure": 938,
                    "light": 40,
                    "humidity": 14,
                    "temperature": 23.1875
                  },
                  {
                    "timestamp": 1519734267939,
                    "airPressure": 938,
                    "light": 40,
                    "humidity": 14,
                    "temperature": 23.1875
                  }
                ]

timestamp: Time of data acquisition in the form of a Unix timestamp in milliseconds.
airPressure: air pressure in [hPa].
light: Illuminance in [lux].
humidity: Humidity in [%].
temperature: temperature in [°C].

The records are sorted in ascending order according to timestamp.

iBeacon Data

"iBeaconData": [
                  {
                    "uuid": "626C756B-6969-2E63-6F6D-626561636F6E",
                    "major": 3,
                    "minor": 5002,
                    "measuredPower": -57,
                    "timestamp": 1584449212186
                  },
                  {
                    "uuid": "626C756B-6969-2E63-6F6D-626561636F6E",
                    "major": 3,
                    "minor": 5002,
                    "measuredPower": -57,
                    "timestamp": 1584449213186
                  }
                ]

timestamp: Time of data acquisition in the form of a Unix timestamp in milliseconds.
uuid: The uuid of the iBeacon frame.
major: Major value of the iBeacon frame.
minor: Minor value of the iBeacon frame.
measuredPower: Measured power value of the iBeacon frame.

The records are sorted in ascending order according to timestamp.

Eddystone UID

"eddystoneUID": [
                  {
                    "uidNamespace": "F7826DA6BC5B71E0893E",
                    "uidInstance": "7A6C4E51414E",
                    "timestamp": 1584449212635
                  },
                  {
                    "uidNamespace": "F7826DA6BC5B71E0893E",
                    "uidInstance": "7A6C4E51414E",
                    "timestamp": 1584449213635
                  }
                ]

timestamp: Time of data acquisition in the form of a Unix timestamp in milliseconds.
uidNamespace: The 10-byte Namespace ID of the beacon.
uidInstance: The 6-byte Instance ID of the beacon.

The records are sorted in ascending order according to timestamp.

Eddystone URL

"eddystoneURL": [
                  {
                    "url": "https://myin.fo/hgKfM",
                    "timestamp": 1584449212896
                  },
                  {
                    "url": "https://myin.fo/hgKfM",
                    "timestamp": 1584449213896
                  }
                ]

timestamp: Time of data acquisition in the form of a Unix timestamp in milliseconds.
url: The eddystone URL of the beacon.

The records are sorted in ascending order according to timestamp.

Eddystone TLM

"eddystoneTLM": [
                  {
                    "battery": 3000,
                    "temperature": 22.5,
                    "packets": 38589588,
                    "activeTime": 40501320,
                    "timestamp": 1584449212283
                  },
                  {
                    "battery": 3000,
                    "temperature": 22.5,
                    "packets": 38589589,
                    "activeTime": 40501320,
                    "timestamp": 1584449212392
                  }
                ]

timestamp: Time of data acquisition in the form of a Unix timestamp in milliseconds.
battery: The current battery voltage in [mV].
temperature: The beacon temperature in [°C].
packets: Count of advertised frames.
activeTime: Time since powered on or reboot in seconds.

The records are sorted in ascending order according to timestamp.