Introduction

A simple plugin for the freeboard.io dashboard that allows data from Particle devices to be exposed on a local Particle cloud.

The original work for this plugin was authored by @krvarma and posted on the Particle.io community forum. That version provided SSEs (Server-Sent-Events) between the Particle.io cloud (non-local) and a locally-installed [freeboard.io] dashboard.

At the time of writing, the local Particle cloud can only broadcast SSEs at the following levels:

• Firehose (e.g. http://particle.local:8080/v1/events)
• Event-specific (e.g. http://particle.local:8080/v1/events/[eventName])
• Device-specific Firehose (e.g. http://particle.local:8080/v1/devices/[deviceID]/events)
• Device-and-event-specific (e.g. http://particle.local:8080/v1/devices/[deviceID]/events/[eventName])

This repository is created to host freeboard plugins that address the above differences between Particle.io and locally-installed clouds.

Installation

Follow the instructions on freeboard.io to install the plugin.

At this time time, there is only one plugin available:

• particleLocalSSE.js

Usage: Setting up a datasource

Add the Particle Local SSE datasource as you would normally do on freeboard.io.

The fields in the dialog box are self-explanatory. Take note to provide the full local url for your local Particle cloud and port number. For example: http://particle.local:8080

In the Event text field, enter the SSE event name you want to track. This field should contain the same string as your Particle Build/Dev code:

Spark.publish("eventName", String(eventValue), 5, PRIVATE);

(Note: there's no practical difference between PRIVATE / PUBLIC events on a local cloud!)

Once OK'ed, you should get the SSE working and updating itself automatically to your freeboard every time a new event gets called by your Particle devices.

Usage: Linking your datasource to a widget

This really depends on how you are publishing your variables from Particle, but a suggested approach is to compile as many readings as needed into a JSON string (be sure to check the 63-byte limit for both event name and data strings), and send that as a single publish request to minimise the number of events being published.

Take note: the local Particle cloud by default limits the publish frequency to 1Hz, or a burst of 4 messages every 4 seconds.

Example:

A publish request in Particle Build/Dev for a temperature/humidity sensor might look like:

tempC = DHT22.getCelsius();
humidity = DHT22.getHumidity();
sprintf(pubOut, "{\"c\":\"%2.2f\",\"h\":\"%2.2f\"}", tempC, humidity);
Spark.publish("dht22", pubOut, 5, PUBLIC);

Working from the above example, the data received in a freeboard widget will require some additional JSON parsing, which can be easily done in the freeboard .JS editor as:

var d = JSON.parse(datasources["SSE"]["data"]);
return d["c"];

If you are not publishing JSON data from Particle Build/Dev and only need to publish a single string value, retrieving this is even easier:

datasources["SSE"]["data"]);

In addition, you can also parse the metadata included with each SSE:

datasources["SSE"]["coreid"]

or

var dateObj = new Date(datasources["SSE"]["published_at"]);
return dateObj.getHours();

Usage: Filtering event firehose using Device ID in widgets

Due to the way the current Particle local cloud works, we are unable to retrieve device-specific or device-and-event-specific SSEs for direct usage. Therefore, a workaround needs to be included in the .JS editor in freeboard.

After setting up your datasource SSE, create a widget, and follow the guidelines below, using a Text widget as an example. In the widget's settings, click on the .JS editor and wrap the following if...else condition:

var id = datasources["your_datasource"]["coreid"];
if(id=="[deviceID]") {    // replace with the Device ID that you are targeting
    return datasources["your_datasource"]["data"];    // or customised code depending on the JSON you generated
}

Note: sample above is just a guideline; alter the fields to match your own scenario.

Todo

• This plugin should be updated, once Particle.io updates the local cloud and addresses issues with the limitations mentioned in the Introduction above.
• Full testing of plugin w/Photons – initial tests show Photon compatibiliity

Authors and Contributors

Original plugin: 2014 Krishnaraj Varma (@krvarma)
Particle local cloud adaptation and instructions: 2015 Chuan Khoo (@chuank)