Losant

This library wraps the Losant enterprise IoT platform REST API. It supports most of the platform's single-device and multiple-device actions, allowing the your code to create, update and delete devices on the Losant platform. The library also supports sending commands to platform devices and updating the current state of a platform device.

To use this library you need to have a Losant account and a Losantapplication.

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 "Losant.agent.lib.nut:1.0.0"

at the top of your agent code.

Class Usage

Constructor: Losant(appId, apiToken)

Each instance of the class will connect the device with a Losant application (identified by its ID). All methods will send and receive data via this application only.

Parameters

Parameter	Type	Required	Description
appId	String	Yes	A Losant Application ID
apiToken	String	Yes	An Application API token with Device and Devices permissions

Return Value

Nothing.

Example

// ID and API Token for My Losant Application
const LOSANT_APPLICATION_ID   = "<YOUR APPLICATION API TOKEN HERE>";
const LOSANT_DEVICE_API_TOKEN = "<YOUR API TOKEN HERE>";

lsntTrackerApp <- Losant(LOSANT_APPLICATION_ID, LOSANT_DEVICE_API_TOKEN);

Class Methods

Callback Functions

All HTTPS requests to Losant are made asynchronously. Each method that makes an HTTP request will have a required callback parameter, a function that will executed when the server responds. The callback function has a single parameter, response, into which is passed a table containing the following keys:

Key	Type	Description
statuscode	Integer	HTTP status code (or libcurl error code)
headers	Table	Squirrel table of returned HTTP headers
body	String	Returned HTTP body (if any)

createDevice(deviceInfo, callback)

This method creates a new device.

Parameters

Parameter	Type	Required	Description
deviceInfo	Table	Yes	A table with device info used to create the device. Please see the API documentation for table details
callback	Function	Yes	Called when response is received (see Callback Functions)

Return Value

Nothing.

Example

lsntDeviceId <- null;
agentId      <- split(http.agenturl(), "/").top();
impDeviceId  <- imp.configparams.deviceid;

deviceInfo   <- {
  "name"        : format("Tracker_%s", agentId),
  "description" : "Electric Imp Asset Tracker",
  "deviceClass" : "standalone",
  "tags"        : [
    { "key"   : "agentId",
      "value" : agentId },
    { "key"   : "impDevId",
      "value" :  impDeviceId }
  ],
  "attributes"  :  [
    { "name"     : "location",
      "dataType" : "gps" },
    { "name"     : "temperature",
      "dataType" : "number" },
    { "name"     : "humidity",
      "dataType" : "number" },
    { "name"     : "magnitude",
      "dataType" : "number" },
    { "name"     : "alertTemperature",
      "dataType" : "string" },
    { "name"     : "alertHumidity",
      "dataType" : "string" },
    { "name"     : "alertMovement",
      "dataType" : "string" }
  ]
}

lsntTrackerApp.createDevice(deviceInfo, function(res) {
  server.log(res.statuscode);
  server.log(res.body);
  local body = http.jsondecode(res.body);
  lsntDeviceId = body.deviceId;
})

getDevices(callback[, queryParams])

This method fetches a list of application devices.

Parameters

Parameter	Type	Required	Description
callback	function	Yes	Called when response is received (see Callback Functions)
queryParams	String	No	Query parameters to be added to the URL and which will be used to filter the results. Please see createTagFilterQueryParams() for an example

Return Value

Nothing.

Example

lsntDeviceId <- null;
agentId      <- split(http.agenturl(), "/").top();
impDeviceId  <- imp.configparams.deviceid;

deviceInfo   <- {
  "name"        : format("Tracker_%s", agentId),
  "description" : "Electric Imp Asset Tracker",
  "deviceClass" : "standalone",
  "tags"        : [
    { "key"   : "agentId",
      "value" : agentId },
    { "key"   : "impDevId",
      "value" :  impDeviceId }
  ],
  "attributes"  :  [
    { "name"     : "location",
      "dataType" : "gps" },
    { "name"     : "temperature",
      "dataType" : "number" },
    { "name"     : "humidity",
      "dataType" : "number" },
    { "name"     : "magnitude",
      "dataType" : "number" },
    { "name"     : "alertTemperature",
      "dataType" : "string" },
    { "name"     : "alertHumidity",
      "dataType" : "string" },
    { "name"     : "alertMovement",
      "dataType" : "string" }
  ]
}

// Get all devices
lsntTrackerApp.getDevices(function(response) {
  server.log("Status Code: " + response.statuscode);
  server.log(response.body);
});

// Create filter for tags matching this device, use the tags set up as unique ids - agent and device id combo
local qparams = lsntTrackerApp.createTagFilterQueryParams(deviceInfo.tags);

// Look for this device
lsntTrackerApp.getDevices(function(response) {
  local body = http.jsondecode(response.body);
  if (response.statuscode == 200 && "count" in body) {
    // Successful request
    switch (body.count) {
      case 0:
        // No devices found, create device
        lsntTrackerApp.createDevice(deviceInfo, function(resp) {
          local bdy = http.jsondecode(resp.body);
          lsntDeviceId = bdy.deviceId;
        });
        break;
      case 1:
        // We found the device, store the lsntDeviceId
        lsntDeviceId = body.items[0].deviceId;
        break;
      default:
        // We have multiple matches, log results of filtered query
        server.error("Found " + body.count + "devices matching the device tags.");
        // TODO: Delete multiples
    }
  } else {
    server.error("List device request failed with status code: " + response.statuscode);
  }
}, qparams);

getDeviceInfo(losantDeviceId, callback)

This method retrieves information for the specified device.

Parameters

Parameter	Type	Required	Description
losantDeviceId	String	Yes	The device ID assigned by Losant when the device is created
callback	function	Yes	Called when response is received (see Callback Functions)

Return Value

Nothing.

Example

lsntTrackerApp.getDeviceInfo(lsntDeviceId, function(response) {
  server.log("Status Code: " + response.statuscode);

  // Log device info
  server.log(response.body);
});

updateDeviceInfo(losantDeviceId, deviceInfo, callback)

This method updates information for the specified device.

Parameters

Parameter	Type	Required	Description
losantDeviceId	String	Yes	The device ID assigned by Losant when the device is created
deviceInfo	Table	Yes	A table containing updated device info. Please see the API documentation for table details
callback	function	Yes	Called when response is received (see Callback Functions)

Return Value

Nothing.

Example

lsntTrackerApp.updateDeviceInfo(lsntDeviceId, deviceInfo, function(response) {
  server.log("Status Code: " + response.statuscode);
  //Log updated device info
  server.log(response.body);
});

deleteDevice(losantDeviceId, callback)

This method deletes the specified device.

Parameters

Parameter	Type	Required	Description
losantDeviceId	String	Yes	The device ID assigned by Losant when the device is created
callback	function	Yes	Called when response is received (see Callback Functions)

Return Value

Nothing.

Example

lsntTrackerApp.deleteDevice(lsntDeviceId, function(response) {
  server.log("Status Code: " + response.statuscode);
  // Log if delete was successful
  server.log(response.body);
});

sendDeviceState(losantDeviceId, deviceState, callback)

This method sends the current state of the device.

Parameters

Parameter	Type	Required	Description
losantDeviceId	String	Yes	The device ID assigned by Losant when the device is created
deviceState	Table or array of tables	Yes	The keys in the device-state table(s) should correspond to the device's attributes
callback	function	Yes	Called when response is received (see Callback Functions)

Return Value

Nothing.

Example

device.on("data", function(data) {
  // We cannot post data, so just drop it
  if (lsntDeviceId == null) {
    server.log("Losant device not configured. Not sending data: ");
    server.log(http.jsonencode(data));
    return;
  }

  local payload = {
    "time" : lsntTrackerApp.createIsoTimeStamp(),
    "data" : {}
  };

  if ("lat" in data && "lng" in data) payload.data.location <- format("%s,%s", data.lat, data.lng);
  if ("temp" in data) payload.data.temperature <- data.temp;
  if ("humid" in data) payload.data.humidity <- data.humid;
  if ("mag" in data) payload.data.magnitude <- data.mag;

  lsntTrackerApp.sendDeviceState(lsntDeviceId, payload, function(res) {
    server.log(res.statuscode);
    server.log(res.body);
  });
});

getDeviceState(losantDeviceId, callback)

This method retrieves the last known state(s) of the specified device.

Parameters

Parameter	Type	Required	Description
losantDeviceId	String	Yes	The device ID assigned by Losant when the device is created
callback	function	Yes	Called when response is received (see Callback Functions)

Return Value

Nothing.

Example

lsntTrackerApp.getDeviceState(lsntDeviceId, function(response) {
  server.log("Status Code: " + response.statuscode);
  // Log device state
  server.log(response.body);
});

getDeviceCompositeState(losantDeviceId, callback)

This method retrieves the composite last complete state of the specified device.

Parameters

Parameter	Type	Required	Description
losantDeviceId	String	Yes	The device ID assigned by Losant when the device is created
callback	function	Yes	Called when response is received (see Callback Functions)

Return Value

Nothing.

Example

lsntTrackerApp.getDeviceCompositeState(lsntDeviceId, function(response) {
  server.log("Status Code: " + response.statuscode);
  // Log device composite state
  server.log(response.body);
});

sendDevicesCommand(command, callback)

This method sends a command to multiple devices.

Parameters

Parameter	Type	Required	Description
command	Table	Yes	A command table. Please see the API documentation for table details
callback	function	Yes	Called when response is received (see Callback Functions)

Return Value

Nothing.

Example

local cmd = { "time" : lsntTrackerApp.createIsoTimeStamp(),
              "name" : "myCommand",
              "payload" : [1, 1, 2, 3, 5] }

lsntTrackerApp.sendDevicesCommand(cmd, function(response) {
  server.log("Status Code: " + response.statuscode);
  //Log if command was sent successfully
  server.log(response.body);
});

sendDeviceCommand(losantDeviceId, command, callback)

This method send a command to the specified device.

Parameters

Parameter	Type	Required	Description
losantDeviceId	String	Yes	The device ID assigned by Losant when the device is created
command	Table	Yes	A command table. Please see the API documentation for table details
callback	function	Yes	Called when response is received (see Callback Functions)

Return Value

Nothing.

Example

local cmd = { "time" : lsntTrackerApp.createIsoTimeStamp(),
              "name" : "myCommand",
              "payload" : [1, 1, 2, 3, 5] }

lsntTrackerApp.sendDeviceCommand(losantDeviceId, cmd, function(response) {
  server.log("Status Code: " + response.statuscode);
  //Log if command was sent successfully
  server.log(response.body);
});

getDeviceCommand(losantDeviceId, callback)

This method retrieves the last known commands(s) sent to the specified device.

Parameters

Parameter	Type	Required	Description
losantDeviceId	String	Yes	The device ID assigned by Losant when the device is created
callback	function	Yes	Called when response is received (see Callback Functions)

Return Value

Nothing.

Example

lsntTrackerApp.getDeviceCommand(lsntDeviceId, function(response) {
  server.log("Status Code: " + response.statuscode);
  // Log commands
  server.log(response.body);
});

openDeviceCommandStream(losDevId, onData, onError[, keepAliveTimeout])

This method opens a stream that listens for commands directed at the specified device.

Note Only one stream can be open at a time. If called while a stream is open, openDeviceCommandStream() will close the stream that is currently open and will open a new stream.

Parameters

Parameter	Type	Required	Description
losantDeviceId	String	Yes	The device ID assigned by Losant when the device is created
onData	Function	Yes	A function that will be called when a command is received from Losant. It has a single parameter, a table, containing the command received from Losant
onError	Function	Yes	A function that will be called if the stream is closed unexpectedly or if a command cannot be parsed. It has two parameters: the error encountered, and the response from Losant
keepAliveTimeout	Integer or float	No	The amount of time in seconds to wait for a keepalive ping from Losant before closing the stream. Keepalive pings from Losant are sent every two seconds. Default: 30 seconds

Return Value

Nothing.

Example

function onData(command) {
  server.log(command.name);
  server.log(command.payload);
}

onError(error, response) {
  server.error("Error occurred while listening for commands.");
  server.error(error);

  if (lsntTrackerApp.isDeviceCommandStreamOpen()) {
    // Parsing error occurred
    server.log(response);
  } else {
    // HTTP error occurred
    if ("statuscode" in response) server.log("Status code: " + response.statuscode);

    // Reopen stream
    lsntTrackerApp.openDeviceCommandStream(lsntDeviceId, onData, onError);
  }
}

lsntTrackerApp.openDeviceCommandStream(lsntDeviceId, onData, onError);

closeDeviceCommandStream()

This method closes a command stream if one is open.

Return Value

Nothing.

Example

lsntTrackerApp.closeDeviceCommandStream();

isDeviceCommandStreamOpen()

This method indicates whether a command stream is open.

Return Value

Boolean — true if a steam is currently open, otherwise false.

Example

server.log("Device command stream is open: " + lsntTrackerApp.isDeviceCommandStreamOpen());

getDeviceLogs(losantDeviceId, callback)

This method retrieves the recent log entries for the specified device.

Parameters

Parameter	Type	Required	Description
losantDeviceId	String	Yes	The device ID assigned by Losant when the device is created
callback	function	Yes	Called when response is received (see Callback Functions)

Return Value

Nothing.

Example

lsntTrackerApp.getDeviceLogs(lsntDeviceId, function(response) {
  server.log("Status Code: " + response.statuscode);
  // Log device logs
  server.log(response.body);
});

createIsoTimeStamp([epochTime])

This method creates a UTC combined date time timestamp based on the ISO 8601 standard. If a value is passed into epochTime, it will be reformatted, otherwise the current time will be used.

Parameters

Parameter	Type	Required	Description
epochTime	Integer	No	Integer returned by calling time(), the current date and time as elapsed seconds since midnight, 1 Jan 1970

Return Value

Sting — An ISO 8601 timestamp.

Example

local now = lsntTrackerApp.createIsoTimeStamp();
server.log(now);

createTagFilterQueryParams(tags)

This method formats a device information tag array into query parameter format.

Parameters

Parameter	Type	Required	Description
tags	Array	Yes	Array of tag tables with slots key and/or value

Return Value

String — A tag filter query parameter string.

Example

local searchTags = [
    { "key"   : "agentId",
      "value" : split(http.agenturl(), "/").top() },
    { "value" : imp.configparams.deviceid }
];

local qparams = lsntTrackerApp.createTagFilterQueryParams(searchTags);

Examples

Please see the examples folder on GitHub for further example code.

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

License

This library is licensed under the MIT License.

Latest Version: 1.0.0

Class Usage

Constructor: Losant(appId, apiToken)

Parameters

Return Value

Example

Class Methods

Callback Functions

createDevice(deviceInfo, callback)

Parameters

Return Value

Example

getDevices(callback[, queryParams])

Parameters

Return Value

Example

getDeviceInfo(losantDeviceId, callback)

Parameters

Return Value

Example

updateDeviceInfo(losantDeviceId, deviceInfo, callback)

Parameters

Return Value

Example

deleteDevice(losantDeviceId, callback)

Parameters

Return Value

Example

sendDeviceState(losantDeviceId, deviceState, callback)

Parameters

Return Value

Example

getDeviceState(losantDeviceId, callback)

Parameters

Return Value

Example

getDeviceCompositeState(losantDeviceId, callback)

Parameters

Return Value

Example

sendDevicesCommand(command, callback)

Parameters

Return Value

Example

sendDeviceCommand(losantDeviceId, command, callback)

Parameters

Return Value

Example

getDeviceCommand(losantDeviceId, callback)

Parameters

Return Value

Example

openDeviceCommandStream(losDevId, onData, onError[, keepAliveTimeout])

Parameters

Return Value

Example

closeDeviceCommandStream()

Return Value

Example

isDeviceCommandStreamOpen()

Return Value

Example

getDeviceLogs(losantDeviceId, callback)

Parameters

Return Value

Example

createIsoTimeStamp([epochTime])

Parameters

Return Value

Example

createTagFilterQueryParams(tags)

Parameters

Return Value

Example

Examples

Release History

License