The Smart Home Skill API is a new addition to the Alexa Skills Kit, which enables developers to add capabilities, called skills, to Alexa. With this new API you can teach Alexa how to control your own cloud-controlled lighting and thermostat devices. For example, customers can simply say, “Alexa, turn on the kitchen lights” or “Alexa, turn up the heat downstairs” and Alexa will communicate directly with your Smart Home device. Smart home skills are created in the same developer portal as existing custom skills and follow a similar process.

Creating a Smart Home Skill

To create your smart home skill, you’ll first configure your skill using a new Smart Home Skill API flow in the developer portal. Ensure you have selected the Smart Home Skill API skill type, enter a Name for your skill and then simply click Next.

Unlike custom skills, smart home skills already have an existing interaction model for you. This means you won’t have to define the intent schema and sample utterances like you would in a custom skill. Click Next to move to the Configuration tab.

 

Configuring a Smart Home Skill Adaptor

The configuration tab will be where you set up your skill adapter and skill authorization, via oAuth. The skill adapter translates between Alexa’s skills and your device’s proprietary control systems, as the means to relay discovery and control commands from Alexa to your device control cloud. Alexa acts as an OAuth client and requests resources from the device control cloud. To facilitate this, you will need to provide information about your OAuth server information when creating a skill adapter so the user of the application can grant permissions for Alexa to retrieve device information. That information can then be used to control those devices. 

We will be using AWS Lambda to create our skill adapter using a Lambda blueprint that has already been created for us to quickly get started. To get started, sign in to your AWS Account, and create the Lambda function. To do this: 

• On the AWS Console, under Compute, select Lambda.
• Make sure you’ve selected the N.Virginia region for your account. The region is displayed in the upper right corner. Currently, N. Virginia is the only supported region for Lambda functions used with the Alexa Skills Kit.
• Click Create a Lambda function.

• On Step 1: Select blueprint page, type home in the filter box. Select the alexa-smart-home-skill-adapter.

• On Step 2: Configure event sources page, make sure the Event source type is set to Alexa Connected Home.
• On the same page, for Alexa Application ID, add the Application Id from the developer portal. Click Next.

Your final event sources configuration screen should look similar to this:

• On Step 3: Configure function, enter the following:
  • Name: A name for your Lambda function. This name appears in the AWS console and is also returned by the AWS command-line interface (CLI) ListFunctions API. It should be unique across your Lambda functions.
  • Description: Optionally provide a description.
  • Runtime: Select Python 2.7. Lambda also supports Node.js and Java, but the example you will work with is in Python.
• For Lambda function code, make sure Edit code inline is selected.
• Copy and paste the following code into the code editor. This code determines the request type by determining the namespace and name values in the message header. The namespace specifies whether the request is a discovery or control request, and calls either thehandleDiscovery or handleControl function, respectively.

In addition, for a control request, the name specifies the kind of request. In this example code, the only request type handled is aTurnOnRequest. You should handle every type of request a user would make to your skill. For information about all of the request and response messages, see Smart Home Skill  API Reference. 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56

def lambda_handler(event, context):     access_token = event['payload']['accessToken']       if event['header']['namespace'] == 'Alexa.ConnectedHome.Discovery':         return handleDiscovery(context, event)       elif event['header']['namespace'] == 'Alexa.ConnectedHome.Control':         return handleControl(context, event)   def handleDiscovery(context, event):     payload = ''     header = {         "namespace": "Alexa.ConnectedHome.Discovery",         "name": "DiscoverAppliancesResponse",         "payloadVersion": "2"         }       if event['header']['name'] == 'DiscoverAppliancesRequest':         payload = {             "discoveredAppliances":[                 {                     "applianceId":"device001",                     "manufacturerName":"yourManufacturerName",                     "modelName":"model 01",                     "version":"your software version number here.",                     "friendlyName":"Smart Home Virtual Device",                     "friendlyDescription":"Virtual Device for the Sample Hello World Skill",                     "isReachable":True,                     "actions":[                         "turnOn",                         "turnOff"                     ],                     "additionalApplianceDetails":{                         "extraDetail1":"optionalDetailForSkillAdapterToReferenceThisDevice",                         "extraDetail2":"There can be multiple entries",                         "extraDetail3":"but they should only be used for reference purposes.",                         "extraDetail4":"This is not a suitable place to maintain current device state"                     }                 }             ]         }   def handleControl(context, event):     payload = ''     device_id = event['payload']['appliance']['applianceId']     message_id = event['header']['messageId']       if event['header']['name'] == 'TurnOnRequest':         payload = { }       header = {         "namespace":"Alexa.ConnectedHome.Control",         "name":"TurnOnConfirmation",         "payloadVersion":"2",         "messageId": message_id         }

• For Handler leave the default name lambda_function.lambda_handler. A function handler is the main entry point for a Lambda function, and you specify it with the format fileName.entryPointFunctionName. When you edit code inline in the console, the file name is lambda_function and the lambda_handler function is the entry point in this code.
• For Role, select Lambda_basic_execution role, you should see something similar to the following:   

• Leave the Advanced settings set to the defaults and click Next.
• On Step 4: Review page, you should see something similar to the following:   

• Click Create function.
• On the summary page, copy the Amazon Resource Name (ARN) for your Lambda function, which is found in the upper right corner, into your clipboard. You will use this value when you configure the smart home skill in the developer portal. The ARN should be similar to the following: arn:aws:lambda:us-east-1:053208314052:function:myLightBulbFunction.

Setting up Authentication

To finish registering your skill, you must configure OAuth 2.0 for your skill. You can use Login with Amazon or another provider for this section.

• Navigate back to your skill in the Developer Portal. To do this, log in, and navigate to the Alexa section by clicking Apps & Services and then clicking Alexa in the top navigation. Select your skill from the displayed list.
• On the Configuration page, in the Endpoint field, copy in the ARN number from the Lambda function you created.
• You also must enable Account Linking for your skill. This allows end-users to associate their cloud-enabled devices with the Alexa skill, and where you need OAuth 2.0 information for the device cloud your skill communicates with. To learn more about account linking, see Linking an Alexa User with a User in Your System.

The following fields are required:

• Authorization URL: This is the URL for your web site’s login page. Refer back to Adding Account Linking Support to Your Login Page for information about how this page is used when users link their accounts.
• Client ID: An identifier your login page uses to recognize that the request came from your skill. This value is passed to your authorization URL in the client_id parameter. You will use authorization code grant, which means this value is also part of the client credentials that the Alexa service includes when requesting an access token from the Access Token URI.
• Redirect URL: Enabling account linking displays your Redirect URL. This is the URL to which your login page must redirect the user after they are authenticated.

 

• Authorization Grant Type: Authorization Code Grant is preselected, as it’s the supported grant type for Smart Home Skill API. 
  For Authorization Code Grant, you must also fill in the following:
  • Access Token URI: The URL for the authorization server that provides the access tokens.
  • Client Secret: A credential you provide that lets the Alexa service authenticate with the Access Token URI This is combined with the Client Id to identify the request as coming from Alexa.
  • Client Authentication Scheme: Identifies the type of authentication Alexa should use when requesting tokens from the Access Token URI.
  • Privacy Policy URL: A URL for a page with your privacy policy. This link is displayed in the Alexa app and is required for smart home skills.

To learn more about Authorizing Alexa users with your Smart Home Skill check out the Linking an Alexa User with a User in Your System guide here.
 

• On the Test page, make sure that your skill is enabled for testing by choosing Yes.

 

Testing Your Smart Home Skill

You can now test your smart home skill by using it with your own Alexa-enabled device. To do this:

• You should enable and account-link your skill to the device cloud it is designed to work with on the Skills tab of the Alexa app. If you want to remove this later, you should disable your skill in the Skills tab.
• Discover and manage devices in the Your Devices section in the Smart Home tab of the Alexa app. 
• Give Alexa commands using the utterances your skill supports with device names you’ve set for devices in your account-linked device cloud. Make sure and test the skill with valid utterances and invalid ones, and in a variety of conditions, such as with a target device powered off.
• When you are satisfied with your smart home skill’s performance, you can submit it for certification.

Publishing Your Skill with the Smart Home Skill API

Like custom skills, smart home skills must pass our certification process before they go live. Learn more about our certification process here. Approved smart home skills will be available for customers in the Alexa app by the end of April. 

To start this process, do the following:

• Go back to your skill in the developer portal. To do this, open the Alexa section and click Get Started.
• Select your smart home skill and navigate to the Publishing Information page.

• This information displays with your skill in the Alexa app.
  • Descriptions: Complete the Short Skill and Full Skill descriptions.
  • Category: This is automatically set to Smart Home and cannot be changed.
  • Keywords: (optional) Add keyword appropriate for your skill.
  • Images: Add small and large icons per the guidelines specified.
  • Add any testing instructions necessary for the certification team.
  • Click Next.
• On the Privacy and Compliance page, answer the questions, and click Submit for Certification.

You have now successfully created and submitted a smart home skill for certification. If you have questions during the certification process you can reach the team directly here and selecting Alexa from the drop down subject.

Newly Redesigned Alexa Smart Home store on Amazon.com 

With the recent launch of Echo Dot and Amazon Tap, there are more ways than ever to control smart home devices like lights, switches, plugs, and thermostats using Alexa. To help customers find, discover and buy Alexa-compatible smart home devices, today we also introduced a refreshed Alexa Smart Home store. The store allows customers to shop smart home products by brand or solution and it offers brands new opportunities to get their products noticed by Alexa customers. To learn more, visit www.amazon.com/alexasmarthome.
 

For more information about getting started with Alexa Smart Home skills, check out the following additional assets:

Smart Home Skill API
Understanding the Smart Home Skill API
Creating a Smart Home Skill
Smart Home Skill API Reference
Alexa Training with Big Nerd Ranch
Intro to Alexa Skills On Demand
Voice Design 101 On Demand

-Dave (@TheDaveDev)