NAV Navbar
Logo
shell javascript

Introduction

BlueBeacon Gateway is a BlueUp product built with a Raspberry Pi 3. BlueBeacon Gateway is preconfigured with DHCP. Once the IP address has been acquired from the BlueBeacon Gateway, you can use ssh (Putty) to login on the system. The username and password are the defaults for the Raspbian Linux distribution:
username: pi
password: raspberry.

BlueBeacon Gateway implements three services to access beacons data:

  1. a set of REST API to scan and filter the beacons received from the BlueBeacon Gateway
  2. a STREAM mode that uses Socket.io (WebSocket) to get the beacons data in real-time
  3. a STREAM mode that uses raw TCP socket to get the beacons data in real-time

Beacon JSON

{
  "bdaddr" : "c1:fd:a4:3b:48:06",
  "rssi" : -67,
  "timestamp" : "2017-01-09T17:12:29.304Z",
  "model" : 7,
  "serial" : 11175,
  "battery" : 85,
  "ibeacon" : [
    {
      "uuid" : "acfd065ec3c011e39bbe1a514932ac01",
      "major" : 0,
      "minor" : 10375,
      "measuredPower" : -54,
      "accuracy" : 6.612724812700408,
      "proximity" : "far"
    }
  ],
  "eddystone" : { 
    "url" : [
      {
        "measuredPower" : -13,
        "url" : "https://www.blueupbeacons.com"
      }
    ],
    "eid": {
      "measuredPower" : -13,
      "eid" : "3b3c60686ea7c5f2"
    }
  }
}

...

{
  "bdaddr" : "ec:1a:c8:d3:da:79",
  "rssi" : -71,
  "timestamp" : "2017-01-09T17:12:29.286Z",
  "model" : 2,
  "serial" : 14876,
  "battery" : 85,
  "ibeacon" : [
    {
      "uuid" : "acfd065ec3c011e39bbe1a514932ac01",
      "major" : 0,
      "minor" : 14876,
      "measuredPower" : -54,
      "accuracy" : 12.050437809041986,
      "proximity" : "far"
    }
  ],
  "eddystone" : {
    "tlm" : {
      "battery" : 2835,
      "temperature" : 26,
      "adv_counter" : 2200840,
      "sec_counter" : 1127100
    },
    "uid" : [
      {
        "measuredPower" : -13,
        "uid" : "acfd065e1a514932ac01000002014876"
      }
    ]
  }
}

All the APIs on the BlueBeacon Gateway encode the beacons in JSON format. Each beacon has the following fields:

bdaddr: Bluetooth MAC address,

rssi: RSSI, received signal strength,

timestamp: timestamp of the latest packet reception,

model: model number (BlueUp),

serial: serial number (BlueUp),

battery: battery level (BlueUp),

ibeacon: array of iBeacon objects, with the following fields

eddystone: object that represents the Eddystone data, with the following fields

REST API

Receive all beacons

curl "http://<ip_address>/beacons"
$.ajax({
  type: "GET",
  url: "http://<ip_address>/beacons"
})
.done(function(beacons) {
  console.log(JSON.stringify(beacons));
})
.fail(function() {
  console.log("Error");
});

The above command will show a JSON like this:

[
  {
    "bdaddr": "fa:ab:c6:d1:7a:f3",
    "rssi": -84,
    "timestamp": "2017-01-04T10:59:15.538Z",
    "model": 1,
    "serial": 10158,
    "battery": 100,
    "ibeacon": [
      {
        "uuid": "acfd065ec3c011e39bbe1a514932ac01",
        "major": 0,
        "minor": 10158,
        "measuredPower": -62,
        "accuracy": 13.699544862302977,
        "proximity": "far"
      }
    ]
  }
]

HTTP Request

GET http://<ip_address>/beacons

Receive only iBeacons

curl "http://<ip_address>/beacons/ibeacon"
$.ajax({
  type: "GET",
  url: "http://<ip_address>/beacons/ibeacon"
})
.done(function(beacons) {
  console.log(JSON.stringify(beacons));
})
.fail(function() {
  console.log("Error");
});

The above command will show a JSON like this:

[
  {
    "bdaddr": "fa:ab:c6:d1:7a:f3",
    "rssi": -84,
    "timestamp": "2017-01-04T10:59:15.538Z",
    "model": 1,
    "serial": 10158,
    "battery": 100,
    "ibeacon": [
      {
        "uuid": "acfd065ec3c011e39bbe1a514932ac01",
        "major": 0,
        "minor": 10158,
        "measuredPower": -62,
        "accuracy": 13.699544862302977,
        "proximity": "far"
      }
    ]
  }
]

HTTP Request

GET http://<ip_address>/beacons/ibeacon

Filtering iBeacons with UUID

curl "http://<ip_address>/beacons/ibeacon/acfd065ec3c011e39bbe1a514932ac01"
$.ajax({
  type: "GET",
  url: "http://<ip_address>/beacons/ibeacon/acfd065ec3c011e39bbe1a514932ac01"
})
.done(function(beacons) {
  console.log(JSON.stringify(beacons));
})
.fail(function() {
  console.log("Error");
});

The above command will show a JSON like this:

[
  {
    "bdaddr": "fa:ab:c6:d1:7a:f3",
    "rssi": -84,
    "timestamp": "2017-01-04T10:59:15.538Z",
    "model": 1,
    "serial": 10158,
    "battery": 100,
    "ibeacon": [
      {
        "uuid": "acfd065ec3c011e39bbe1a514932ac01",
        "major": 0,
        "minor": 10158,
        "measuredPower": -62,
        "accuracy": 13.699544862302977,
        "proximity": "far"
      }
    ]
  }
]

HTTP Request

GET http://<ip_address>/beacons/ibeacon/acfd065ec3c011e39bbe1a514932ac01

Filtering iBeacons with UUID and Major

curl "http://<ip_address>/beacons/ibeacon/acfd065ec3c011e39bbe1a514932ac01/0"
$.ajax({
  type: "GET",
  url: "http://<ip_address>/beacons/ibeacon/acfd065ec3c011e39bbe1a514932ac01/0"
})
.done(function(beacons) {
  console.log(JSON.stringify(beacons));
})
.fail(function() {
  console.log("Error");
});

The above command will show a JSON like this:

[
  {
    "bdaddr": "fa:ab:c6:d1:7a:f3",
    "rssi": -84,
    "timestamp": "2017-01-04T10:59:15.538Z",
    "model": 1,
    "serial": 10158,
    "battery": 100,
    "ibeacon": [
      {
        "uuid": "acfd065ec3c011e39bbe1a514932ac01",
        "major": 0,
        "minor": 10158,
        "measuredPower": -62,
        "accuracy": 13.699544862302977,
        "proximity": "far"
      }
    ]
  }
]

HTTP Request

GET http://<ip_address>/beacons/ibeacon/acfd065ec3c011e39bbe1a514932ac01/0

Filtering iBeacons with UUID, Major and Minor

curl "http://<ip_address>/beacons/ibeacon/acfd065ec3c011e39bbe1a514932ac01/0/10158"
$.ajax({
  type: "GET",
  url: "http://<ip_address>/beacons/ibeacon/acfd065ec3c011e39bbe1a514932ac01/0/10158"
})
.done(function(beacons) {
  console.log(JSON.stringify(beacons));
})
.fail(function() {
  console.log("Error");
});

The above command will show a JSON like this:

[
  {
    "bdaddr": "fa:ab:c6:d1:7a:f3",
    "rssi": -84,
    "timestamp": "2017-01-04T10:59:15.538Z",
    "model": 1,
    "serial": 10158,
    "battery": 100,
    "ibeacon": [
      {
        "uuid": "acfd065ec3c011e39bbe1a514932ac01",
        "major": 0,
        "minor": 10158,
        "measuredPower": -62,
        "accuracy": 13.699544862302977,
        "proximity": "far"
      }
    ]
  }
]

HTTP Request

GET http://<ip_address>/beacons/ibeacon/acfd065ec3c011e39bbe1a514932ac01/0/10158

Receive only Eddystone

curl "http://<ip_address>/beacons/eddystone"
$.ajax({
  type: "GET",
  url: "http://<ip_address>/beacons/eddystone"
})
.done(function(beacons) {
  console.log(JSON.stringify(beacons));
})
.fail(function() {
  console.log("Error");
});

The above command will show a JSON like this:

[
  {
    "bdaddr": "f4:fd:be:6b:aa:22",
    "rssi": -78,
    "timestamp": "2017-01-04T10:59:15.499Z",
    "model": 5,
    "serial": 99999,
    "battery": 100,
    "eddystone": {
      "url": [
        {
          "measuredPower": -13,
          "url": "https://www.blueupbeacons.com"
        }
      ]
    }
  }
]

HTTP Request

GET http://<ip_address>/beacons/eddystone

Receive only Eddystone URL

curl "http://<ip_address>/beacons/eddystone/url"
$.ajax({
  type: "GET",
  url: "http://<ip_address>/beacons/eddystone/url"
})
.done(function(beacons) {
  console.log(JSON.stringify(beacons));
})
.fail(function() {
  console.log("Error");
});

The above command will show a JSON like this:

[
  {
    "bdaddr": "f4:fd:be:6b:aa:22",
    "rssi": -78,
    "timestamp": "2017-01-04T10:59:15.499Z",
    "model": 5,
    "serial": 99999,
    "battery": 100,
    "eddystone": {
      "url": [
        {
          "measuredPower": -13,
          "url": "https://www.blueupbeacons.com"
        }
      ]
    }
  }
]

HTTP Request

GET http://<ip_address>/beacons/eddystone/url

Receive only Eddystone UID

curl "http://<ip_address>/beacons/eddystone/uid"
$.ajax({
  type: "GET",
  url: "http://<ip_address>/beacons/eddystone/uid"
})
.done(function(beacons) {
  console.log(JSON.stringify(beacons));
})
.fail(function() {
  console.log("Error");
});

The above command will show a JSON like this:

[
  {
    "bdaddr": "ec:1a:c8:d3:da:79",
    "rssi": -62.5,
    "timestamp": "2017-01-04T11:26:23.170Z",
    "model": 2,
    "serial": 14876,
    "battery": 85, 
    "eddystone": {
      "uid": [
        {
          "measuredPower": -13,
          "uid": "acfd065e1a514932ac01000002014876"
        }
      ]
    }
  }
]

HTTP Request

GET http://<ip_address>/beacons/eddystone/uid

Receive only Eddystone TLM

curl "http://<ip_address>/beacons/eddystone/tlm"
$.ajax({
  type: "GET",
  url: "http://<ip_address>/beacons/eddystone/tlm"
})
.done(function(beacons) {
  console.log(JSON.stringify(beacons));
})
.fail(function() {
  console.log("Error");
});

The above command will show a JSON like this:

[
  {
    "bdaddr": "ec:1a:c8:d3:da:79",
    "rssi": -62.5,
    "timestamp": "2017-01-04T11:26:23.170Z",
    "model": 2,
    "serial": 14876,
    "battery": 85,
    "eddystone": {
      "tlm": {
        "battery": 2850,
        "temperature": 26,
        "adv_counter": 1313490,
        "sec_counter": 674335
      }
    }
  }
]

HTTP Request

GET http://<ip_address>/beacons/eddystone/tlm

Receive only Eddystone EID

curl "http://<ip_address>/beacons/eddystone/eid"
$.ajax({
  type: "GET",
  url: "http://<ip_address>/beacons/eddystone/eid"
})
.done(function(beacons) {
  console.log(JSON.stringify(beacons));
})
.fail(function() {
  console.log("Error");
});

The above command will show a JSON like this:

[
  {
    "bdaddr": "c1:fd:a4:3b:48:06",
    "rssi": -67,
    "timestamp": "2017-01-09T17:12:29.304Z",
    "model": 7,
    "serial": 11175,
    "battery": 85,
    "eddystone": {
      "eid": {
        "measuredPower": -13,
        "eid": "3b3c60686ea7c5f2"
      }
    }
  }
]

HTTP Request

GET http://<ip_address>/beacons/eddystone/eid

Filtering Eddystone with URL

curl "http://<ip_address>/beacons/eddystone/url/http%3A%2F%2Fwww.blueupbeacons.com"
$.ajax({
  type: "GET",
  url: "http://<ip_address>/beacons/eddystone/url/http%3A%2F%2Fwww.blueupbeacons.com"
})
.done(function(beacons) {
  console.log(JSON.stringify(beacons));
})
.fail(function() {
  console.log("Error");
});

The above command will show a JSON like this:

[
  {
    "bdaddr": "f4:fd:be:6b:aa:22",
    "rssi": -78,
    "timestamp": "2017-01-04T10:59:15.499Z",
    "model": 5,
    "serial": 99999,
    "battery": 100,
    "eddystone": {
      "url": [
        {
          "measuredPower": -13,
          "url": "https://www.blueupbeacons.com"
        }
      ]
    }
  }
]

HTTP Request

GET http://<ip_address>/beacons/eddystone/url/http%3A%2F%2Fwww.blueupbeacons.com

Filtering Eddystone with UID

curl "http://<ip_address>/beacons/eddystone/uid/acfd065e1a514932ac01000002014876"
$.ajax({
  type: "GET",
  url: "http://<ip_address>/beacons/eddystone/uid/acfd065e1a514932ac01000002014876"
})
.done(function(beacons) {
  console.log(JSON.stringify(beacons));
})
.fail(function() {
  console.log("Error");
});

The above command will show a JSON like this:

[
  {
    "bdaddr": "ec:1a:c8:d3:da:79",
    "rssi": -62.5,
    "timestamp": "2017-01-04T11:26:23.170Z",
    "model": 2,
    "serial": 14876,
    "battery": 85, 
    "eddystone": {
      "uid": [
        {
          "measuredPower": -13,
          "uid": "acfd065e1a514932ac01000002014876"
        }
      ]
    }
  }
]

HTTP Request

GET http://<ip_address>/beacons/eddystone/uid/acfd065e1a514932ac01000002014876

Filtering Eddystone with EID

curl "http://<ip_address>/beacons/eddystone/eid/3b3c60686ea7c5f2"
$.ajax({
  type: "GET",
  url: "http://<ip_address>/beacons/eddystone/eid/3b3c60686ea7c5f2"
})
.done(function(beacons) {
  console.log(JSON.stringify(beacons));
})
.fail(function() {
  console.log("Error");
});

The above command will show a JSON like this:

[
  {
    "bdaddr": "c1:fd:a4:3b:48:06",
    "rssi": -67,
    "timestamp": "2017-01-09T17:12:29.304Z",
    "model": 7,
    "serial": 11175,
    "battery": 85,
    "eddystone": {
      "eid": {
        "measuredPower": -13,
        "eid": "3b3c60686ea7c5f2"
      }
    }
  }
]

HTTP Request

GET http://<ip_address>/beacons/eddystone/eid/3b3c60686ea7c5f2

Socket.io API

Introduction

var socket = io.connect("http://<ip_address>:8081");

socket.on('connect', function() {
  console.log("connected");
});

socket.on('disconnect', function() {
  console.log("disconnected");
});

socket.on('error', function(data) {
  console.log(data);
});

socket.on('beacon', function(beacon) {
  console.log(JSON.stringify(beacon));
}

socket.emit('request', { 'enable' : true });

The code shows an example of how to use the Socket.io client library to connect to the Gateway and enable the data stream.

The Socket.io API uses the WebSocket technology to send a real-time stream of the beacons received by BlueBeacon Gateway.

Each beacon detected by the Gateway is immediately sent to all clients who have enabled the communication channel through Socket.io API.

Server connection

var socket = io.connect("http://<ip_address>:8081");

io.connect("http://<ip_address>:8081")

Enable beacon data streaming

var socket = io.connect("http://<ip_address>:8081");

...

socket.emit('request', { 'enable' : true });

socket.emit('request', { 'enable' : true });

After connecting to the server you need to activate the data stream on the server using the socket.emit() call.

Disable beacon data streaming

...

socket.emit('request', { 'enable' : false });

socket.emit('request', { 'enable' : false });

Enable only iBeacons

var socket = io.connect("http://<ip_address>:8081");

...

socket.emit('request', { 'enable' : true, 'ibeacon' : 'all' });

socket.emit('request', { 'enable' : true, 'ibeacon' : 'all' });

During the activation of the data stream you can also add some filtering parameters. You can enable the reception of only iBeacons by specifying 'iBeacon': 'all' when performing the request.

Filtering iBeacons

var socket = io.connect("http://<ip_address>:8081");

...

// Filtering with UUID
socket.emit('request', { 'enable' : true, 'ibeacon' : { 'uuid' : "acfd065ec3c011e39bbe1a514932ac01" } });

// Filtering with UUID and Major
socket.emit('request', { 'enable' : true, 'ibeacon' : { 'uuid' : "acfd065ec3c011e39bbe1a514932ac01", 'major' : 0 } });

// Filtering with UUID, Major and Minor
socket.emit('request', { 'enable' : true, 'ibeacon' : { 'uuid' : "acfd065ec3c011e39bbe1a514932ac01", 'major' : 0, 'minor' : 10158 } });

You can also filter UUID, Major and Minor iBeacon the package, specifying values.

Enable only Eddystone

var socket = io.connect("http://<ip_address>:8081");

...

socket.emit('request', { 'enable' : true, 'eddystone' : 'all' });

socket.emit('request', { 'enable' : true, 'eddystone' : 'all' });

During the activation of the data stream you can also add some filtering parameters. You can enable the reception of only Eddystone beacons by specifying 'eddystone': 'all' when performing the request.

Filtering Eddystone

var socket = io.connect("http://<ip_address>:8081");

...

// Filtering Eddystone URL
socket.emit('request', { 'enable' : true, 'eddystone' : { 'url' : 'all' } });

// Filtering Eddystone URL with specified URL
socket.emit('request', { 'enable' : true, 'eddystone' : { 'url' : "http://www.blueupbeacons.com" } });

// Filtering Eddystone UID
socket.emit('request', { 'enable' : true, 'eddystone' : { 'uid' : 'all' } });

// Filtering Eddystone UID with specified UID
socket.emit('request', { 'enable' : true, 'eddystone' : { 'uid' : "acfd065e1a514932ac01000002014876" } });

// Filtering Eddystone TLM
socket.emit('request', { 'enable' : true, 'eddystone' : { 'tlm' : 'all' } });

// Filtering Eddystone EID
socket.emit('request', { 'enable' : true, 'eddystone' : { 'eid' : 'all' } });

// Filtering Eddystone EID with specified EID
socket.emit('request', { 'enable' : true, 'eddystone' : { 'eid' : "3b3c60686ea7c5f2" } });

You can also filter URLs, UID, TLM and EID of Eddystone package, specifying values.

TCP API

Introduction

BlueBeacon Gateway also implements a raw TCP server that can be used to enable the beacons data stream (as an alternative to the Socket.io library). TCP server is listening on port 8082.

Connection

nc <ip_address> 8082

To connect to the TCP server you can use command line utilities like netcat on Linux orPutty (also available for Windows).

Enable the data stream

nc <ip_address> 8082
STREAM

Once connected to the server, you must enable the reception of the data stream. The command that you use is STREAM.

Disable the data stream

nc <ip_address> 8082
STOP

To disable the data stream using the command STOP.

Filtering beacons

nc <ip_address> 8082
STREAM /ibeacon

You can choose to filter out the beacon to be received when sending the STREAM command by specifying a path (as in the REST API) for the beacons that you want to receive.

Some examples:

STREAM /ibeacon

STREAM /ibeacon/acfd065ec3c011e39bbe1a514932ac01

STREAM /eddystone

STREAM /eddystone/url

STREAM /eddystone/uid

STREAM /eddystone/uid/acfd065e1a514932ac01000002014876