Skip to main content

Plotly

Latest Version: 1.0.1

This library wraps the Plotly REST API, allowing you to graph and style data obtained from imp-connected sensors. It requires the creation of a Plotly account.

The class permits the creation of simple time-series data graphs while exposing access for styling graphs using all features of the Plotly API.

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 "Plotly.class.nut:1.0.1" to the top of your agent code.

Examples

To see working examples of this library in use, look at the Fully-Featured and Minimal Plotly projects on GitHub.

Callbacks

Almost all methods in this class, including the constructor, include an optional callback parameter. This is a function that takes three parameters: error, response and decoded. The first of these is a string (or null if no error occured); response is a table representing a response from the Plotly servers; and decoded is a table representing the JSON object returned by the Plotly servers. The response object mirrors that provided in the callback to httprequest.sendasync(). Always check the error argument before using either response or decoded.

Note While the constructor will return immediately, it is only safe to operate on the resulting object once the callback has been executed. It is the user’s responsibility to ensure at this step that the construction has succeeded by checking the HTTP response code and/or Plotly response messages.

Class Usage

Constructor: Plotly(userName, userKey, fileName, worldReadable, traces[, callback])

To create a plot, you need to call the constructor with your Plotly authentication information and some basic data about the new graph.

To find the values of userName and userKey that you will pass to the constructor, go to the Plotly API settings page and copy the Username and API key as highlighted below. Your userKey is not your password, but is an API key that Plotly provides to developers. Whenever you cycle your API key, for example by clicking ‘Generate a new key’, you will have to update this value in your code as well.

Plotly settings screenshot

Set fileName to the file name you would like this graph to have in your Plotly account.

The value of worldReadable should be true if you would like this graph to be accessible to anyone with a link to the plot. If it is false, the graph will only be accessible to your account.

Finally, traces is a list of the data point names you would like to graph. Each Plotly graph can display many concurrent values, known as traces, but you must list them all here before plotting them.

local callback = function(error, response, decoded) {
    if (error) {
        server.log("Got an error: " + error);
        return;
    }

    server.log("See plot at " + myPlot.getUrl());
}

myPlot <- Plotly("<YOUR USERNAME>", "<YOUR API KEY>", "weather_data", true, ["temperature", "inside_humidity", "outside_humidity"], callback);

Class Methods

getUrl()

Returns a string with the URL of the graph that the object generates. If the worldReadable constructor parameter was set to false, this link will only be viewable when you are logged into Plotly.

local myPlotUrl = myPlot.getUrl();

setTitle(title[, callback])

Sets the title (string) that will be displayed on this graph.

myPlot.setTitle("Weather at Station 7");

setAxisTitles(xAxisTitle, yAxisTitle)

Sets the labels (string) that will be applied to the standard x- and y-axes on this graph. If either argument is null or empty, that axis title will not be changed.

myPlot.setAxisTitles("Time", "Temperature (F)");

addSecondYAxis(axisTitle, traces, [callback])

Adds a second y-axis on the right side of the graph and assigns the specified traces to it. traces should be a list of the string names of traces as passed in the traces parameter to the constructor.

myPlot.addSecondYAxis("Humidity (%)", ["inside_humidity", "outside_humidity"]);

setStyleDirectly(styleTable, [callback*])

Sets the style of the graph by passing a description directly to the Plotly API. This allows for advanced styling options that this library does not provide specific methods for.

styleTable should be a Squirrel array or table that will be parsed into JSON. See the Plotly API docs for guidance on how to format this value.

local style = [
    { "name" : "temperature",
      "type" : "scatter",
      "marker" : { "symbol" : "square",
                   "color" : "purple" } },
    { "name" : "inside_humidity",
      "type" : "scatter",
      "marker" : { "symbol" : "circle",
                   "color" : "red"} }
];

myPlot.setStyleDirectly(style);

That there are several caveats to using this method:

  • This will entirely overwrite style parameters previously set using methods like addSecondAxis() and setStyleDirectly().
  • If there is an error in formatting styleTable, an error may be passed to the callback function or the call may silently fail.

setLayoutDirectly(layoutTable[, callback])

Sets the layout of the graph by passing a description directly to the Plotly API. This allows for advanced layout options that this library does not provide specific methods for.

layoutTable should be a Squirrel array or table that will be parsed into JSON. See the Plotly API docs for guidance on how to format this value.

Note that there are several caveats to using this method:

  • This will entirely overwrite layout parameters previously set using methods like AddSecondAxis(), setTitle() or setLayoutDirectly().
  • If there is an error in formatting styleTable, an error may be passed to the callback function or the call may silently fail.

post(dataObjs[, callback])

Appends data to the Plotly graph. The parameter dataObjs is an array of tables in the following form:

{ "name" : <TRACE_NAME>,
  "x" : [<X_VALUE_1, X_VALUE_2, ...>],
  "y" : [<Y_VALUE_1, Y_VALUE_2, ...>],
  "z" : [<OPTIONAL_Z_VALUE_1>, <OPTIONAL_Z_VALUE_2>, ...]
}

Note that the x, y and z fields hold arrays of integers or strings. The z field is also optional.

Each element in dataObjs must have a name field that corresponds to a trace name as passed into the constructor. To add multiple data points to a trace, either add them via an array or make multiple calls to this method.

myPlot.post([
  { "name" : "temperature",
    "x" : [timestamp],
    "y" : [latest_temperature] },
  { "name" : "inside_humidity",
    "x" : [timestamp],
    "y" : [latest_humidity] }
]);

Static Class Methods

Plotly.getPlotlyTimestamp([timestamp])

Returns a timestamp string that Plotly will automatically recognize and style correctly. Use this for your x-axis value on time-series data.

If the timestamp argument is provided as a Unix timestamp, this function will output the correctly formatted Plotly timestamp corresponding to it.

local timestamp = Plotly.getPlotlyTimestamp();
myPlot.post(
    { "name" : "temperature",
      "x" : [timestamp],
      "y" : [latest_temperature] }
);

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 Code improvements

License

The Plotly library is licensed under the MIT License.