thing-it-device-ibeacon/README.md

[thing-it-node] Device Plugin for iBeacon Devices.

# thing-it-device-ibeacon

[![NPM](https://nodei.co/npm/thing-it-device-ibeacon.png)](https://nodei.co/npm/thing-it-device-ibeacon/)
[![NPM](https://nodei.co/npm-dl/thing-it-device-ibeacon.png)](https://nodei.co/npm/thing-it-device-ibeacon/)

[thing-it-node] Device Plugin for [iBeacon]()

<img src="https://github.com/marcgille/thing-it-device-ibeacon/blob/master/documentation/images/ibeacon.jpeg" width="40%">

This allows you to configure distributed iBeacons together with other devices by means of [thing-it-node](https://github.com/marcgille/thing-it-node) and [thing-it.com](http://www.thing-it.com).

You may react to low battery levels and initiate workflows to exchange those.

You can also use the BLE functionality of the Gateway Computer hosting the **iBeacon** Device to run a "built-in", virtual beacon (without additional hardware) on that Gateway Computer for which you
can specify **UUID**, **Major**, **Minor** and **Measured Power**.

Additionally, a **Beacon Scanner** Device is provided, which allows you to report arbitrary scanning events for beacons.
Combining the **rssi** values for those and the position of - possibly multiple - of the **Beacon Scanner** Devices configured for 
distributed Gateways with a well-defined position will allow you to perform "tracking of everything".

In addition to using the gateway computer as a beacon scanner, you can also use scanners from BlueUp. To distinguish between gateway and 
BlueUp, use the scannerType Property: 0 stands for built-in, 1 for BlueUp. Other properties that are needed for BlueUp Scanners:
- IP adress 
- update frequency (i.e. how often data is requested from the BlueUp API)

## Installation

### Installation of NodeJS and [thing-it-node]

First, install [nodejs](https://nodejs.org/en/download/) on your computer (e.g. your PC or your Raspberry Pi).

Then install **[thing-it-node]** via

```
npm install -g thing-it-node
```
 
### Initialization and Start of [thing-it-node] 

The **[thing-it-device-ibeacon]** Plugin is installed with **[thing-it-node]**, hence there is no need to install it separately.

The Plugin supports Autodiscovery, hence you only have to create a directory in which you intend to run the configuration, e.g.
 
```
mkdir ~/ibeacon
cd ~/ibeacon
```
and invoke

```
tin init
```

and then start **[thing-it-node]** via

```
tin run
```

Install the **thing-it Mobile App** from the Apple Appstore or Google Play and set it up to connect to **[thing-it-node]** 
locally as described [here](https://thing-it.com/thing-it/#/documentationPanel/mobileClient/connectionModes) or just connect your browser under 
[http://localhost:3001](http://localhost:3001).
 
## Configuration

### Beacon

You may measure the RSSI in 1, 3 and 5 meters distance (e.g. via your Beacon App) and provide the measured values via **Measured Power (1m)**, **Measured Power (3m)** and **Measured Power (5m)**.

This will allow for more accuracy in indoor positioning algorithms.

If you are running a virtual beacon on your Gateway, **Measured Power (1m)** has to be set. Default is -50dB.

With **Surpress Threshold** you can define a value for the RSSI below which no beacon events will be published.

### Beacon Scanner

* **Cumulation Interval (cumulationInterval)** - interval after which cumulated ranging data are submitted independently of all other settings
* **Ranging Interval (rangingInterval)** - interval after which data on a new beacon ranging event is submitted independently of the RSSI change
* **Event Interval (eventInterval)** - interval after which data on a new beacon ranging event is submitted independently of the RSSI change
* **RSSI Threshold (rssiThreshold)** - threshold for the difference in the RSSI in dB for which a new beacon ranging event is submitted
* **Exclude Filter (excludeFilter)** - regular expression filter applied against the UUID/major/minor string to generally exclude beacons from creating events and being counted
* **Include Filter (includeFilter)** - regular expression filter applied against the UUID/major/minor string to generally include beacons (all others are excluded) to creating events and being counted
* **Count Interval (eventInterval)** - interval for which the count of distinct beacons seen is calculated and submitted

Setting state variable **ignoreRangingThrottling** allows to ignore the settings for **eventInterval** and **rssiThreshold**.

## User Interface

The UI for iBeacon Devices shows as follows.

<img src="https://github.com/marcgille/thing-it-device-ibeacon/blob/master/documentation/images/mobile-ui.png" width="60%">

The proximity values are those for the Gateway computer running **[thing-it-node]** and the Bluetooth Adapter connecting to the iBeacon.

Using the **Beacon Scanner** on a Gateway Computer as well as real or virtual beacons you can use [thing-it.com](https://www.thing-it.com) to perform tracking of users
with smart phones (if they are allow you to do so) and equipment (with a beacon attached to it).

<img src="https://github.com/marcgille/thing-it-device-ibeacon/blob/master/documentation/images/user-tracking.png" width="60%">

## Where to go from here ...

After completing the above, you may be interested in

* Configuring additional [Devices](https://www.thing-it.com/thing-it/#/documentationPanel/mobileClient/deviceConfiguration), 
[Groups](https://www.thing-it.com/thing-it/#/documentationPanel/mobileClient/groupConfiguration), 
[Services](https://www.thing-it.com/thing-it/#/documentationPanel/mobileClient/serviceConfiguration), 
[Event Processing](https://www.thing-it.com/thing-it/#/documentationPanel/mobileClient/eventConfiguration), 
[Storyboards](https://www.thing-it.com/thing-it/#/documentationPanel/mobileClient/storyboardConfiguration) and 
[Jobs](https://www.thing-it.com/thing-it/#/documentationPanel/mobileClient/jobConfiguration) via your **[thing-it] Mobile App**.
* Use [thing-it.com](https://www.thing-it.com) to safely connect your Node Box from everywhere, manage complex configurations, store and analyze historical data 
and offer your configurations to others on the **[thing-it] Mesh Market**.
* Explore other Device Plugins like [Philips Hue](https://www.npmjs.com/package/thing-it-device-philips-hue), [Plugwise Smart Switches](https://www.npmjs.com/package/thing-it-device-plugwise) and many more. For a full set of 
Device Plugins search for **thing-it-device** on [npm](https://www.npmjs.com/). Or [write your own Plugins](https://github.com/marcgille/thing-it-node/wiki/Plugin-Development-Concepts).