Alexa Enabled Your Particle Photon in 30 Lines of Code

Add Alexa SmartHome control to your Particle Photon (or Electron) project using Tinamous and the Tinamous SmartHome Skill for Alexa. The only coding required is a few lines on the Photon to implement a couple of Particle.functions and variables.

In this example I'll use the on-board RGB LED of the Photon to keep it simple, just replace the RGB control with your own control.

Prerequisites:

Before we can control the Photon it needs to be accessible by Tinamous. Tinamous is an Internet of Things platform that enables you to monitor, control and chat with your things.

I'll assume you already have a Photon up and running. In this example mine is called "Water2" at Particle.io and a more friendly "Kitchen Water" in Tinamous (you can probably guess what it's going to be used for eventually!).

To get started we need to:

• Create a free Tinamous.com account (if you don't already have one)

• Add a ParticleBot

• Optionally create a member account for "Alexa"

• Install the Tinamous SmartHome Skill

Add a ParticleBot:

From your Tinamous account, navigate to the Bots page and click [Add] and follow the instructions on the dialog box.

Rerfresh the Bots page to see the new Particle Bot. We also need to allow the Particle Bot to process Alexa SmartHome status posts as Particle Function calls. Click Edit next to your Particle Bot and under Particle Integration tick "Alexa Function"

Create a member for Alexa:

Navigate over the the Members page and click [Add Member] to add a new member for Alexa.

Install the Tinamous SmartHome Skill

From the Alexa app, select Skills and search for the "Tinamous SmartHome" skill. (At the time of writing this is in the UK only). If you're interested in the skill or want to make your own version with modifications the full code is on Github.

When you install this you will need to link your account, this will take you to the Authorize page on Tinamous to Authorize Alexa to access your account.

The Account entry is the name you gave your Tinamous account when you created it and the subdomain you use to access it (i.e. here it's ddd and I use ddd.Tinamous.com to access that account), then the username and password you set for the Alexa member.

Before doing the SmartHome device discovery we need to get our Photon up and running...

Example 1: Simple On/Off

Tasks:

• Write the Photon Code

• Tag the device in Tinamous to support the Alexa.PowerControl interface.

• Discover SmartHome Devices

• "Alexa, Turn on the kitchen water."

Photon code:

// =============================================
// This example switches on and off the LED on 
// the photon from Alexa's Turn On and Turn Off command
// =============================================
bool powerState = false; 
void setup() {
   RGB.control(true);
   RGB.brightness(0);
   RGB.color(0, 255, 0);
   Particle.variable("powerState", powerState);
   Particle.function("TurnOn", turnOn);
   Particle.function("TurnOff", turnOff);
}
void loop() {}
// This function will be called when you say "Alexa, Turn On the __Device_Name__"
int turnOn(String args) {
   // args will either be empty, or contain "port-1", "port-2" or...
   powerState = true;
   RGB.brightness(255);
   return 255;
}
// This function will be called when you say "Alexa, Turn Off the __Device_Name__"
int turnOff(String args) {
   // args will either be empty, or contain "port-1", "port-2" or...
   powerState = false;
   RGB.brightness(0);
   return 0;
}

The important parts to note here are the two Particle.functions "TurnOn" and "TurnOff". These are the functions that get called by the Alexa handling and the "powerState" variable which is read by Alexa as a property of the device.

In turnOn we set the LED brightness to 255, and in turnOff we set it to 0, the return values are just to help us and not seen by Alexa.

Flash the code to the Photon (be sure to select the correct Photon, all to often I forget to select the Photon I want to flash to!). Once updated we can check the function is available and test it from the Particle section on the device details page.

From the Devices list, find your Photon and click the name, this takes you to the Devices page. Click "Particle" from the left options. You should see the functions and clicking them should produce the desired effects.

Tag your device:

Add the tag Alexa.SmartDevice to allow the device to be picked up by Alexa as a SmartHome Device.

Additionally we'll apply Alexa.PowerController to indicate that the device supports the power control (Turn On, Turn Off) directives.

Navigate to the Devices page in Tinamous. Find the device and click the Edit button on the right.

Under the Basics section edit the tags and add the two Alexa tags.

Click Save at the top. Your device should now look like this on the devices page (although the status may be red or yellow if it is not yet sending data):

Discover SmartHome Devices:

If the Alexa app has just finished adding the Tinamous SmartHome skill you should be promoted to discover SmartHome Devices. You can select this now.

Alternatively (useful when adding new devices, or you've made changes to the device), select the "Smart Home" menu and use Add Device, or "Alexa, Discover Smart Home Services".

If Alexa didn't find the device it's likely you've missed off the "Alexa.SmartDevice" tag, or an authentication error occured.

Alexa, Turn on the kitchen water:

You should now be able to say, "Alexa, Turn on the kitchen water" and have the LED on the Photon switch on.

Status Messages

The Tinamous SmartHome skill works by posting status messages to your accounts timeline (think Tweets), these are processed by the ParticleBot and if they match the pre-defined SmartHome templates the appropriate function is called on the Particle Device.

Here we can see the interactions on the Tinamous timeline.

You can use this to debug the interactions or just type "@Water Turn On" yourself (Pro-tip: this also works by sending a sms message to the timeline within Tinamous, or using a notification to post a status message).

Example 2: On/Off, Flow rate and Temperature

In this example we'll use the Set Brightness from Alexa to control the LEDs brightness on the kitchen water usage monitor.

This example builds on Example 1. If you've skipped that be sure to go back and follow it.

Tasks:

• Update the Photon Code

• Update the device tags in Tinamous to support Alexa.BrightnessController and Alexa.TempertureSensor interface.

• Discover SmartHome Devices to update the device.

• Alexa....

The updated Photon code is below. Note the addition of brightnessPercent and temperature variables, as well as the SetBright Particle Function.

// ==========================================================
// This example switches on and off the LED on 
// the photon from Alexa's Turn On and Turn Off command.
// and sets the brightness from the set brightness command.
// ==========================================================
bool powerState = false; 
int brightnessPercent = 0;
double temperature = 23.4;
void setup() {
   RGB.control(true);
   RGB.color(0, 255, 0);
   updateBrightness(0);
   Particle.variable("temperature", temperature);
   Particle.variable("powerState", powerState);
   Particle.variable("brightness", brightnessPercent);
   Particle.function("TurnOn", turnOn);
   Particle.function("TurnOff", turnOff);
   Particle.function("SetBright", setBrightness);
}
void loop() {}
int updateBrightness(int brightness) {
   // Validation goes here :-)
   brightnessPercent = brightness;
   RGB.brightness(brightnessPercent * 2.55f);
   if (brightnessPercent < 1) {
       powerState = false;
   } else {
       powerState = true;
   }
   return brightnessPercent;   
}
int turnOn(String args) {
   return updateBrightness(100);
}
int turnOff(String args) {
   return updateBrightness(0);
}
int setBrightness(String args) {
   // args will be "###" (0 to 100)
   return updateBrightness(args.toInt());
}

Update the device tags:

To tell Alexa about the new interfaces the device supports we just add the tags Alexa.PowerLevelController and Alexa.TemperatureSensor, I've also added "Alexa.Lighting" so Alexa knows the device is a light.

Once you've flashed the photon either give it some time for the fields to be updated or use the device page to read the variables, ensure that temperature is available as a field.

The Fields section of the device editor should now look like...

Discover SmartHome Devices to update the device.

We need to re-run SmartHome Discovery again to update your device.

"Alexa, Discover smart home devices"

Don't worry, Alexa will tell you no new devices were found, but will add the extra capabilities to the device.

If you get "That command doesn't work on ____" either the tag was spelt wrong or you forgot to run discovery.

Alexa....

"Alexa, What's the temperature of kitchen water"

"Alexa, Turn on the kitchen water"

"Alexa, Set kitchen water to 50 percent"