InitialState

Latest Version: 1.0.0

Initial State is a hosted service that allows you to easily push event-based data.

This class wraps Initial State’s Event API (aka groker) in an agent-side library.

More information on the Initial State service’s rate-limiting can be found here. Documentation describing how the Initial State API should be consumed can be found here.

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

To include this library in your project, add

#require "InitialState.class.nut:1.0.0"

at the top of your agent code.

Class Usage

Constructor: InitialState(accessKey[, bucketKey][, bucketName])

To instantiate the InitialState class, you need an Access Key and, optionally, the Bucket Key and Bucket Name:

Parameter	Optional	Notes
Access key	No	Available in Initial State account page under “Streaming Access Keys”
Bucket key	Yes	User-generated bucket ID, defaults to your agent ID
Bucket name	Yes	User-generated bucket name, defaults to the bucket ID

For example:

#require "InitialState.class.nut:1.0.0"

is <- InitialState(MY_ACCESS_KEY);

Class Methods

Send Events

There are two methods that may be used to send events to Initial State. One method, sendEvent(), is for singular events. The other, sendEvents(), is for a batch of events. Both methods can take an optional callback function which will be fired when the request is complete.

Initial State limits users to five requests per second. To be efficient with your Internet traffic, you should batch calls and use the sendEvents() method. sendEvent() is intended for low-frequency data like sending once every 300ms or more.

sendEvent(key, value[, epoch][, callback])

The parameters key and value are the data to be sent to Initial State. The value parameter currently accepts simple data types as values, ie. string, integer, float, bool.

The third parameter, epoch, is optional: it is an event timestamp (see below). It is possible to exclude epoch but include the (also optional) callback — sendEvent() will manage this for you.

// Send an event
is.sendEvent("temperature", 72, function(err, data) {
    if (err != null) server.error("Error: " + err);
});

sendEvents(events[, callback])

The events parameter is an array of key-value pairs, each a data point that could be sent to Initial State singly using sendEvent(). The value parameter currently accepts simple data types as values, ie. string, integer, float, bool.

// Send an array of events
is.sendEvents([
    {"key": "temperature", "value": 72},
    {"key": "humidity", "value": 55}
], function(err, data) {
    if (err != null) server.error("Error: " + err);
});

Note The sendEvents() method takes a single dimension array of tables. These tables need at least one key and its corresponding value, and can optionally include an epoch to override the timestamp of the event.

Overriding Event Timestamps

You can optionally override the timestamp of an event by passing in an epoch to the sendEvent() method. Values for epoch may also be added to the array items sent using sendEvents():

// Override the timestamp for a single event
is.sendEvent("temperature", 72, time());

// Override timestamps for multiple events
is.sendEvents([
    {"key": "temperature", "value": 72, "epoch": time() },
    {"key": "humidity", "value": 55, "epoch": time() }
]);

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