Controlling Your Photon Device With SmartThings and Alexa

So you have created a Particle Photon ($20 Arduino compatible board with cloud connectivity) project and it was great.

You made it greater still by creating an IFTTT applet so that you could control your device using the IFTTT DO button app.

You then took it to the next level by hooking up IFTTT to the Amazon Alexa service, allowing you to control your Photon using voice command (and the Amazon Echo device).

But you find that saying the word "trigger" (code word for IFTTT) every time you want to issue a command is not natural. Instead of saying: "Alexa, trigger fan on", wouldn't it be nice if you could say: "Alexa, turn on the fan". You also happen to have a SmartThings hub and you noticed that for those devices, you can indeed say things like "Alexa, turn on the lights".

You surmise that if you were able to add you photon device to the list of SmartThings you could not only control your device using the SmartThings app, but you could then also use Alexa to control it. The good news is that it is possible to add your home brew device to SmartThings.

In this Instructables, we will take a look at the steps required to do just that.

Step 1: Adding Your Device to SmartThings

In this Instructables, we will be using a Particle Photon to control a ceiling Fan as an example. We will not be describing the project itself (which is the subject of another Instructables, Voice Control of a Ceiling Fan With Alexa) but will assume that you have have exposed a Particle cloud function (if you are using a Photon), or that you have provided an API to control it via an HTTP request (if you are using another microcontroller which is exposing an API).

You will need a SmartThings hub similar to this one.

SmartThings conveniently provides a dashboard for managing your devices and creating your automation routine. We will use the dashboard to add our device to the list of SmartThings devices. You will need a SmartThings account to login. The SmartThings dashboard is located here: https://graph.api.smartthings.com/

Refer to the SmartThings documentation reference for more information.

Here is a quick overview of the features we will be using in this tutorial.

SmartApps are small programs written in a programming language called Groovythat allow users to connect and control their devices. SmartApps can create automation routine but also communicate with external web services, send push and SMS notifications, expose their own REST endpoints, and more.

For the task at hand which is to integrate our home brew devices into the SmartThings ecosystem, we will need to create a SmartThings Device Handler, which is a Groovy program that encapsulates the details of communication between SmartThings and our physical device. The Device Handler is responsible for communicating with our device and performing an action in the physical world.

Step 2: Anatomy of a SmartThings Device Handler

Click on "My Device Handlers" tab and then click on "Create New Device Handler" button.
There are basically four ways to create a new device handler: from a form, from code, from a template and from ZigBee Device Fingerprint. At the end of the day, you will end up with the required Groovy code, so let's take a look at some code (attached), which can be pasted in the "From Code" tab.

Each device handler we create has one or more "capability". An example of a capability would be a "Switch", which allows you to turn things "on" or "off", a "Lock" which allows you to "lock" or "unlock" a lock, a "Garage Door Control" which allows you to "open" or "close" a door or a "Thermostat".

Step 3: Creating a New Device Handler

A device handler requires a set of inputs to function. These are parameters supplied by the user when he or she installs a new device (using the SmartThings mobile app or using the dashboard as we will see later). In our case, because we will need an OAuth2 access token and our device ID to interface with the Particle cloud API, we have added 2 input parameters, "token" and "deviceId".

The second section is the metadata section, which is primarily used for defining the device capabilities and interacting with the user when using the mobile app (the "tiles"). Because we are happy with just being able to turn the fan off or on at a preset speed, we have chosen a "switch" capability with commands "on" and "off".

Finally, we are connecting the "on" and "off" commands to our physical device via the Particle cloud. The "on" command for example calls sendToDevice('2') which in turn performs an HTTP POST to the particle cloud located at "https://api.particle.io/v1/devices/${deviceId}/FanControl". Notice that the input parameter token and the cloud function data are being passed as parameters of the Http call in the body of the request while the deviceId input parameter is being passed as part of the url request itself. "FanControl" is the name of the particle cloud function that we exposed by the device as a Particle cloud function in this example.

Step 4: Adding Our Device Instance

Because our new device handler will not be published for everyone's use and will be available only to us, we will use the SmartThings dashboard to add a new device, instead of using the SmartThings app on our mobile device. Click on the "+ New Device" button located under the "My Devices" tab:

1. Enter a name for your device, in this case "Fan". This is what you will use when talking to Alexa, so keep it short.
2. Enter a "Device Network Id", which is a unique string. Pick anything you like.
3. For Type, select the name of the Device Handler you created, in this case "Photon Fan Control".
4. For Hub, select your hub name.
5. Click the "Create" button to finish.

Your device list will now be updated with your new device.

Step 5: Testing Your Device

Open the SmartThings mobile app on your phone. Your device should now be listed. You have the option to change the icon to a more appropriate icon on your device. You should be able to turn on or off your device by tapping the icon.

What if nothing happens? How do you troubleshoot problems? This is where the SmartThings Device Simulator comes in handy.

Go back to the Device Handler tab, select your device handler and click the Simulator button at the far right of the toolbar. Click Set Location. Under Preferences, click device and select your device ("Fan"). Click Install button. You will now be able to click the "on" and "off" button to send commands to your device and watch the result of the calls in the debug console in the panel in the lower left. Useful information such as on which line the failure occurs can be used to troubleshoot a problem in your device handler.

Step 6: Using Alexa to "Turn on the Fan"

Finally, we need Alexa to refresh its list of SmartThings devices. Open the Amazon Alexa mobile app and click on the "Smart Home" tab. Your devices will be listed. Click on "Discover Devices" to perform a new search. An alternative is to ask your Echo: "Alexa, discover my devices".

What if your new device is not discovered? Make sure Alexa has permission to access the new device. Open the SmartThings mobile app and click on "Automation/SmartApps". Click on Amazon Echo. Under "Switches", the new device "Fan" should be listed. Otherwise, click on that section and check the check box next to "Fan".

Congratulations! You can now control your device using Alexa! There is actually quite a bit more to it and there are other ways to accomplish this, but I wanted to give you a quick overview of how to (relatively simply) go from "Alexa, trigger fan on!" to "Alexa, turn on the fan". I hope this Instructables has accomplished this goal.