Developers

blukii Hub JSON API 2.0

In this documentation the JSON API structure 2.0 is described.

Last modified for version: 3.0.5.3.

HTTP Response format

The hub expects the following response data, if the server accepts the JSON data structure.

• Response status codes: 200, 202, 204, 302

• Response content: JSON string, if no content should be sent to hub, then “{}” is expected

Push interface overview

Output example of the push interface

{
  "id": "hub86C274E0",
  "localIp": "192.168.178.41",
  "data": [
    "F05ECD2555ACBB9155263E8F0100006401626C756B69692E636F6D626561636F6E00010001C7",
    "665544332211ADC455263E8F0100006420020100000000000000010080",
    "F05ECD2555ACB8CA56263E8F0100006402CE626C756B626561636F6E000000010001",
    "665544332211ABF856263E8F0100006420020100000000000000010080",
    "F05ECD2555ACB9F257263E8F0100006402CE626C756B626561636F6E000000010001",
    "665544332211AB2558263E8F0100006420020100000000000000010080",
    "F05ECD2555ACB95959263E8F01000064040CEC000000003F510000C06C"
  ]
}

This format contains the raw byte data of each received data frame.

• id: hub ID

• _localIp: IP address in local network

• data: array of received data frames (raw bytes), see coding below

Data frame coding

Common Frame Part

MAC	RSSI	Timestamp	Battery	Type	Content
6 bytes	1 byte	8 bytes	1 byte	1 byte	N bytes

• MAC: 6 bytes array: MAC address of blukii Beacon

• RSSI: 1 signed byte: RSSI measured value in [dBm].

• Timestamp: 8 bytes (unsigned int64 little endian): Time of data acquisition in the form of a Unix timestamp in milliseconds.

• Battery: 1 byte (unsigned int8): Battery percentage.

• Type: 1 byte (unsigned int8): Frame Data Type
  • 0x01: iBeacon
  • 0x02: Eddystone UID
  • 0x04: Eddystone TLM
  • 0x10: Device Tracing
  • 0x20: Special
• Content: Array of N bytes: lenght and data depends on the Frame Data Type, see sections below

The records are sorted in ascending order according to timestamp.

iBeacon Content

Frame Data Type: 0x01

Content Length: 21 Bytes

UUID	Major	Minor	Measured Power
16 bytes	2 bytes	2 bytes	1 byte

• UUID: 16 bytes array: iBeacon UUID

• Major: 2 bytes (unsigned int16 big endian): iBeacon Major

• Minor: 2 bytes (unsigned int16 big endian): iBeacon Minor

• Measured Power: 1 signed byte: iBeacon Measured Power in [dBm].

Eddystone UID Content

Frame Data Type: 0x02

Content Length: 17 Bytes

TxPower	Namespace	Instance
1 byte	10 bytes	6 bytes

• TxPower: 1 signed byte: Eddystone TxPower value in [dBm].

• Namespace: 10 bytes array: Eddystone UID Namespace

• Instance: 6 bytes array: Eddystone UID Instance

Eddystone TLM Content

Frame Data Type: 0x04

Content Length: 12 Bytes

Battery	Temperature	Packets	Active Time
2 bytes	2 bytes	4 bytes	4 bytes

• Battery: 2 bytes (unsigned int16 big endian): Battery capacity in millivolts

• Temperature: 2 bytes float as 8.8 fix-point number (-127..128):
  • Byte 0: Integer part
  • Byte 1: Decimal part: (x/256)
  • Value 0x8000: no temperature sensor available

• Packets: 4 bytes (unsigned int16 big endian): Number of Data Frames the Beacon has sent since startup

• Active Time: 4 bytes (unsigned int16 big endian): Time since startup in 0.1 seconds resolution

Device Tracing Content

Frame Data Type: 0x10

Content Length: 22 Bytes

Device Id	Tracing Set	Frame Index	Found Devices
2 bytes	1 byte	1 byte	16 bytes

• Device Id: 2 bytes (unsigned int16 big endian): Device tracing id of the current blukii (inherited from iBeacon minor value).

• Tracing Set: 1 byte (unsigned int8): Device Tracing Set index that is increased after each scan period.

• Frame Index: 1 byte (unsigned int8): Frame index as part of one Tracing Set.

• Found Devices: List of up to 6 other devices that were scanned in last scan period, see coding below.

Device Tracing Found Devices Content

Id 0	RSSI 0	Id 1	RSSI 1	…	Id 5	RSSI 5
2 bytes	1 byte	2 bytes	1 byte	…	2 bytes	1 byte

• Id n: 2 bytes (unsigned int16 big endian): Device tracing id of the found blukii (inherited from iBeacon minor value).
  • 0xFFFF: less than n+1 device tracing blukiis found
• RSSI n: 1 signed byte: RSSI measured value in [dBm]. of the found blukii (inherited from iBeacon minor value).
  • 0x80: less than n+1 device tracing blukiis found

The Found Devices are sorted according to RSSI value with highest value first.

Special Frame Content

Frame Data Type: 0x20

Content Length: special content defined

Special Type	Special Content
1 byte	N bytes

• Special Type: 1 byte (unsigned int8): Special Frame Data Type

• Content: Array of N bytes: lenght and data depends on the Special Frame Data Type