Steps to Build a Smart Home Skill

This topic provides the steps for creating a smart home skill that responds synchronously to directives. The steps will walk you through skill creation in the developer console, creating an AWS Lambda function, configuring and testing your skill, and submitting it for certification.

Register as an Amazon Developer and Create the Skill

To configure a new smart home skill, you need an account on the Amazon Developer Console. If you don’t already have an account, go to https://developer.amazon.com/alexa/console/ask and create an account. Registering is free. Once you’ve registered:

Enter the Skill name. Note that your skill's name must not indicate that it's functionality is limited. For example, you should not use "basic", "reduced" or "simple" in the title of your skill. The skill will default to English (US). Change the Default language using the drop-down, if you are targeting a different region/language. See Build Smart Home Skills in Multiple Languages to see the device categories that are supported for each language.

Under Choose a model to add to your skill page, select Smart Home, which is a pre-built model, and click Create skill.

Under Payload Version, select v3.

Click Save and copy Your Skill ID to the clipboard. The ID will be in a format similar to the following:
amzn1.ask.skill.1a2b55555-c325-1234-d56e-1f234d5e6a78

Next, you will create a Lambda function so that you can configure the Smart Home service endpoint.

Add a Lambda Function

You will need an AWS account and some basic knowledge of AWS. The code for your smart home skill is hosted as a Lambda function on AWS. AWS Lambda is a service that lets you run code in the cloud without managing servers. Alexa sends your skill requests and your code inspects the request, takes any necessary actions such as communicating with the device cloud for that customer, and then sends back a response.

Create an IAM Role for Lambda

If you haven't worked with Lambda before, you will need to create an Identity and Access Management (IAM) role that enables basic execution. To create an IAM role. Navigate to the IAM console. If you already have a role that enables Lambda basic execution, skip to the next section.

Choose Roles and click Create a new role.

Select AWS Lambda under AWS Service Role.

Type "basic" in the filter box and choose the AWSLambdaBasicExecutionRole, and click Next Step.

Enter a name that identifies this role and click Create role.

Create a Lambda function and add code

On the AWS Console, under Compute, select Lambda.

Make sure you’ve selected:

N.Virginia for English (US) or English (CA) skills

EU (Ireland) region for English (UK), English (IN), German or French (FR) skills

US West (Oregon) for Japanese and English (AU) skills.

The region is displayed in the upper right corner. Providing your Lambda function in the correct region prevents latency issues.

Click Create a Lambda function.

Select Author from scratch, and enter the following information:

Name: Provide a name for your Lambda function. This name is 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.

Runtime: To use the sample code provided in this topic, choose Node.js 6.10 or alternatively, select the runtime for the code you plan to write. Supported languages are:
Node.js, Java, Python, or C#.

Click Create Function. Your function should be created and you will move to Configuration.

In the Configuration designer, under Add triggers select the Alexa Smart Home trigger.

In the Configure triggers section, add the Skill ID from the developer console in the box specified.

Leave Enable trigger checked. This enables the Amazon Alexa service to call your Lambda function. If you don't enable it when you create, you will not be able to enable it in the console later.

Click Add and then click Save.

Note: You can write Lambda function code in C#, Java, Node.js and Python. This topic provides sample code in Node.js and some of the steps are specific to the sample code.

At the top of the page, select the Lambda function to display the function code. Following is an example of the Lambda function.

In the Function code section make sure Edit code inline is selected. Leave the Runtime and Handler set to their defaults.

Paste in the following code, completely replacing the code in index.js.

Important: This code provides a starting point for implementing a smart home skill and provides the basic structure for responding to a discovery and one control request. You must add code to respond to ReportState directives and code specific to your device types and the interfaces that your devices support. You can find additional sample code in the GitHub repository for Alexa smart home.

exports.handler=function(request,context){if(request.directive.header.namespace==='Alexa.Discovery'&&request.directive.header.name==='Discover'){log("DEBUG:","Discover request",JSON.stringify(request));handleDiscovery(request,context,"");}elseif(request.directive.header.namespace==='Alexa.PowerController'){if(request.directive.header.name==='TurnOn'||request.directive.header.name==='TurnOff'){log("DEBUG:","TurnOn or TurnOff Request",JSON.stringify(request));handlePowerControl(request,context);}}functionhandleDiscovery(request,context){varpayload={"endpoints":[{"endpointId":"demo_id","manufacturerName":"Smart Device Company","friendlyName":"Bedroom Outlet","description":"Smart Device Switch","displayCategories":["SWITCH"],"cookie":{"key1":"arbitrary key/value pairs for skill to reference this endpoint.","key2":"There can be multiple entries","key3":"but they should only be used for reference purposes.","key4":"This is not a suitable place to maintain current endpoint state."},"capabilities":[{"type":"AlexaInterface","interface":"Alexa","version":"3"},{"interface":"Alexa.PowerController","version":"3","type":"AlexaInterface","properties":{"supported":[{"name":"powerState"}],"retrievable":true}}]}]};varheader=request.directive.header;header.name="Discover.Response";log("DEBUG","Discovery Response: ",JSON.stringify({header:header,payload:payload}));context.succeed({event:{header:header,payload:payload}});}functionlog(message,message1,message2){console.log(message+message1+message2);}functionhandlePowerControl(request,context){// get device ID passed in during discoveryvarrequestMethod=request.directive.header.name;varresponseHeader=request.directive.header;responseHeader.namespace="Alexa";responseHeader.name="Response";responseHeader.messageId=responseHeader.messageId+"-R";// get user token pass in requestvarrequestToken=request.directive.endpoint.scope.token;varpowerResult;if(requestMethod==="TurnOn"){// Make the call to your device cloud for control// powerResult = stubControlFunctionToYourCloud(endpointId, token, request);powerResult="ON";}elseif(requestMethod==="TurnOff"){// Make the call to your device cloud for control and check for success// powerResult = stubControlFunctionToYourCloud(endpointId, token, request);powerResult="OFF";}varcontextResult={"properties":[{"namespace":"Alexa.PowerController","name":"powerState","value":powerResult,"timeOfSample":"2017-09-03T16:20:50.52Z",//retrieve from result."uncertaintyInMilliseconds":50}]};varresponse={context:contextResult,event:{header:responseHeader,endpoint:{scope:{type:"BearerToken",token:requestToken},endpointId:"demo_id"},payload:{}}};log("DEBUG","Alexa.PowerController ",JSON.stringify(response));context.succeed(response);}};

Finish configuring and test the Lambda function

Click Save.

If you want to perform a quick test of the Discovery request in the Lambda code editor, you can click on Test. The Configure test event page appears.

Leave Create new test event selected. For Event template, leave the default Hello World. In the Event name, enter discovery and replace the entire contents in the editor with the following code.

Click Create, and then Test. If successful, the Execution Result should be similar to the following:

{"event":{"header":{"correlationToken":"12345692749237492","messageId":"1bd5d003-31b9-476f-ad03-71d471922820","name":"Discover.Response","namespace":"Alexa.Discovery","payloadVersion":"3"},"payload":{"endpoints":[{"endpointId":"demo_id","manufacturerName":"Smart Device Company","friendlyName":"Bedroom Outlet","description":"Smart Device Switch","displayCategories":["SWITCH"],"cookie":{"key1":"arbitrary key/value pairs for skill to reference this endpoint.","key2":"There can be multiple entries","key3":"but they should only be used for reference purposes.","key4":"This is not a suitable place to maintain current endpoint state."},"capabilities":[{"type":"AlexaInterface","interface":"Alexa","version":"3"},{"interface":"Alexa.PowerController","version":"3","type":"AlexaInterface","properties":{"supported":[{"name":"powerState"}],"retrievable":true}}]}]}}}

Configure the Smart Home Service Endpoint

You must provide the ARN for your Lambda function in the skill configuration in the developer console.

Navigate back to your skill in the Developer Console.

Under 2. Smart Home service endpoint, in the Default endpoint box, provide the ARN number from the Lambda function you created and click Save. If you are creating multiple language versions of your skill, you must provide geographic-specific endpoints. The following table lists mapping between the language you select for your skill, the regional endpoint and regions for your Lambda function.

Skill language

Endpoint Region

Lambda Function Region

English (US), English (CA)

North America

US East (N. Virginia)

English (UK), French (FR), German, Italian, Spanish (ES)

Europe, India

EU (Ireland)

English (IN)

Europe, India

EU (Ireland)

Japanese, English (AU)

Far East

US West (Oregon)

If your skill only supports one language/region, provide the same ARN for the default ARN and the selected regional ARN.

If your skill supports multiple languages/regions, you must provide ARNs for each region. Provide one of the regional ARNs for the default.

Provide Account Linking Information

In the Section 3. Account Linking, click Setup Account Linking
This section requires account information from your OAuth 2.0 provider, which enables customers to associate their device cloud account with your smart home skill. You can use Login with Amazon or another OAuth provider for this section.
You provide:

Test Your Skill

When your implementation is complete, and you've tested your Lambda function, you can functionally test your smart home skill.

Make sure you have a smart home trigger added and enabled. To check this, go to the Lambda console, select your smart home skill, and make sure you have an Alexa Smart Home trigger.

Sign in to the Alexa app (available on Android, IOS or the web at https://alexa.amazon.com) with the same credentials as your developer account.

Find your skill in the Alexa app. To do this, go to Skills, and tap Your Skills in the upper right corner of the All Skills page. Scroll to DEV SKILLS and find your skill.

Click the ENABLE button to enable the skill, and you will be directed to account-link the skill to a device cloud account. If you are unable to complete account linking, make sure you are using valid credentials for the device cloud. Otherwise, it is likely there is an issue with account-linking information you provided in the developer console. For help with this, see Alexa: Debugging account linking in the developer forums. If you want to remove account linking later, you should disable your skill in the Skills tab.

Close the window and tap the DISCOVER DEVICES button in the Alexa app.

If the skill does not discover devices, check the logs for your Lambda function to see if it received a discover directive from Alexa, and use the logs to troubleshoot the issue. Common issues include incorrectly formatted event responses.

If your skill successfully discovers devices, return to the Test page of the developer console. On the Test page, move the test slider to Yes and use the Alexa Simulator to give Alexa commands using the device names found in the discovery process and utterances your skill supports. Make sure and test the skill with valid utterances and invalid ones, meaning ask your skill to do things that should work, and things that should not work, 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 provide it for beta testing or submit it for certification.

Provide Launch Information

To provide your skill to customers for beta testing or submit your skill for certification, you must provide some information that is used to describe your skill in the Alexa app.

Select Distribution, and on the English (US) Store Preview page, specify:

Public Name.

One Sentence Description

Detailed Description

Example Phrases

Small Skill Icon

Large Skill Icon

Keywords

Privacy Policy URL

Terms of Use URL.

Use the tooltips provided on the page for assistance in completing these fields. For more detailed instructions about how to complete these fields, see the Smart Home Skill Publishing Guide.

Click Save and Continue

On the Privacy and Compliance page, answer the questions provided.
For Testing Instructions, provide test account credentials.
You should make sure your testing instructions and other publishing information follows the guidelines in our Publishing Guide.

Click Save and Continue

On the Availability page, check whether your skill is public, or for use by Alexa for Business Organizations.

Select the countries and regions you would like to distribute your skill

Click Save and Continue

Optionally Do Beta Testing

At this point, the Beta Test button should be enabled, and you can complete information to start a beta test. For more information, see Skills Beta Testing.

Submit Your Skill for Certification

If you have completed all of the fiends successfully, you should see a large green check mark and Your skill is ready for submission.

Submit Changes to a Live Skill

Once your skill is live, any changes to the skill must be certified. For example, your skill must be recertified as part of changing the information you provided about your skill in the developer console or changing the AWS Lambda function. The certification review varies depending on the changes, and updating the Lambda function may trigger additional review.

When a skill status is changed to live, a new Development version is automatically created in the developer console and displays immediately below the live skill. This version has the same information as the original live version. You can use it to continue to work on your skill to improve it and add features.

When you submit your updated skill to the developer console, in the Testing Instructions field, add a change log that provides a detailed description of all changes.

To Update Your Lambda function

Do the following to update your AWS Lambda function:

Create a new Lambda function with a new ARN, and copy your live Lambda function into the new Lambda function.

Make your updates in the new Lambda function. Avoid updating the live Lambda function that supports your live skill, and avoid Lambda aliases or versioning because they do not work reliably once your skill is updated.

In the development stage for your skill, update the Lambda ARN configuration to point to the new Lambda ARN.

After your skill is recertified and pushed live, your skill points to the new Lambda ARN. You can then deprecate the previous Lambda function or use the function for future development or updates.