Step-by-step guide to make a physical dashboard

Making an object that displays information from the web is easy with the Particle Photon.

Here's a step-by-step guide to creating a beach safety display light. You can adapt these steps to the data source and display you choose.

Project overview

The project will display a green/yellow/red light depending on the safety status of a Poipu beach in Hawaii.

The safety status is fetched once per hour from the Hawaii beach safety API and parsed in a Node.js Javascript program hosted on hook.io. The status is then sent to the Photon.

The Photon has code in the Arduino language to display the green/yellow/red light on an LED.

The reason to split the code in 2 is that by using the strengths of each system we can keep the code straightforward and easy to modify. Javascript is great for fetching web pages and parsing JSON. The Arduino language is great for controlling physical components, but not great a parsing text and fetching web pages.

Code for Particle device

This guide assumes you'll be using a Photon or Core internet-connected microcontroller from Particle. You should already have an account and claimed your device to your account.

Open Particle Build, the web IDE and create a new program with this code.

The code for the Particle device is simple since it only needs to display a color on the LED.

For your project, you'll have to modify this code if you're using a 7 segment display, a NeoPixel, a Particle Internet button, or a Color Orb like Brian Chamberlain build.

module['exports'] = function udpateBeachStatus (hook) {
  var got = require('got');
  got('http://hawaiibeachsafety.com/rest/ratings.json')
  .then(function (response) {
    hook.res.end(response.body);
  })
  .catch(function (error) {
    hook.res.end("Error fetching data: " + error);
  });
};

Flash it to your device.

To test that it works, you can use the Particle command line interface to send commands

particle call mydevice beach-status green

Code for the web program

Using hook.io, it's easy to create a small Javascript program that run when accessed in a browser. In addition, hook.io has a timer to have your script called on a regular schedule, like once an hour.

Sign up to hook.io using your GitHub account and create a new hook called "update-beach-status".

We'll develop the program step by step.

Step 1

First, let's fetches the beach safety information from the API at http://hawaiibeachsafety.com/rest/ratings.json and just show it.

module['exports'] = function udpateBeachStatus (hook) {
  var got = require('got');
  got('http://hawaiibeachsafety.com/rest/ratings.json')
  .then(function (response) {
    hook.res.end(response.body);
  })
  .catch(function (error) {
    hook.res.end("Error fetching data: " + error);
  });
};

Step 1 code: Just fetch the data

Go to your web script URL (mine is https://hook.io/monkbroc/update-beach-status) to see the output.

Step 2

Let's update the program to only get the data that interests us. We go through each rating element in the JSON array to look for Poipu beach.

module['exports'] = function udpateBeachStatus (hook) {
  var got = require('got');
  got('http://hawaiibeachsafety.com/rest/ratings.json')
  .then(function (response) {
    var ratings = JSON.parse(response.body);
    for(var rating of ratings) {
      if(rating.beach.match(/poipu/)) {
        hook.res.end(JSON.stringify(rating));
      }
    }
  })
  .catch(function (error) {
    hook.res.end("Error fetching data: " + error);
  });
};

Step 2 code: Show only the rating for Poipu beach

Step 3

Next we map the nearshore status of low to the color green, high to yellow and extreme to red.

module['exports'] = function udpateBeachStatus (hook) {
  var got = require('got');
  got('http://hawaiibeachsafety.com/rest/ratings.json')
  .then(function (response) {
    var ratings = JSON.parse(response.body);
    for(var rating of ratings) {
      if(rating.beach.match(/poipu/)) {
        var color;
        switch(rating.nearshore) {
          case "low": color = "green"; break;
          case "high": color = "yellow"; break;
          case "extreme": color = "red"; break;
        }
        hook.res.end(color);
      }
    }
  })
  .catch(function (error) {
    hook.res.end("Error fetching data: " + error);
  });
};

Step 3 code: Map conditions to LED color

Step 4

Finally, we send the status to the Particle device using the Particle Javascript library. We log in using a Particle token, get our device and call our beach-status function.

module['exports'] = function udpateBeachStatus (hook) {
  var got = require('got');
  var Particle = require('spark');
  
  got('http://hawaiibeachsafety.com/rest/ratings.json')
  .then(function (response) {
    var ratings = JSON.parse(response.body);
    for(var rating of ratings) {
      if(rating.beach.match(/poipu/)) {
        var color;
        switch(rating.nearshore) {
          case "low": color = "green"; break;
          case "high": color = "yellow"; break;
          case "extreme": color = "red"; break;
        }
        return color;
      }
    }
  })
  .then(function (color) {
    hook.res.write("Updating device with color " + color + "\n");
    
    return Particle.login({ accessToken: hook.env.PARTICLE_API_TOKEN })
    .then(function () {
      return Particle.getDevice('mydevicename');
    })
    .then(function (device) {
      return device.callFunction("beach-status", color);
    });
  })
  .then(function () {
    hook.res.end("Done!");
  })
  .catch(function (error) {
    hook.res.end("Error fetching data: " + error);
  });
};

Step 4 code: Send the color to our device

Before running this step, you have to add your Particle access token to the hook.io environment. Never put tokens, passwords or other sensitive information in source code otherwise other people reading your code will see them and have access to your account. If the API where you get your data for your project requires a token, put it in the environment too.

Find your Particle token in the Settings tab of Particle Build. Alternatively, you can generate another token using the Particle command line interface.

Go to https://hook.io/env and paste your token to a hook.io environment variable called PARTICLE_API_TOKEN

With that, you can now run the web script to send the value to your device.

The final step is to have the script run on a regular schedule. Go to your web script admin page (mine is https://hook.io/monkbroc/update-beach-status/admin) and scroll to the bottom to the Schedule section. Configure the timer to run your web script every hour on the hour (8:00, 9:00, 10:00, etc). Save the hook.

You're done!

You now have a physical dashboard for information fetched from the web.

Go ahead an integrate a Particle Photon to your next beautifully crafted object.

Post scriptum

Why not use a Particle webhook to fetch and parse the API data, and put the code to map from the API data to the LED color in the Photon? As mentioned above, I find it easier to write and test the web fetching and parsing code in Javascript. If you feel more comfortable using Particle webhooks than having 2 pieces of code, go ahead and do it this way.