Xively

This library wraps Xively’s public API, which allows you to push and get time-series data, as well as configure callbacks that can be triggered through Xively’s ‘_triggers’.

The Xively library consists of three classes, all of which are required to interact with the Xively service: - Xively.Client — Used to send requests to the Xively Service - Xively.Feed — A representation of a Xively feed consisting of one or more channels - Xively.Channel — A representation of a Xively Channel

In order to push data to Xively, we need to instantiate a Xively.Client object with our API key, create Xively.Channel objects for the data we wish to push, and then pass those channels into a Feed, which we can then send to the Xively service with Xively.Client.put().

Note The current implementation of this library makes synchronous requests when Xively.Client.get() and Xively.Client.put() are called.

You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.

To include this library in your project, add

#require "Xively.class.nut:1.0.1"

at the top of your agent code

Xively.Client Usage

Constructor: Xively.Client(apiKey[, baseURL])

To create a new Xively client, you need to call the constructor with your Xively API key. You can override the default base URL of https://api.xively.com/v2/ by supplying an optional second parameter.

#require "Xively.class.nut:1.0.1"

client <- Xively.Client("YOUR API KEY");

Xively.Client Methods

Xively.Client.get(feed)

Retreives the current value of a specified feed from Xively.

local tempChannel = Xively.Channel("Temperature");
local tempFeed = Xively.Feed("YOUR FEED ID", [tempChannel]);
client.get(tempFeed);
local temp = tempChannel.get();

Xively.Client.put(feed)

Sends the specified feed (and the data it contains) to Xively.

device.on("temp", function(temp) {
    local tempChannel = Xively.Channel("Temperature", temp);
    local tempFeed = Xively.Feed("YOUR FEED ID", [tempChannel]);
    client.put(tempFeed);
});

Xively.Feed Usage

Constructor: Xively.Feed(feedId, arrayOfChannels)

To create a Xively.Feed object, you need to pass a Feed ID which can be retrieved from your Xively dashboard, and an array of Xively.Channel objects representing the channels in the feed.

local tempChannel = Xively.Channel("Temperature");
local tempFeed = Xively.Feed("YOUR FEED ID", [tempChannel]);

Xively.Feed Methods

Xively.Feed.getFeedId()

To get the Feed ID of a previously instantiated Xively.Feed object, call the getFeedId() method.

local feedId = tempFeed.getFeedId();

Xively.Channel Usage

Constructor: Xively.Channel(channelName[, value])

To create a Xively.Channel object, you need to specify the channel name and, optionally, an initial value. The initial value is typically specified when we plan to immediatly send the channel’s data to Xively.

// Create a channel to send data
device.on("temp", function(temp) {
    local tempChannel = Xively.Channel("Temperature", temp);
    local tempFeed = Xively.Feed("YOUR FEED ID", [tempChannel]);
    client.put(tempFeed);
})

client <- Xively.Client("YOUR API KEY");

// Create a channel to get data
local tempChannel = Xively.Channel("Temperature");
local tempFeed = Xively.Feed("YOUR FEED ID", [tempChannel]);
client.get(tempFeed);

local temp = tempChannel.get();

Xively.Channel Methods

Xively.Channel.get()

The get() method returns the current value stored in the Xively Channel. This method does not retreive information from Xively. To retreive information from Xively, you must call Xively.Client.Get().

local tempChannel = Xively.Channel("Temperature", 21);
server.log(tempChannel.get());
// Logs 21

Xixvely.Channel.set(value)

The set() method sets the current value of the Xively Channel. This method does not send information to Xively. To send information to Xively, you must call Xively.Client.Set().

client <- Xively.Client("YOUR API KEY");
tempChannel <- Xively.Channel("Temperature");
tempFeed <- Xively.Feed("YOUR FEED ID", [tempChannel]);

device.on("temp", function(temp) {
    tempChannel.set(temp);
    client.put(tempFeed);
});

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version	Source Code	Notes
1.0.0	GitHub	Initial release
1.0.1	GitHub	Minor improvements

License

The Xively library is licensed under the MIT License.