Build a Working Smart Home Skill in 15 Minutes

briankel edited this page Mar 13, 2018 · 9 revisions

Overview

If you would like to learn everything about building Smart Home skills for Alexa, please review our documentation on developer.amazon.com. You can also jump straight into the API reference, and come back to this GitHub repo for Tools and Resources.

However, if you follow the next few steps, you can get a working Smart Home skill built in about 15 minutes. This skill will introduce you to the basics of Smart Home skills, and give you the foundations upon which you can build support for the rest of our Smart Home APIs, and integrate with your user accounts and actual devices.

Prerequisites

  • An Amazon developer account, created one here if needed
    • This is required for building and managing skills
    • This is also required if you plan to use Login with Amazon (LWA) as your OAuth provider. OAuth integration is required for Smart Home skills
    • This is an Amazon account, so it can also be used as an Alexa user for testing
  • An Alexa-enabled device associated with the above account
  • An AWS account -- create one here if needed
    • This is required for building and hosting Lambda functions, which are required for Smart Home skills

Five Easy Steps

Please refer to our official documentation for detailed steps to creating a skill. However, it boils down to the following five easy steps:

  1. Setup LWA
  2. Create the skill
  3. Create the Lambda function
  4. Configure the skill
  5. Test

Setup LWA

Smart Home skills require that a user completes account linking during skill enablement. This step asks customers to associate their device cloud account with your smart home skill. You will need an OAuth provider in order to implement this process. If you don't already have an OAuth provider, you can use Login with Amazon (LWA).

If you decide to use LWA, follow these instructions:

  1. Connect to https://developer.amazon.com/login.html and authenticate with your Amazon credentials.
  2. Click on “Apps & Services”, then “Login with Amazon”
  3. Click on “Create a New Security Profile”
  4. Fill in all three required fields to create your security profile and click “Save”.
  5. Before you complete this step, be sure to click on the link named “Show Client ID and Client Secret” and save these values to a secure location so they're easily available later. You’ll need these values later in a future step.

Create the skill

This is super easy! The steps here will provide you with the bare minimum required for a working Smart Home skill.

  1. Go to https://developer.amazon.com/login.html and sign in
  2. Go to Alexa > Alexa Skills Kit (Get Started) > Add a New Skill
  3. In the Skill Information tab:
    • Skill Type = Smart Home Skill API
    • Name = Test Smart Home Skill (or whatever you want)
    • Payload Version = v3
    • Click Save

This creates the skill. Note the skill ID near the top, underneath your skill name.

  • Skill ID:

Create the Lambda function

This can't be easier! We've provided you with a sample Lambda function that you can just plug and play. To get the sample:

  1. Clone this repo (https://github.com/alexa/alexa-smarthome)
  2. Navigate to /sample_lambda/python
  3. Copy the file alexa_smart_home_message_schema.json into this directory.
  4. Zip all contents of that directory to python.zip. NOTE: Take care to ensure that the files from /sample_lambda/python appear in the root of your .zip file, not in a nested subfolder.

Now let's setup the Lambda function:

  1. Go to https://console.aws.amazon.com/console/home and sign in
  2. Go to Services > Compute > Lambda
  3. Click on Create Function
  4. Step 1: Click on Author from scratch
  5. Step 2: Configure your Lambda function
    • Name = SampleLambdaFunction (or whatever you want)
    • Role = Create a Custom Role which will launch a new tab. Click Allow to create a new role named lambda_basic_execution and automatically insert this role into the Lambda basic information dialog.
    • Click Create Function
  6. Step 3: Click Triggers -> Add Trigger and select Alexa Smart Home
    • Application Id = skill ID of your test skill that you noted above
    • Enable trigger = checked
    • Click Submit
  7. Step 4: Click Configuration
    • Runtime = Python 3.6
    • Code entry type = Upload a .ZIP file
    • Click on Upload and find the python.zip you created earlier
    • Handler = lambda.lambda_handler
    • Click Next
    • Click Save
    • On the top right corner, note the Lambda ARN
  • Lambda ARN:

Configure skill

Now that you have all the components, let's put everything together. These steps assume you're using LWA for account linking:

  1. Go back to https://developer.amazon.com/home.html and sign in as needed
  2. Go to Alexa > Alexa Skills Kit > the test skill you created earlier
  3. In the Configuration tab:
    • Lambda ARN default = enter your Lambda ARN noted from the previous step
    • Authorization URI = https://www.amazon.com/ap/oa
    • Client ID = your client ID from LWA noted in a previous step
    • Scope: profile (click Add Scope first to add)
    • Access Token URI: https://api.amazon.com/auth/o2/token
    • Client Secret: your client secret from LWA noted in a previous step
    • Client Authentication Scheme: HTTP Basic (Recommended)
    • Click Save
  4. Provide Redirect URL's to LWA:
    • The Configuration page for your Skill lists several Redirect URL's. Open the LWA security profile you created earlier and visit the Web Settings dialog. Provide each of the Redirect URL values from your Skill in the Allowed Return URL's field.

That's it!

Test!

Now comes the fun part:

  1. Go to https://alexa.amazon.com in your browser
  2. Login with same Amazon developer account
  3. Make sure you have an Alexa device associated with the account. If not, open a new tab and load one of the virtual ones mentioned above
  4. Go to Skills > Your Skills (on the top right corner) and search for your test skill, it should be there with a "devUS" tag
  5. Click on the skill and then click Enable
  6. Log in with the same Amazon credentials when presented with a LWA login page
  7. Allow LWA access, and you should see a message that says you can close this window. Close that window and you should be presented with a popup asking to discovery devices. Click Discover Devices.
  8. Go to Smart Home > Devices and you should see several virtual devices
  9. Now with your Alexa device, try "Alexa, turn on switch". In CloudWatch, you should see a PowerController.TurnOn directive come to your Lambda, and see that a PowerController response was sent back to Alexa. That allowed you to hear Alexa respond with "OK".

And there you have it, a fully working Smart Home skill. Perhaps it look a little longer than 15 mins, but hopefully it was pretty straightforward. Now that you have a working skill, head on over to our more comprehensive documentation to learn more about other concepts such as the various capability interfaces and how to send events to Alexa.

FAQ

  1. After following instructions, I can get my skill linked. But after discovery, I don't see any devices.

    Did you receive a Discovery directive at your Lambda? If not, then check your Lambda console to confirm if you have enabled the Alexa Smart Home trigger and the Application ID matches your skill ID in the Developer Console.

    If you received the Discovery directive, did you send back a valid Discovery response? Please validate the response against the Validation Schemas.

    If all these check out, post a question by methods below.

Other Questions

If you have any questions, don't hesitate to ask in our forums or post in Issues here. Good luck!

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.