Introduction

This tutorial will walk you through how to write a program that can import data about your environments into the Flare server.

The Flare sever comes with an import.js script that you can run on the command line on the server. It reads some Flare objects from a JSON file and imports them directly into the database. See the server page for instructions on getting the server up and running and importing data server-side.

This tutorial will walk you through writing a script that can do the same thing client-side. It will read the same JSON file and call the API.

Using the buttons at the top of the column to the right, you can see the raw API calls and JSON objects, or follow along with code samples in each of the supported languages.

To import your own data, you can:

• modify the JSON file with a description of your own environments
• modify one of the import scripts to connect to your own data source
• write your own script in the language of your choice that calls the API

See the environments page for a detailed description of the Flare object model, and other ways of importing data into the server.

See the import script included with each sample code project for a complete solution.

Dependencies

<script src="js/socket.io-1.0.0.js"></script>
<script src="js/jquery-2.1.4.min.js"></script>
<script src="js/flare.js"></script>

import Cocoa
import Flare

java

import flare
import json

Start by importing these dependencies.

Data source

open the model.json file

var filename = './model.json';

$.getJSON(filename, function(data) {
    var environments = data.environments;
    for (var i = 0; i < environments.length; i++) {
        importEnvironment(environments[i]);
    }
});

let flareManager = FlareManager(host: "localhost", port: 1234)
let filename = "model"

func importData() {
    if let path = NSBundle.mainBundle().pathForResource(filename, ofType: "json"),
        contents = NSData(contentsOfFile: path),
        json = NSJSONSerialization.JSONObjectWithData(contents, options: nil, error: nil) as? JSONDictionary,
        environments = json["environments"] as? JSONArray
    {
        for environment in environments {
            self.importEnvironment(environment)
        }
    }
}

java

def importData():
    with open("model.json") as json_file:
        data = json.load(json_file)

        for environment in data.get('environments', []):
            importEnvironment(environment)

Open the JSON file, which contains a hierarchical outline of Flare objects. Iterate over the environments array, and call the importEnvironment function for each environment.

Instead of importing from JSON, you could connect to your own data source and modify the script as needed.

Environments

POST /environments

{
    "name": "New York",
    "description": "Cisco New York, One Penn Plaza",
    "geofence": {
        "latitude": 40.751267,
        "longitude": -73.99229,
        "radius": 500
    },
    "perimeter": {
        "origin": {
            "x": -1,
            "y": -1
        },
        "size": {
            "height": 100,
            "width": 100
        }
    },
    "angle": 29,
    "data": {
        "uuid": "2F234454-CF6D-4A0F-ADF2-F4911BA9FFA6"
    }
}

function importEnvironment(source) {
    var environment = {};
    environment.name = source.name;
    environment.description = source.description;
    // latitude, longitude, radius (in meters)
    environment.geofence = source.geofence;
    // origin.x, origin.y, size.height, size.width
    environment.perimeter = source.perimeter;
    environment.data = source.data ? source.data : {};
    environment.angle = source.angle ? source.angle : 0;

    newEnvironment(environment, function(result) {
        var environmentId = result._id;
        console.log('Imported environment ' + result.name);

        if (source.zones) {
            for (var i = 0; i < source.zones.length; i++) {
                importZone(environmentId, source.zones[i]);
            }
        }

        if (source.devices) {
            for (var i = 0; i < source.devices.length; i++) {
                importDevice(environmentId, source.devices[i]);
            }
        }
    });
}

func importEnvironment(source: JSONDictionary) {
    var environment: JSONDictionary = [:]

    if let name = source["name"] as? String {
        environment["name"] = name }
    if let desc = source["description"] as? String {
        environment["description"] = desc }
    if let geofence = source["geofence"] as? JSONDictionary {
        environment["geofence"] = geofence }
    if let perimeter = source["perimeter"] as? JSONDictionary {
        environment["perimeter"] = perimeter }
    if let angle = source["angle"] as? Double {
        environment["angle"] = angle }
    if let data = source["data"] as? JSONDictionary {
        environment["data"] = data }

    flareManager.newEnvironment(environment) { result in
        if let environmentId = result["_id"] as? String,
            name = result["name"] as? String
        {
            NSLog("Imported environment \(name)")

            if let zones = source["zones"] as? JSONArray {
                for zone in zones {
                    self.importZone(environmentId, source: zone)
                }
            }

            if let devices = source["devices"] as? JSONArray {
                for device in devices {
                    self.importDevice(environmentId, source: device)
                }
            }
        }
    }
}

java

def importEnvironment(source):
    environment = {}
    environment['name'] = source.get('name', 'untitled')
    environment['description'] = source.get('description', '')
    environment['geofence'] = source.get('geofence', {})
    environment['perimeter'] = source.get('perimeter', {})
    environment['data'] = source.get('data', {})
    environment['angle'] = source.get('angle', 0)

    result = flare.newEnvironment(environment)
    environmentId = result['_id']
    print('Imported environment', result['name'])

    for zone in source.get('zones', []):
        importZone(environmentId, zone)

    for device in source.get('devices', []):
        importDevice(environmentId, device)

This function will create a new environment object from the source object by copying one property at a time. This assumes that the source object is already in the format of a Flare object, so this is a trivial operation (we could just duplicate the source object or use it directly). But the sample code breaks it down this way to validate the data, and to give an example that you can modify if you are using a different data source.

The code then creates a new environment by calling the API. The response includes the ID of the new environment, which is generated by the database. Then we iterate over all the zones and devices in the environment, and create them using the new environment ID.

Zones

POST /environments/{environment_id}/zones

{
    "name": "Open Space",
    "description": "The open space near the elevators",
    "perimeter": {
        "origin": {
            "x": 5,
            "y": 5
        },
        "size": {
            "height": 10,
            "width": 10
        }
    },
    "data": {
        "major": 2
    },
}

function importZone(environmentId, source) {
    var zone = {};
    zone.name = source.name;
    zone.description = source.description;
    // origin.x, origin.y, size.height, size.width
    zone.perimeter = source.perimeter;
    zone.data = source.data ? source.data : {};

    newZone(environmentId, zone, function(result) {
        var zoneId = result._id;
        console.log('Imported zone ' + result.name);

        if (source.things) {
            for (var i = 0; i < source.things.length; i++) {
                importThing(environmentId, zoneId, source.things[i]);
            }
        }
    });
}

func importZone(environmentId: String, source: JSONDictionary) {
    var zone: JSONDictionary = [:]

    if let name = source["name"] as? String {
        zone["name"] = name }
    if let desc = source["description"] as? String {
        zone["description"] = desc }
    if let perimeter = source["perimeter"] as? JSONDictionary {
        zone["perimeter"] = perimeter }
    if let data = source["data"] as? JSONDictionary {
        zone["data"] = data }

    flareManager.newZone(environmentId, zone: zone) { result in
        if let zoneId = result["_id"] as? String,
            name = result["name"] as? String
        {
            NSLog("Imported zone \(name)")

            if let things = source["things"] as? JSONArray {
                for thing in things {
                    self.importThing(environmentId, zoneId: zoneId, source: thing)
                }
            }
        }
    }
}

java

def importZone(environmentId, source):
    zone = {}
    zone['name'] = source.get('name', 'untitled')
    zone['description'] = source.get('description', '')
    zone['perimeter'] = source.get('perimeter', {})
    zone['data'] = source.get('data', {})

    result = flare.newZone(environmentId, zone)
    zoneId = result['_id']
    print('Imported zone', result['name'])

    for thing in source.get('things', []):
        importThing(environmentId, zoneId, thing)

This function will create a new zone object from the source object by copying one property at a time, as above. Modify as necessary for your data source.

The code then creates a new zone by calling the API. The response includes the ID of the new zone. Then we iterate over all the things in the zone, and create them using the environment ID and the new zone ID.

Things

POST /environments/{environment_id}/zones/{zone_id}/things

{
    "name": "Southwest",
    "description": "Flare 1.3",
    "position": {
        "x": 1,
        "y": 1
    },
    "data": {
        "minor": 3
    }
}

function importThing(environmentId, zoneId, source) {
    var thing = {};
    thing.name = source.name;
    thing.description = source.description;
    thing.position = source.position; // x, y
    thing.data = source.data ? source.data : {};

    newThing(environmentId, zoneId, thing, function(result) {
        console.log('Imported thing ' + result.name);
    });
}

func importThing(environmentId: String, zoneId: String, source: JSONDictionary) {
    var thing: JSONDictionary = [:]

    if let name = source["name"] as? String {
        thing["name"] = name }
    if let desc = source["description"] as? String {
        thing["description"] = desc }
    if let position = source["position"] as? JSONDictionary {
        thing["position"] = position }
    if let data = source["data"] as? JSONDictionary {
        thing["data"] = data }

    flareManager.newThing(environmentId, zoneId: zoneId, thing: thing) { result in
        if let name = result["name"] as? String {
            NSLog("Imported thing \(name)")
        }
    }
}

java

def importThing(environmentId, zoneId, source):
    thing = {}
    thing['name'] = source.get('name', 'untitled')
    thing['description'] = source.get('description', '')
    thing['position'] = source.get('position', {'x': 0, 'y': 0})
    thing['data'] = source.get('data', {})

    result = flare.newThing(environmentId, zoneId, thing)
    print('Imported thing', result['name'])

This function will create a new thing object from the source object by copying one property at a time, as above. Modify as necessary for your data source.

The code then creates a new thing by calling the API.

Devices

POST /environments/{environment_id}/devices

{
    "name": "My iPhone",
    "description": "iPhone 6 (32 GB)",
    "position": {
        "x": 3,
        "y": 1
    },
    "data": {
        "color": "red",
        "angle": 90,
        "mac": "69:6b:a6:11:9a:3e"
    }
}

function importDevice(environmentId, source) {
    var device = {};
    device.name = source.name;
    device.description = source.description;
    device.position = source.position; // x, y
    device.data = source.data ? source.data : {};

    newDevice(environmentId, device, function(result) {
        console.log('Imported device ' + result.name);
    });
}

func importDevice(environmentId: String, source: JSONDictionary) {
    var device: JSONDictionary = [:]

    if let name = source["name"] as? String {
        device["name"] = name }
    if let desc = source["description"] as? String {
        device["description"] = desc }
    if let position = source["position"] as? JSONDictionary {
        device["position"] = position }
    if let data = source["data"] as? JSONDictionary {
        device["data"] = data }

    flareManager.newDevice(environmentId, device: device) { result in
        if let name = result["name"] as? String {
            NSLog("Imported device \(name)")
        }
    }
}

java

def importDevice(environmentId, source):
    device = {}
    device['name'] = source.get('name', 'untitled')
    device['description'] = source.get('description', '')
    device['position'] = source.get('position', {'x': 0, 'y': 0})
    device['data'] = source.get('data', {})

    result = flare.newDevice(environmentId, device)
    print('Imported device', result['name'])

This function will create a new device object from the source object by copying one property at a time, as above. Modify as necessary for your data source.

The code then creates a new device by calling the API.