Skip to main content

Mnubo

Latest Version: 1.0.0

The Mnubo client is an Electric Imp agent-side library for interfacing to the Mnubo API v3. It currently only supports the “ingestion” (insertion of records) features and not the “restitution” (searching the records) features. This library is ported from and designed to be as close as possible to the Mnubo JavaScript SDK. Refer to the JavaScript SDK for further information.

This library is dependent on the Promise library.

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

To add this library to your project, add

#require "mnubo.agent.nut:1.0.0"
#require "promise.class.nut:3.0.1"

to the top of your agent code.

Class Usage

Constructor: Mnubo.Client(clientOptions)

The Mnubo client class is instantiated with a table of client options. The following fields are available:

clientOptions Key Value Type Default Notes
id String none, mandatory This is the client_id, available in the security section of the Mnubo dashboard
secret String none, mandatory This is the client_secret, available in the security section of the Mnubo dashboard
env String "sandbox" Should be "sandbox" or "production"
httpOptions Table See below Configuration of the HTTP client

 

httpOptions Key Value Type Default Notes
protocol String "https" Should be "http" or "https"
port Integer 443
hostname String "rest.[sandbox/api].mnubo.com"

Example

#require "promise.class.nut:3.0.1"
#require "mnubo.agent.nut:1.0.0"

// Instantiate an Mnubo sandbox client with the default values
const CLIENT_ID = "<YOUR_CLIENT_ID>";
const CLIENT_SECRET = "<YOUR_CLIENT_SECRET>";
const MNUBO_ENV = "sandbox";

client <- Mnubo.Client({"id": CLIENT_ID, "secret": CLIENT_SECRET, "env": MNUBO_ENV});

Authentication

The authentication is wrapped for every API call. The library will first fetch a new Access Token and make the API call. There is nothing to do from a developer’s perspective besides setting the client ID, client secret and environment during initialization.

API Calls

All the API calls return a Promise. Each promise is an instance of the class provided by the Promise library.

  • When a promise is successful, you can call the then() method to get the data returned by the Mnubo servers. If there is no data, the value is null. For example: client.events.send({...}).then(function(data) { server.log(http.jsonencode(data)); });

  • When a promise is fails, you can call the fail() method to get the error returned by the Mnubo servers. If there is no data, the value is null. For example: client.events.send({...}).fail(function(data) { server.log(http.jsonencode(data)); });

If you are not familiar with promises, there is an excellent article on html5rocks.

Class Properties

objects

The objects property holds the methods for inserting data about objects. These are usually a mapping of real-world devices. The class can create(), update() and remove() objects. Each object is identified by a user-generated deviceId (commonly the mac address or agent ID of the imp).

// Create a new object
local agentid = split(http.agenturl(), "/").pop();
client.objects
    .create({
        "x_device_id": agentid,
        "x_object_type": "widget",
    })
    .then(function(response) {
        server.log("Object creation was successful");
    });

events

The events object holds the functions for inserting data about (usually time sensitive) events that have taken place. The class can send() (multiple) events when they are not attached to a device and sendFromDevice() when the events are directly associated with a device.

// Record an event by a device
client.events
    .sendFromDevice(agentid, [
        { "x_event_type": "boot" }
    ])
    .then(function(response) {
        server.log("Event sending was successful");
    });

owners

The owners object holds the functions for inserting data about the end-user. The class can create(), update() and remove() owners plus it can claim() objects for the owner. Owners are identified by an email address.

// Create a new user
client.owners
    .create({
        "username": "user@example.com",
        "x_password": "password"
    })
    .then(function(success, response) {
        server.log("Owner creation was successful");

        // Claim an object on behalf of a user
        client.owners
            .claim("user@example.com", agentid)
            .then(function(response) {
                server.log("Object claim was successful");
            }.bindenv(this));
    }.bindenv(this);

Examples

There are further examples in the GitHub repository.

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 Source Code Initial release

License

The Mnubo class copyright 2015 SMS Diagnostics Pty Ltd. It is licensed under the MIT License.