Skip to main content

The Things API

Latest Version: 1.2.0

This library wraps the thethings.io Internet of Things Cloud.

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 "TheThingsAPI.class.nut:1.2.0"

at the top of your agent code.

Class Usage

Callbacks

All methods which make web requests to TheThings.IO (activate(), write(), read() and subscribe()) take an optional callback as a parameter. The callbacks require three parameters: err, resp and data:

Parameter Notes
err null on success, or a string indicating the error
resp The HTTP Response table from the request
data The decoded body of the request

Constructor: TheThingsAPI([thingToken])

Create a new thing by passing its existing token as an argument — or leave it empty to activate it later using the activate() method. You can use the method getToken() to retrieve the thing’s Thing Token later.

#require "TheThingsAPI.class.nut:1.2.0"

// Instantiate a thing with an existing token
thing <- TheThingsAPI("<EXISTING_THING_TOKEN>");

Class Methods

activate(activationCode[, callback])

This method activates a thing using a TheThings.IO Activation Code, which identifies you as the creator of the thing and binds the thing to your account. Activation generates a unique Thing Token that will identify your thing at thethings.IO.

// Create a thing object
thing <- TheThingsAPI();

// Activate a thing with a token from your Dev Console
thing.activate("<ACTIVATION_TOKEN>", function(err, resp, data) {
    // If it failed - log an error message
    if (err) {
        server.error("Failed to activate Thing: " + err);
        return;
    }
    server.log("Success! Activated Thing!");
});

addVar(key, value[, metadata])

The addVar() method allows you to add a key/value pair that will be sent to TheThings.IO the next time write() is called. An optional third parameter, metadata, can be included to add additional metadata to the key/value pair. The metadata parameter should be a table with any of the following keys:

Key Type Description
timestamp Integer A unix timestamp (generated with time()) or a datetime string (YYYYMMDDHHmmss) indicating when the sample was collected
geo Table A table with lat and long keys indicating the latitude and longitude where the sample was collected

The addVar() method returns a reference to this, allowing you to chain multiple calls to addVar() together, or invoke write() immediatly after addVar().

// Add a simple sample:
thing.addVar("foo", "bar");

// Add a sample with metadata:
thing.addVar("foo1", "bar1", {
    "timestamp": time() - 3600,  // 1 hour ago
    "geo": {
        "lat": 41.4121132,
        "long": 2.2199454
    }
});

// Add two samples at once:
thing.addVar("foo2", "bar2").addVar("foo3", "bar3");

// Send all four samples to TheThings.IO
thing.write(function(err, resp, data) {
    if (err) {
        server.error(err);
        return;
    }
    server.log("Success!");
});

write([callback])

Sends the information collected with addVar() to TheThings.IO.

See addVar(), above, for sample usage.

read(key[, filters][, callback])

The read() method returns one or more samples for the specified key. An optional second parameter, filters, can be passed in to provide more information about the samples you are searching for. The filter table can contain any of the following keys:

Key Type Description
limit Integer The maximum number of results to return (1-100)
startDate Integer A unix timestamp (generated with time()) or a datetime string (YYYYMMDDHHmmss)
endDate Integer A unix timestamp (generated with time()) or a datetime string (YYYYMMDDHHmmss)

Note If a limit is not supplied, the read() method will return the last sample for the specified key.

// Get the last sample collected for 'foo'
thing.read("foo", null, function(err, resp, data) {
    if (err) {
        server.error(err);
        return;
    }
    // Get the sample
    local result = data[0];
    // Do something with the sample
    server.log(result.datetime + ": " + result.value);
});

// Get the last 100 samples collected in the last 24 hours for 'foo'
local yesterday = time() - 86400; // 86400 seconds in a day
thing.read("foo", { "limit": 100, "startDate": yesterday }, function(err, resp, data) {
    if (err) {
        server.error(err);
        return;
    }

    foreach(sample in data) {
        server.log(sample.datetime + ": " + sample.value);
    }
});

subscribe([callback])

The subscribe() method subscribes to the thing channel to get real time updates. Updates are passed to the callback when available.

thing.subscribe(function(error, response, data) {
    if (error) {
        server.error(error);
        return;
    }

    // We received an updated value from the thing channel
    if (typeof content == "array") {
        foreach (item in content) {
            // Do something with the update
            server.log(item.key + ": " + item.value);
        }
    }

    // We got a ping or connection status update
    if (typeof content == "table") {
        // Log status and message content
        if ("status" in content) server.log("Request status: " + content.status);
        if ("message" in content) server.log("Message: " + content.message);
    }
});

getToken()

Returns the thing’s Thing Token, which identifies your thing at thethings.IO.

// Save the Thing's token:
local data = server.load();
data.token <- thing.getToken();
server.save(data);

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 code improvements
1.2.0 GitHub Add subscribe(), improve activate()

License

The TheThingsIO library is licensed under the MIT License.