EZ-Device: Lib to Connect Particle Board to Structure

Motivation

Structure is a cool platform that is dedicated to connecting all your IoT devices. Moreover, this platform allows maker to build easy and intuitive workflows connected to their devices. You can create new devices and associate them to your applications and workflows. The Structure-MQTT-device Library for Particle boards that allows the makers to use the notion of connected device not only on the Structure platform, but also on the IoT device side.

The Structure Side

We need three information to enable communication between the board and the Structure platform:

• Device ID
• Access Key
• Access Secret

You need first to create an account at Structure if you do not have one yet. Create then your application and a device. Once the device created, you can get the device ID that will be used to identify your board. The Figure 1 illustrate how to retrieve the device ID.

You need to create the access key that will be used by the board to get connected. the Figure 2 one illustrates how to generate a key. Please note that the access secret will be provided by a popup window during the generation of the key.

Connect your Components

You need to connect a temperature sensor to your board. The Figure 3 illustrate the schematics.  This step should be straightforward. 

I used in the Figure 3 an Arduino nano because it is the closest board to the Particle photon available in Fritzing.

Flash your Particle Board

UPDATE: You can skip this step and simply add Structure-MQTT-device from community libraries

IMPORTANT : you need to add SPARKJSON library also from the community libraries to your project.

Use the Particle builder and create a new application. Then click on libraries. on the left panel, click on contribute library. A popup will appear as illustrated in Figure 4. Copy-Paste the library link and click on add repository.

https://github.com/charifmahmoudi/getstructure-particle

The library is not published yet with the community libraries. I will do that after some more tuning on the code and completing the documentation.

Get your Particle Board Talk to Structure

The example that i propose has two features:

• it sends the luminosity variation to your application at Structure
• it listening to a "toggle" message from your application at Structure to turn on/off the built in led on the Particle Photon

Use the example in the library or copy-paste the following code on your sketch on the particle builder. Before flashing the code to your board, make sure to modify the deviceID, AccessKey, and AccessSecret.

#include "Structure-MQTT-device/Structure-MQTT-device.h"
// The Photon's onboard LED.
int LED = D7;
// Toggles the LED on/off whenever "toggle" command is received.
bool ledValue = false;
// Used to only send temperature once a second.
int lastUpdate = millis();
// The initialization of your device
GetStructure::Device photon("YOUR-DEVICE-ID", "YOUR-ACCESS-KEY", "YOUR-ACCESS-SECRET");
// Callback signature for Structure subscriptions.
void myCallback(JsonObject& command);
// Callback for GetStructure.io  subscriptions.
// Receive Your JsonObject from Structure
void myCallback(JsonObject& command) {
    // If the command's name is "toggle", flip the LED.
    if(String(command["name"].asString()).equals(String("toggle"))) {
        ledValue = !ledValue;
        digitalWrite(LED, ledValue ? HIGH : LOW);
    }
}
void setup() {
    Serial.begin(9600);
    Serial.println("Starting the Setup");
    pinMode(LED, OUTPUT);
    //you can create dynamicly devices using pointers
    //photon = new GetStructure::Device("aaaa", "bbbb", "cccc");
	//Connect the photon to the Structure broker
	photon.connect(myCallback);
	Serial.println("Setup complete");
}
void loop() {
	int now = millis();
    // Publish Light value every second.
    if(now - lastUpdate > 1000) {
        lastUpdate = now;
        // Build the json payload: { "rawlight" : xxx, "time" : yyy}
        StaticJsonBuffer<100> jsonBuffer;
        JsonObject& root = jsonBuffer.createObject();
        // Gets raw voltage to a light.
        int light = analogRead(A0);
        root["rawlight"] = light;
        root["time"] = lastUpdate;
       //Publish directly your JsonObject !!!  
       photon.publish(root);
    }
    photon.loop();
}

Test your Code and Turn on the Led

To test your code, go to your device at Structure and send a toggle message. You should go to your device at Stucture. On the bottom of the page, write toggle as the name of the command and simply send it. The Figure 5 illustrate how to send a toggle message to your board. 

You should see the built in led on as illustrated in Figure 6. Send the message again. and the led should turn off.

EZ-lib for EZ-Making

The Structure-MQTT-device library offers multiples cool features:

• The callback method support directly JSon object. so you do not have to deal with boring char * and convert them by yourself.

// Callback for Structure subscriptions.
// Receive Your JsonObject from GetStructure.io
void myCallback(JsonObject& command) {
    // If the command's name is "toggle", flip the LED.
    if(String(command["name"].asString()).equals(String("toggle"))) {
        ledValue = !ledValue;
        digitalWrite(LED, ledValue ? HIGH : LOW);
    }
}

• Is a wrapper for all the MQTT communication. It provides simply an object GetStructure::Device that you deal with. and it represents the devices on GetStructure.io application.

// The initialization of your device
GetStructure::Device photon("YOUR-DEVICE-ID", "YOUR-ACCESS-KEY", "YOUR-ACCESS-SECRET");

Just create your Json object and it send it for your to Structure application.

StaticJsonBuffer<100> jsonBuffer;
JsonObject& root = jsonBuffer.createObject();
...
//Publish directly your JsonObject !!!  
photon.publish(root);

Conclusion

Structure is a cool platform. Photon boards are also cool. The Structure-MQTT-device library is a library that integrates two cool platform for your convenience.

Do not hesitate to post comment if you need help or more precision.

That all folks!!!