Magic Mirror Module for Particle.io Data

Introduction

I needed to find a better way to monitor data in my garden, so a year ago I built In-Plants using Particle.io Mesh hardware. The devices worked well, good battery life, and accurate data, however monitoring the data through the ThingSpeak.com was a hassle.

Having to navigate to the ThingSpeak frontend whenever I wanted to check on the statuses of my plants was a simple enough barrier that I never looked at it, causing my plants to continue to be neglected.

So I decided to level up and invest in a Smart Mirror to display my plant data in real-time right by my garden. If you are unfamiliar, smart mirrors are a two-way mirror system with an electronic display behind the glass. They are fairly easy to replicate using Magic Mirror, especially if you have a spare Raspberry Pi laying around, and you can add your own custom modules to it.

I created a Magic Mirror Module for my Particle devices and I am now able to easily digest data coming in from my Particle.io device network at a glance. It's working really well so I decided to write up a quick guide on how to utilize the module for any other enginerds out there utilizing Particle tech.

Step 0: Make a Magic Mirror

There are plenty of magic mirror guides out there, so I'm not going to spend too much time on this step. Check out the Magic Mirror GitHub for a detailed guide, but if you have a Raspberry Pi and a display it is as simple as running the bash install script:

bash -c "$(curl -sL https://raw.githubusercontent.com/MichMich/MagicMirror/master/installers/raspberry.sh)"

Then start the Magic Mirror afterward:

cd ~/MagicMirror && DISPLAY=:0 npm start

Step 1: Clone the Module

Run the following commands in your shell on the Magic Mirror to clone the Magic Mirror MMM-ParticleStatus module in the appropriate place:

cd ~/MagicMirror/modules 
git clone https://github.com/NickEngmann/MMM-ParticleStatus.git

Step 2: Set up your Configuration File

Magic Mirrors utilize a configuration file called config.js (located in ~/MagicMirror/config/config.js) to add modules and customizations to the Magic Mirror. Add the following code to your config file.

{
    module: "MMM-ParticleStatus",
    position: <Position of module>,
    header: "My Particle Devices",
    particleUsername: "default@gmail.com",
    particlePassword: "defaultpassword",
    clientId: "notrealclientId", //optional
    clientSecret: "notrealclientSecret", //optional
    debug: false, // optional
    events: [{event_object}]
}

Replace "default@gmail.com" and "defaultpassword" with your actual particle Username and password. And if you are publishing PRIVATE events, then you will need to include your clientId and clientSecret. And if you want to debug your event stream, set debug to true.

Now you are ready to fill in the events array with Event Objects

What are Particle Event Objects?

The MMM-ParticleStatus module listens for events. For each indicator you want to have on your Magic Mirror, make up a unique name for the event, such as "LightStateChange", "Garage", or "Car". Do not create separate events for the states (such as "LightOn" and "LightOff"); just an umbrella event.

Each time you want to update the state of the indicator on the Magic Mirror, publish to that event by using Particle.publish("Event Name", "New State") in the Particle firmware, such as the example shown below:

if(<Light switch just turned on>){
    Particle.publish("Light", "On");
}
if(<Light switch just turned off>){
    Particle.publish("Light", "Off");
}

another example:

float voltage = analogRead(BATT) * 0.0011224;
Particle.publish("device_battery_voltage", String(voltage));

You can have multiple events per device and use multiple devices.

You can read the official Particle docs on Particle.publish here.

An array of events (format is described below).

The Event Array:

The events field in the config takes a special JS Object, as described below.

If you leave the Event array Empty, nothing will be shown

Examples of the Event Array

Event Example 1

events:
    {
        deviceId: "a------------8",
        name: "moisture_level_percentage",
        icon: "leaf",
        nickname: "lettuce",
        states: [16, 30]
    },

If the data returned by the moisture_level_percentage event is within "16-30", it will display a green leaf icon, otherwise, it displays a red leaf icon.

Event Example 2

events:
    {
        deviceId: "a------------8",
        name: "device_battery_voltage",
        icon: "battery-half",
        nickname: "tomatoes",
        states: [2.9, 4.5],
        show_data: true
    }

If the data returned by the device_battery_voltage event is within the range "2.9-4.5", it will display a green battery-half icon, otherwise, it displays a red battery-half icon. It will also show the data returned by the event underneath.

Event Example 3

events:
    {
        deviceId: "b------------8",
        name: "device_sensor_online",
        icon: "leaf",
        nickname: "rosemary",
        states: ["off", "on"]
    },

If the data returned by the device_sensor_online event returns "off", then it will return back a red leaf icon, but if the data returned by the event is "on" then it displays a green leaf icon.

Full Configuration Example

{   
    module: "MMM-ParticleStatus",
    position: "top_bar",
    header: "Particle Devices", //Change this as you see fit
    config: {
        particleUsername: "default@gmail.com",
        particlePassword: "defaultpassword",
        clientId: "notrealclientId", //optional
        clientSecret: "notrealclientSecret", //optional
        debug: false, //optional
        events:
            [
                {
                    deviceId: "e------------f",
                    name: "moisture_level_percentage",
                    nickname: "lettuce",
                    icon: "leaf",
                    states: [16, 30]
                },
                {
                    deviceId: "e------------d",
                    name: "moisture_level_percentage",
                    icon: "leaf",
                    nickname: "lavender",
                    states: [16, 30]
                },
                {
                    deviceId: "e------------d",
                    name: "device_battery_voltage",
                    icon: "battery-half",
                    nickname: "lavender",
                    states: [2.9, 4.5],
                    show_data: true
                },
           ]
}

This configuration will show 3 icons, two events for the moisture_level_percentage, and one for the device_battery_voltage. The second and third events in the array are both coming from the same Particleio device, and one shows the moisture level state and raw data, while the other shows the battery level of the device and raw data.

Step 3: That's It!

Save your configuration file and restart your Magic Mirror display. Whenever your Particle devices publish data you should see your event icons and properties pop up on your magic mirror.

Enjoy :D