Conctr

Latest Version: 2.1.0

The Conctr library allows you to easily integrate your agent and device code with the Conctr IoT Platform. This library provides an easy way to send data to a Conctr application.

Click here for the full documentation of the Conctr API.

This library is supported by Mystic Pants not by Electric Imp. If you have questions about or issues with the library, please contact Mystic Pants at support@conctr.com

Click here to see information on the released versions of this library.

Setup

To use this library you will need to:

  • Register for an account on the Conctr platform.
  • Create an application.
  • Create a model within the application.

To include this library in your project, add

#require "conctr.agent.lib.nut:2.1.0"

at the top of your agent code and

#require "conctr.device.lib.nut:2.1.0"

at the top of your device code

Agent Class Usage

Constructor: Conctr(appId, apiKey, model[, options])

The constructor has three required parameters: appId, apiKey and model. These details can be found by navigating into your application on the Conctr platform, selecting the ‘models’ tab in the left-side menu then clicking on the ‘example’ button under the model you wish to use and chose the tab marked ‘Squirrel’.

Constructor Parameter Data Type Required Default Value Description
appId String Yes N/A The ID used to uniquely identify the application
apiKey String Yes N/A The API key that will be used to authenticate requests to Conctr
model String Yes N/A The model created within the application that defines the data structure Conctr will expect from the device and will validate against

There are also some configuration options parameters that can be set if you wish:

Option Data Type Required Default Value Description
options.useAgentId Boolean No false Boolean flag used to determine whether to use the imp agent ID instead of the device ID as the primary identifier to Conctr for the data sent. See setDeviceId() to set a custom ID
options.region String No "us-west-2" Region of the instance to use. Currently only "us-west-2" is supported
options.environment String No "staging" Conctr environment to send data to
options.protocol conctr.MQTT No conctr.MQTT Protocol to use to send message. Note Currently only MQTT is supported
options.rocky Object No null An instantiated Rocky object to be used for accepting claim requests via HTTPS
options.messageManager Object No null An instantiated MessageManager or Bullwinkle object to be used for guaranteeing message delivery from the device to the agent

Example

#require "conctr.agent.lib.nut:2.1.0"

const API_KEY = "<YOUR API KEY>";
const APP_ID = "<YOUR AUTHENTICATION TOKEN>";
const MODEL = "<YOUR MODEL>";

conctr <- Conctr(APP_ID, API_KEY, MODEL);

Agent Class Methods

setDeviceId(deviceId)

The setDeviceId() allows you the set the unique identifier that will be used by Conctr to identify the current device.

Note Changing the device ID after data has already been set previously will create a new device in Conctr. There will be no link between any data from this newly created device and the device data linked to the previous device ID.

Method Parameter Data Type Required Default Value Description
deviceId String No "imp.configparams.deviceid" Custom unique identifier that Conctr should store data against for this device

Example

const CUSTOM_DEVICE_ID = "device-1";

conctr.setDeviceId(CUSTOM_DEVICE_ID);

sendData(payload[, callback])

The sendData() method sends a data payload to Conctr via the data ingestion endpoint. It is called by the data event listener when the device sends data using the Conctr device class. It can also be used directly to send data to Conctr via the agent alone.

Method Parameter Data Type Required Description
payload Table/Array Yes A table or array of tables containing the data to be sent to Conctr. The keys in this table should correspond to fields from the model and the keys should be of type specified in the model
callback Function No Function to be called on response from Conctr. The function should take two arguments, error and response. See table below for more info

The callback will be called with the following arguments:

Callback Parameter Data Type Description
error String An error message if there was a problem, or null if successful
response Object An imp API httpresponse object

Example

local currentTempAndPressure = { "temperature" : 29, "pressure" : 1032};

conctr.sendData(currentTempAndPressure, function(error, response) {
    if (error) {
        server.error("Failed to deliver to Conctr: " + error);
    } else {
        server.log("Data was successfully received by Conctr");
    }
}.bindenv(this));

sendLocation([sendToConctr])

Retrieves the current location from the device and sends it to Conctr. This manual request ignores all location options.

Key Data Type Required Default Value Description
sendToConctr Boolean No true If true the location will be sent to Conctr. If false, it will be cached on the agent and sent with the next sendData() invocation

Example

// Send location to conctr
conctr.sendLocation();

publish(topics, msg[, contentType][, callback])

Publishes a message to a specific topic.

Parameter Data Type Required Description
topics Array/String Yes Topic or list of topics that message should be sent to
msg Any Yes Data to be published. If anything other than a string is sent, it will be JSON encoded
contentType String No Header specifying the content type of the message. If a content type is not provided, the message will be JSON encoded
callback Function No Function that will be called on completion of the publish request

Example

local msg = "Hello World";

// Publish message to topic 'test'
conctr.publish(["test"], msg, function(err) {
    if (err) {
        server.error(err);
    } else {
        server.log("Successfully published message");
    }
}.bindenv(this));

Your callback should be defined with the following parameters:

Callback Parameter Data Type Description
error String An error message if there was a problem, or null if the request was successful
response Object An HTTP response object

publishToDevice(deviceIds, msg[, contentType][, callback])

Publishes a message to a specific device.

Method Parameter Data Type Required Description
deviceIds Array/String Yes Device ID or list of device IDs that the message should be sent to
msg Any Yes Data to be published. If anything other than a string is sent, it will be JSON encoded
contentType String No Header specifying the content type of the message. If a content type is not provided, the message will be JSON encoded
callback Function No Function to be called on completion of the publish request

Example

local msg = "Hello World";

// Publish message to the host device
conctr.publishToDevice([imp.configparams.deviceid], msg, function(err) {
    if (err) {
        server.error(err);
    } else {
        server.log("Successfully published message");
    }
}.bindenv(this));

Your callback should be defined with the following parameters:

Callback Parameter Data Type Description
error String An error message if there was a problem, or null if the request was successful
response Object An HTTP response object

subscribe([topics][, callback])

Subscribe to a single or list of topics.

Note Calling subscribe() again with a new set of topics will cancel any previous subscription requests.

Method Parameter Data Type Required Default Value Description
topics Array Yes Subscribes to the device ID topic List of topics to subscribe to
callback Function No N/A Function to be called on message receipt

Example

// Subscribe to default topics
conctr.subscribe(function(response) {
    server.log ("Got message:" + response.body);
}.bindenv(this));

// Publish in 2 seconds to ensure subscription is connected
imp.wakeup(2, function() {
    local msg = "Hello World";

    // Publish message
    conctr.publishToDevice(imp.configparams.deviceid, msg, function(err) {
        if (err) {
            server.error(err);
        } else {
            server.log("Successfully published message");
        }
    }.bindenv(this));
}.bindenv(this));

Your callback should be defined with the following parameters:

Callback Parameter Data Type Description
response Table The HTTP response received from Conctr. The message will be in response.body

unsubscribe()

Unsubscribes from all topics.

Example

// Unsubscribe
conctr.unsubscribe();

get(url[, headers][, callback])

Performs a GET request to Conctr with authentication headers automatically added.

Method Parameter Data Type Required Description
url String Yes URL to which the GET request will be sent
headers Table No Additional headers to send
callback Function No Function to be called on completion of the GET request

Example

local url = "https://api.staging.conctr.com/status";

// Get a status request of Conctr
conctr.get(url, function(err ,resp) {
    if (err) {
        server.error(err);
    } else {
        server.log("Successfully got response");
    }
}.bindenv(this));

Your callback should be defined with the following parameters:

Callback Parameter Data Type Description
error String An error message if there was a problem, or null if the request was successful
response Table The HTTP response

post(url, payload[, headers][, callback])

Performs a POST request to Conctr with authentication headers automatically added.

Method Parameter Data Type Required Description
url String Yes URL to which the POST request will be sent
payload Any Yes Body of POST request
headers Table No Additional headers to send
callback Function No Function to be called on completion of the POST request

Example

// Example showing manual request to post a log to a Conctr application.
// Use log function below instead of manual implementation.
local url="https://api.staging.conctr.com/admin/apps/asd8f8a9niks7sd7ds8dsd87/appendLog";
local payload = { "msg": "Hello World!" };

// Append a log to application logs
conctr.post(url, payload, function(err, resp) {
    if (err) {
        server.error(err);
    } else {
        server.log("Successfully appended log");
    }
}.bindenv(this));

Your callback should be defined with the following parameters:

Callback Parameter Data Type Description
error String An error message if there was a problem, or null if the request was successful
response Table The HTTP response

log(message)

Log the message to the Conctr application. Will also output log to server.log(). Logs can be viewed using the conctr cli command line tool.

Note Arguments passed into message which are not strings will be JSON encoded before sending to Conctr.

Method Parameter Data Type Required Description
message String Yes Message to log to the application

Example

local log = "I am an important log message";

// Append an entry to the application log
conctr.log(log);

error(errorMessage)

Log the errorMessage to the Conctr application. Will also output log to server.error(). Logs can be viewed using the conctr cli command line tool.

Note Arguments passed into errorMessage which are not strings will be JSON encoded before sending to Conctr.

Method Parameter Data Type Required Description
errorMessage String Yes Error message to log to the application

Example

local err = "Oh no, Something went wrong";

// Append an error to the application log
conctr.error(err);

Device Class Usage

The device class is optional. It provides utility functions for interfacing with the agent class, such as automating the location-sending process, and provide queueing and error handling for sending data to Conctr.

Constructor: Conctr([options])

Instantiates the Conctr device class. It takes an optional table used to set the location sending configuration of the class. See setLocationOpts() below for details on the options keys.

Constructor Parameter Data Type Default Value Description
options Table null Options to be send to the setLocationOpts() function

Example

conctr <- Conctr();

setLocationOpts([options])

Allows you to override the current location options. Calling the method without any arguments sets location recording to defaults. The table passed into options can contain any of the following keys:

options Key Data Type Default Value Description
locEnabled Boolean true When enabled, location data will be automatically included with the data payload
locInterval Integer 3600 Duration in seconds between location updates
locSendOnce Boolean false Setting to true sends the location of the device only once, when the device boots if other criteria are met
locWakeReasons Array/Integer [WAKEREASON_NEW_SQUIRREL, WAKEREASON_POWER_ON] Only send location on one or more specific wake reasons

Example

// Change options to disable location sending altogether
local opts = { "locEnabled" : false };
conctr.setLocationOpts(opts);

sendData(payload[, callback])

The sendData() method is used to send a data payload to Conctr via the agent.

Note To receive a response to the HTTP request in the callback you must have passed in a value for the options.messageManager optional parameter in the agent constructor. If not, the callback will be called as soon as the payload has been sent to the agent.

Method Parameter Data Type Required Description
payload Table Yes A table containing the data to be sent to Conctr. The keys in this table should correspond to fields from the model and the keys should be of type specified in the model
callback Function No Function to be called on response from Conctr. The function should take two arguments, error and response. When no error occurred, the first argument will be null. If an instance of MessageManager is in use, the callback will be fired when the Conctr platform has accepted/rejected the message. If no MessageManager is in use, the callback will fire immediately upon sending

Example

local currentTempAndPressure = { "temperature" : 29, "pressure" : 1032};

conctr.sendData(currentTempAndPressure, function(error, response) {
    if (error) {
        server.error("Failed to deliver to Conctr: " + error);
    } else {
        server.log("Data was successfully send");
    }
}.bindenv(this));

send(ignoredString, payload)

This is an alias for the sendData() method above that uses the same format as the imp API method agent.send(), ie. agent,send("event name", payload);.

Method Parameter Data Type Required Description
ignoredString String Yes A string that will be ignored, can be null
payload Table Yes A table containing the data to be sent to Conctr. The keys in this table should correspond to fields from the model and the keys should be of type specified in the model 
local currentTempAndPressure = { "temperature" : 29, "pressure" : 1032};

conctr.send("Send a Packet", currentTempAndPressure);

sendLocation([sendToConctr])

Retrieves the current location from the device and sends it to Conctr. This manual request ignores all location options.

Method Parameter Data Type Required Description
sendToConctr Boolean No If true the location will be sent to Conctr. If false, it will be cached on the agent and sent with the next sendData() invocation.

Example

// Send location to conctr
conctr.sendLocation();

Claiming the Device

A mobile application can claim a device on behalf of a consumer, once they are logged into their account. The application should retrieve the consumer_jwt value from the Conctr platform using the consumer OAuth process. The application should then POST to the device’s agent URL, appending /conctr/claim to the end of the URL. The POST body should be a JSON table with the key consumer_jwt. The Content-Type header must be set to application/json for this to succeed.

Troubleshooting

Both the agent and the device libraries have a debug mode. Setting a Conctr instance’s DEBUG property to true will enable extra logging to help troubleshoot any issues you may encounter.

Example

// Enable debug mode
conctr.DEBUG = true;

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
2.0.0 GitHub Certain constructor parameters now passed in as a table; added sendLocation() method to agent and device; replaced device sendOpts() method with setLocationOpts(); added send() method to device; expose DEBUG property
2.1.0 GitHub Added publish and subscribe functions that provide an interface to Conctr’s messages API endpoints; bug fixes

License

The Conctr library is licensed under the MIT License.

© 2024 KORE Wireless. All rights reserved. Terms of Service, Privacy Policy

Toggle