On April 5, 2016, Amazon announced the Smart Home Skill API, the public, self-service version of the Alexa Lighting API, which was introduced as a beta in August 2015. As part of the beta program, we worked with a number of companies to gather developer feedback, while extending the Alexa smart home capabilities to work with their devices.

In 2015, the Alexa team wanted to make it fast and easy for developers to create skills that connect devices directly to our lighting and thermostat capabilities so that customers can control their lights, switches, smart plugs or thermostats—without lifting a finger. So they created a beta program to work with experts in thermostats and home comfort to gather developer feedback, while extending the Alexa smart home capabilities to work with their devices. That naturally led them to ecobee, creator of a smart thermostat that uses remote sensors to optimize the temperature in specific rooms. The engineers at ecobee jumped at the chance to help Amazon define the integration and product requirements for the new feature.

Why? First, ecobee was the first to allow iOS users to control their thermostats with the Siri voice interface when they integrated Apple’s HomeKit API into their smartphone app. “But Alexa’s way different,” said Hesham Fahmy, Vice President of Technology for ecobee. “One of our biggest product benefits is ‘Comfort where it matters,’ which is especially true with our remote sensor capabilities.” To Fahmy, it made perfect sense to connect your ecobee device to Alexa and say, “Alexa, turn up the temperature” without needing to find your phone.

The ecobee engineering team built a prototype skill as soon as the Alexa Skills Kit (ASK) was released, just to gauge interest from customers and ecobee owners loved it and Fahmy and the team were excited about being able to connect directly to the Alexa thermostat capabilities. “Just saying ‘Alexa raise the temperature’ is very easy and natural,” he said.

The Amazon Alexa team had the same idea for their new Smart Home Skill API. So when they invited the ecobee team to their labs as part of the beta program, Fahmy and his team jumped at the chance. Off flew the ecobee engineers, packing their deep knowledge of HVAC systems, to provide early feedback on the thermostat integration in the Smart Home Skill API.

In one whirlwind week, the ecobee and Alexa teams constructed a working model.

Day 0: Before Fahmy’s team had packed their bags, the API team sent an “alpha” draft of what the proposed API would look like. Fahmy says, “It had the bare minimum scenarios. Turn the temperature up. Turn it down. Not much more.”

Day 1: Fahmy brought his prototype and proof-of-concept code, including stubs for OAuth authentication to allow Alexa to link to an ecobee account. The teams spent the first day wiring that AWS Lambda function to OAuth endpoints in Amazon’s lab. By end of the day, they were satisfied the pieces were in place and connected. “It was pretty grueling, but we had all the main building blocks,” says Fahmy.

Day 2: The team spent the next morning discussing both the happy paths and the error scenarios. The rest of the day, Fahmy and the Amazon API team drafted “version 2” of the API, noting the changes required and the responses to specific error conditions. “Many of the API changes we coded live, on-the-fly, right there in Amazon’s lab,” says Fahmy.

Day 3: The last day was spent wrapping up, reviewing all the changes and seeing how well they worked. “By the end of the day, we actually had a working model. We were very excited!” said Fahmy.

The basic Smart Home Skill API—at least the thermostat portion—now had a pulse, but it wasn’t nearly “done” yet. When they returned home, the team had very clear action items.

• Weekly calls with the API team to discuss and receive incremental changes from them
• Re-implement and republish the OAuth authentication function
• Review the “tabled” nice-to-have features and commands with user forums
• Weekly testing and checkpoints, both for the project and technical sides

During the beta period, ecobee released their smart home skill. From the first October meetings to release, Fahmy says it took under six weeks to achieve the first milestone of a field trial with Amazon beta users. After gathering user feedback, the smart home skill, plus the ecobee skill adapter, went live to the public in early February. 

Asked if he had any advice for developers who plan to use the Smart Home Skill API, Fahmy said the API itself was simple to use. “It’s a RESTful API using JSON payloads. Any developer can understand it and come up with a solution quickly.” But he warns developers should really think hard about customer use cases before jumping in and writing a single line of code.

“Even when working directly with the Amazon team, we took a step back. Forget the code and the APIs. What does the user really want? How would they want to request it?”

Fahmy says taking time to nail down those use cases gives you a fast implementation blueprint. “When you do that, you’ll know exactly which of the APIs you’re going to use, how you will stitch them together. That’s the secret sauce.”

If you have an ecobee smart thermostat and an Amazon Echo, it’s time to get even more comfortable in your smart home. Get started by saying “Alexa, discover devices.” Here’s a complete list of voice commands you can use with your ecobee.

Share other innovative ways you’re using Alexa in your life. Tweet us @alexadevs with hashtag #AlexaDevStory.

Get Started with Alexa Skills Kit

Are you ready to build your first (or next) Alexa skill? Build a custom skill or use one of our easy tutorials to get started quickly.