Introduction

This document describes the format of the JSON data returned from the ScanData Streaming Service, including the details of each field.  It is assumed that the reader is familiar with developing systems that connect to web socket streaming apis and processing JSON messages.

Overview

The Streaming API exposes raw JSON messages that are collected by the Bluvision Cloud.  Developers may use this service to perform their own stream processing on JSON data.  Adapters are connectors that put Bluetooth data into the Bluzone Cloud.  The most common Adapter (and currently the only one supported) is a BluFi.  A typical use case would involve several Bluvision Beeks and one or more BluFi devices.  (Note:  This is an example of an extremely small deployment for development purposes.  Actual production deployments can potentially have many thousands of Beeks and BluFi devices.)  Once deployed and configured, the Streaming API may be used to directly process BLE traffic.  

Bluvision Beeks devices are optimized to send different packet types per use case.  For example, there is a packet type for Light sensors, and a different packet type for iBeacon.  This is done for greater flexibility of deployments as well as optimization of battery and network traffic.  Some deployments may require only light or temperature monitoring while other deployments may need only iBeacon.  Furthermore, each packet type may have different requirements for power and interval.  For example, the Beacon my sample light once every hour but temperature every five minutes.

A single message in the Streaming API maps to a BLE Advertisement Packet.  Every packet will define the Packet Type, Adapter Id, and Timestamp.  Some generic Bluetooth broadcasts may not map to a managed device within the Bluzone Cloud, so there is no guarantee that every packet type will have a unique device identifier. 

Available Packet Types

Note:  Not all packet types may be enabled for all projects, please contact customer support for more details.

Anatomy of a Packet

Messages in the Streaming API are "flattened" for easier processing.  Consumers should parse the "packetType" property first and then handle the message accordingly.

Example Packets

Note:  Properties not supported by the example packet type are omitted.  Fields defined above as "Always Present" should never be null, other fields may be null.

Sample sBv2 Packet

{
    "adapterId": "6",
    "battery": 3600,
    "id": "11310989575814262114",
    "packetType": "sBv2",
    "projectId": 1,
    "rssi": -92,
    "temp": 25.25,
    "time": 5608879,
    "timestamp": "2015-06-19T22:29:31.909Z",
    "version": "1",
    "gid":"01:df:05:2b:ff:d7:4a"
}

Sample iBeacon Packet

{
    "adapterId": "6",
    "id": null,
    "major": 25,
    "measuredPower": -55,
    "minor": 133,
    "packetType": "iBeacon",
    "projectId": 1,
    "rssi": -97,
    "time": null,
    "timestamp": "2015-06-19T22:29:40.416Z",
    "uuid": "2a6b70e5-f974-4d42-911e-d44eff379b95",
    "version": "1",
    "gid":"01:df:05:2b:ff:d7:4a"
}

sLight Packet

{
    "adapterId": "6",
    "id": "12317523928979847176",
    "lums": 648,
    "packetType": "sLight",
    "projectId": 1,
    "time": 1434746811,
    "timestamp": "2015-06-19T20:28:25.229Z",
    "version": "1",
    "gid":"01:df:05:2b:ff:d7:4a"
}

sSns Packet

{
    "adapterId": "6",
    "battery": 2920,
    "eventCounter": [
        15,
        16,
        10,
        12,
        0,
        0
    ],
    "id": "3856557568088208712",
    "packetType": "sSns",
    "projectId": 1,
    "temp": 25.0,
    "time": 16554638,
    "timestamp": "2015-06-19T22:32:06.333Z",
    "version": "1",
    "xAccel": 0,
    "yAccel": 0,
    "zAccel": 1,
    "gid":"01:df:05:2b:ff:d7:4a"
}

unknown Packet

Note:  Implementations should not rely on gid property being populated for unknown packet types.

{
    "adapterId": "6",
    "id": null,
    "packetType": "unknown",
    "projectId": 1,
    "raw": [
        -125,
        -5,
        118,
        98,
        5,
        -39,
        2,
        1,
        6,
        15,
        -1,
        -2,
        -4,
        -86,
        85,
        -59,
        -96,
        -124,
        85,
        109,
        -22,
        -79,
        1,
        -114,
        28
    ],
    "rssi": -78,
    "time": null,
    "timestamp": "2015-06-19T22:29:31.823Z",
    "version": "1",
    "gid":"01:df:05:2b:ff:d7:4a"
}