Step 2: Implement Skill Code

Note: Sign in to the developer console to build or publish your skill.

In the previous step, you created a new smart home skill in the Alexa developer console. Now you implement your smart home skill code as an Amazon Web Services (AWS) Lambda function. This function consists of your skill code, configuration information, and an Identity and Access Management (IAM) role that allows Lambda to run the skill code on your behalf. Optionally, Lambda functions can store data in AWS DynamoDB and write logs to AWS CloudWatch.

You can write your code in the AWS Lambda console directly or in a development environment appropriate for the programming language that you plan to use to code your skill. You can author a Lambda function in Node.js, Java, Python, C#, Go, Ruby, or PowerShell. For simplicity, this tutorial step uses the AWS Lambda console code editor and provides code examples in Python and Node.js.

Tutorial:
Build a Smart Home Skill

→

Step 1:
Create the Skill

→

Step 2:
Implement the Skill

→

Step 3:
Configure the Service Endpoint

→

Step 4:
Set up Account Linking

→

Step 5:
Test the Skill

Substeps to implement skill code

To implement the skill code that controls a virtual light bulb, complete the following substeps.

Set up permissions
Create an IAM role
Create a Lambda function
Add skill code
Test the Lambda function
Copy the resource name

Substep a: Set up permissions

In this substep, you create a policy that defines permissions that allow write access for log entries to AWS CloudWatch. In Step b, you attach the policy to an IAM role for your Lambda function.

To create an IAM policy in the AWS developer console

Sign in to the AWS management console.
Under AWS Services > All services > Security, Identity, & Compliance, click IAM.
Or, go directly to the IAM dashboard.
On the IAM dashboard, from the left menu under Access management, click Policies.
On the Policies page, click Create Policy.
On the Create policy page, select the JSON tab.
Copy and paste the following policy definition into the text area.

Copied to clipboard.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogStream",
                "logs:CreateLogGroup",
                "logs:PutLogEvents"
            ],
            "Resource": "*"
        }
    ]
}

Click Next: Tags.
Click Next: Review.
Under the Create policy > Review policy, for Name, enter smart_home_skill_policy.
You can leave the description blank.
To create the policy, click Create policy.

Now, you can see the smart_home_skill_policy in the list of available policies.

Substep b: Create an IAM role

In this substep, you attach the smart home policy to a new IAM role. In Step c, you assign the role to your Lambda function.

Note: These steps use the redesigned IAM roles page.

To create an IAM role for your AWS Lambda function in the AWS developer console

On the IAM dashboard, from the left menu under Access management, click Roles.
On the Roles page, click Create role.
On the IAM > Roles > Create role page, enter the following information:
1. Under Select trusted entity, for Trusted entity type, select AWS service.
2. Under Common use cases, select Lambda.
3. Click Next.
On the Add permissions page, filter to find the smart_home_skill_policy policy that you just created.
Select, click the check box next to smart_home_skill_policy policy,and then click Next.
On the Name, review, and create page, for Role name, enter lambda_smart_home_skill_role, and then click Create role.

Now, you can see the lambda_smart_home_skill_role in the list of available roles.

Substep c: Create a Lambda function

In this substep, you create a Lambda function and add the IAM role that allows Lambda to run your code on your behalf. Then, you add the example skill code.

To create an AWS Lambda function in the AWS developer console

Navigate to the Lambda console.
On the Lambda console, click Create function.
If you've created Lambda functions, the console displays a list of your functions.
Click Create function.
Note: In the upper-right corner, the console displays the AWS region where the Lambda function resides. This tutorial uses the North American region, AWS N. Virginia (us-east-1) region, and English (US). If you want to run your skill outside of North America, select a different AWS region and language. To learn more, see Develop Smart Home Skills for Multiple Languages.
Under Create function, select Author from scratch.
Under Basic information, enter the following information:
1. For Function name, enter my-smart-home-skill.
2. For Runtime, choose Python 3.9 or Node.js 14.x.
3. For Architecture, leave the default.
4. For Permissions > Change default execution role, select Use an existing role.
5. For Existing role, select lambda_smart_home_skill_role, and then select Create function.
On the Lambda > Functions > my-smart-home-skill page, under Function overview, click + Add trigger.
On the Add trigger page, enter the following information about to trigger your skill:
1. For Trigger configuration, select Alexa Smart Home.
2. For Application ID, paste the skill ID that you saved in Step 1: Create a Smart Home Skill.
3. To add the trigger to invoke your skill, click Add.

Substep d: Add skill code

Now, you add the example skill code to your Lambda function. On receipt of a directive from Alexa, the Lambda function executes your skill code.

Add the skill code to your Lambda function

On the Lambda > Functions > my-smart-home-skill page, to view the source code, select the Code tab.
For Python, your skill code resides in the file, lambda_function.py. For Node.js, your skill code resides in the file, index.js.
To display the function code, click lambda_function.py or index.js.
Replace the existing code with the following smart home skill code that controls the virtual light bulb.
The code supports the AcceptGrant, Discovery, TurnOn, and TurnOff directives.

Node.js
Python

Copied to clipboard.

// -*- coding: utf-8 -*-

// Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
//
// SPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0
// Licensed under the Amazon Software License (the "License")
// You may not use this file except in compliance with the License.
// A copy of the License is located at http://aws.amazon.com/asl/
//
// This file is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific
// language governing permissions and limitations under the License.

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, "");
    }
    else if (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);
        }
    }
    else if (request.directive.header.namespace === 'Alexa.Authorization' && request.directive.header.name === 'AcceptGrant') {
        handleAuthorization(request, context)
    }

    function handleAuthorization(request, context) {
        // Send the AcceptGrant response
        var payload = {};
        var header = request.directive.header;
        header.name = "AcceptGrant.Response";
        log("DEBUG", "AcceptGrant Response: ", JSON.stringify({ header: header, payload: payload }));
        context.succeed({ event: { header: header, payload: payload } });
    }

    function handleDiscovery(request, context) {
        // Send the discovery response
        var payload = {
            "endpoints":
            [
                {
                    "endpointId": "sample-bulb-01",
                    "manufacturerName": "Smart Device Company",
                    "friendlyName": "Livingroom lamp",
                    "description": "Virtual smart light bulb",
                    "displayCategories": ["LIGHT"],
                    "additionalAttributes":  {
                        "manufacturer" : "Sample Manufacturer",
                        "model" : "Sample Model",
                        "serialNumber": "U11112233456",
                        "firmwareVersion" : "1.24.2546",
                        "softwareVersion": "1.036",
                        "customIdentifier": "Sample custom ID"
                    },
                    "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":
                    [
                        {
                            "interface": "Alexa.PowerController",
                            "version": "3",
                            "type": "AlexaInterface",
                            "properties": {
                                "supported": [{
                                    "name": "powerState"
                                }],
                                 "retrievable": true
                            }
                        },
                        {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                    ]
                }
            ]
        };
        var header = request.directive.header;
        header.name = "Discover.Response";
        log("DEBUG", "Discovery Response: ", JSON.stringify({ header: header, payload: payload }));
        context.succeed({ event: { header: header, payload: payload } });
    }

    function log(message, message1, message2) {
        console.log(message + message1 + message2);
    }

    function handlePowerControl(request, context) {
        // get device ID passed in during discovery
        var requestMethod = request.directive.header.name;
        var responseHeader = request.directive.header;
        responseHeader.namespace = "Alexa";
        responseHeader.name = "Response";
        responseHeader.messageId = responseHeader.messageId + "-R";
        // get user token pass in request
        var requestToken = request.directive.endpoint.scope.token;
        var powerResult;

        if (requestMethod === "TurnOn") {

            // Make the call to your device cloud for control
            // powerResult = stubControlFunctionToYourCloud(endpointId, token, request);
            powerResult = "ON";
        }
       else if (requestMethod === "TurnOff") {
            // Make the call to your device cloud for control and check for success
            // powerResult = stubControlFunctionToYourCloud(endpointId, token, request);
            powerResult = "OFF";
        }
        // Return the updated powerState.  Always include EndpointHealth in your Alexa.Response
        // Datetime format for timeOfSample is ISO 8601, `YYYY-MM-DDThh:mm:ssZ`.
        var contextResult = {
            "properties": [{
                "namespace": "Alexa.PowerController",
                "name": "powerState",
                "value": powerResult,
                "timeOfSample": "2022-09-03T16:20:50.52Z", //retrieve from result.
                "uncertaintyInMilliseconds": 50
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                "value": "OK"
            },
            "timeOfSample": "2022-09-03T22:43:17.877738+00:00",
            "uncertaintyInMilliseconds": 0
            }]
        };
        var response = {
            context: contextResult,
            event: {
                header: responseHeader,
                endpoint: {
                    scope: {
                        type: "BearerToken",
                        token: requestToken
                    },
                    endpointId: "sample-bulb-01"
                },
                payload: {}
            }
        };
        log("DEBUG", "Alexa.PowerController ", JSON.stringify(response));
        context.succeed(response);
    }
};

Copied to clipboard.

# -*- coding: utf-8 -*-

# Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
#
# SPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0
# Licensed under the Amazon Software License (the "License")
# You may not use this file except in
# compliance with the License. A copy of the License is located at http://aws.amazon.com/asl/
#
# This file is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific
# language governing permissions and limitations under the License.


import json
import math
import random
import uuid
import logging
import datetime
from datetime import datetime, timezone

logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

def lambda_handler(request, context):

    # Dump the request for logging - check the CloudWatch logs.
    print('lambda_handler request  -----')
    print(json.dumps(request))


    if context is not None:
        print('lambda_handler context  -----')
        print(context)

    # Validate the request is an Alexa smart home directive.
    if 'directive' not in request:
        alexa_response = AlexaResponse(
            name='ErrorResponse',
            payload={'type': 'INVALID_DIRECTIVE',
                     'message': 'Missing key: directive, Is the request a valid Alexa Directive?'})
        return send_response(alexa_response.get())

    # Check the payload version.
    payload_version = request['directive']['header']['payloadVersion']
    if payload_version != '3':
        alexa_response = AlexaResponse(
            name='ErrorResponse',
            payload={'type': 'INTERNAL_ERROR',
                     'message': 'This skill only supports Smart Home API version 3'})
        return send_response(alexa_response.get())

    # Crack open the request to see the request.
    name = request['directive']['header']['name']
    namespace = request['directive']['header']['namespace']

    # Handle the incoming request from Alexa based on the namespace.
    if namespace == 'Alexa.Authorization':
        if name == 'AcceptGrant':
            # Note: This example code accepts any grant request.
            # In your implementation, invoke Login With Amazon with the grant code to get access and refresh tokens.
            grant_code = request['directive']['payload']['grant']['code']
            grantee_token = request['directive']['payload']['grantee']['token']
            auth_response = AlexaResponse(namespace='Alexa.Authorization', name='AcceptGrant.Response')
            return send_response(auth_response.get())

    if namespace == 'Alexa.Discovery':
        if name == 'Discover':
            # The request to discover the devices the skill controls.
            discovery_response = AlexaResponse(namespace='Alexa.Discovery', name='Discover.Response')
            # Create the response and add the light bulb capabilities.
            capability_alexa = discovery_response.create_payload_endpoint_capability()
            capability_alexa_powercontroller = discovery_response.create_payload_endpoint_capability(
                interface='Alexa.PowerController',
                supported=[{'name': 'powerState'}])
            capability_alexa_endpointhealth = discovery_response.create_payload_endpoint_capability(
                interface='Alexa.EndpointHealth',
                supported=[{'name': 'connectivity'}])
            discovery_response.add_payload_endpoint(
                friendly_name='Sample Light Bulb',
                endpoint_id='sample-bulb-01',
                capabilities=[capability_alexa, capability_alexa_endpointhealth, capability_alexa_powercontroller])
            return send_response(discovery_response.get())

    if namespace == 'Alexa.PowerController':
        # The directive to TurnOff or TurnOn the light bulb.
        # Note: This example code always returns a success response.
        endpoint_id = request['directive']['endpoint']['endpointId']
        power_state_value = 'OFF' if name == 'TurnOff' else 'ON'
        correlation_token = request['directive']['header']['correlationToken']

        # Check for an error when setting the state.
        device_set = update_device_state(endpoint_id=endpoint_id, state='powerState', value=power_state_value)
        if not device_set:
            return AlexaResponse(
                name='ErrorResponse',
                payload={'type': 'ENDPOINT_UNREACHABLE', 'message': 'Unable to reach endpoint database.'}).get()

        directive_response = AlexaResponse(correlation_token=correlation_token)
        directive_response.add_context_property(namespace='Alexa.PowerController', name='powerState', value=power_state_value)
        return send_response(directive_response.get())

# Send the response
def send_response(response):
    print('lambda_handler response -----')
    print(json.dumps(response))
    return response

# Make the call to your device cloud for control
def update_device_state(endpoint_id, state, value):
    attribute_key = state + 'Value'
    # result = stubControlFunctionToYourCloud(endpointId, token, request);
    return True

# Datetime format for timeOfSample is ISO 8601, `YYYY-MM-DDThh:mm:ssZ`.
def get_utc_timestamp(seconds=None):
    return datetime.now(timezone.utc).isoformat()

class AlexaResponse:

    def __init__(self, **kwargs):

        self.context_properties = []
        self.payload_endpoints = []

        # Set up the response structure.
        self.context = {}
        self.event = {
            'header': {
                'namespace': kwargs.get('namespace', 'Alexa'),
                'name': kwargs.get('name', 'Response'),
                'messageId': str(uuid.uuid4()),
                'payloadVersion': kwargs.get('payload_version', '3')
            },
            'endpoint': {
                "scope": {
                    "type": "BearerToken",
                    "token": kwargs.get('token', 'INVALID')
                },
                "endpointId": kwargs.get('endpoint_id', 'INVALID')
            },
            'payload': kwargs.get('payload', {})
        }

        if 'correlation_token' in kwargs:
            self.event['header']['correlation_token'] = kwargs.get('correlation_token', 'INVALID')

        if 'cookie' in kwargs:
            self.event['endpoint']['cookie'] = kwargs.get('cookie', '{}')

        # No endpoint property in an AcceptGrant or Discover request.
        if self.event['header']['name'] == 'AcceptGrant.Response' or self.event['header']['name'] == 'Discover.Response':
            self.event.pop('endpoint')

    def add_context_property(self, **kwargs):
        self.context_properties.append(self.create_context_property(**kwargs))
        self.context_properties.append(self.create_context_property())


    def add_cookie(self, key, value):

        if "cookies" in self is None:
            self.cookies = {}

        self.cookies[key] = value

    def add_payload_endpoint(self, **kwargs):
        self.payload_endpoints.append(self.create_payload_endpoint(**kwargs))


    def create_context_property(self, **kwargs):
        return {
            'namespace': kwargs.get('namespace', 'Alexa.EndpointHealth'),
            'name': kwargs.get('name', 'connectivity'),
            'value': kwargs.get('value', {'value': 'OK'}),
            'timeOfSample': get_utc_timestamp(),
            'uncertaintyInMilliseconds': kwargs.get('uncertainty_in_milliseconds', 0)
        }

    def create_payload_endpoint(self, **kwargs):
        # Return the proper structure expected for the endpoint.
        # All discovery responses must include the additionAttributes
        additionalAttributes = {
            'manufacturer': kwargs.get('manufacturer', 'Sample Manufacturer'),
            'model': kwargs.get('model_name', 'Sample Model'),
            'serialNumber': kwargs.get('serial_number', 'U11112233456'),
            'firmwareVersion': kwargs.get('firmware_version', '1.24.2546'),
            'softwareVersion': kwargs.get('software_version', '1.036'),
            'customIdentifier': kwargs.get('custom_identifier', 'Sample custom ID')
        }

        endpoint = {
            'capabilities': kwargs.get('capabilities', []),
            'description': kwargs.get('description', 'Smart Home Tutorial: Virtual smart light bulb'),
            'displayCategories': kwargs.get('display_categories', ['LIGHT']),
            'endpointId': kwargs.get('endpoint_id', 'endpoint_' + "%0.6d" % random.randint(0, 999999)),
            'friendlyName': kwargs.get('friendly_name', 'Sample light'),
            'manufacturerName': kwargs.get('manufacturer_name', 'Sample Manufacturer')
        }

        endpoint['additionalAttributes'] = kwargs.get('additionalAttributes', additionalAttributes)
        if 'cookie' in kwargs:
            endpoint['cookie'] = kwargs.get('cookie', {})

        return endpoint

    def create_payload_endpoint_capability(self, **kwargs):
        # All discovery responses must include the Alexa interface
        capability = {
            'type': kwargs.get('type', 'AlexaInterface'),
            'interface': kwargs.get('interface', 'Alexa'),
            'version': kwargs.get('version', '3')
        }
        supported = kwargs.get('supported', None)
        if supported:
            capability['properties'] = {}
            capability['properties']['supported'] = supported
            capability['properties']['proactivelyReported'] = kwargs.get('proactively_reported', False)
            capability['properties']['retrievable'] = kwargs.get('retrievable', False)
        return capability

    def get(self, remove_empty=True):

        response = {
            'context': self.context,
            'event': self.event
        }

        if len(self.context_properties) > 0:
            response['context']['properties'] = self.context_properties

        if len(self.payload_endpoints) > 0:
            response['event']['payload']['endpoints'] = self.payload_endpoints

        if remove_empty:
            if len(response['context']) < 1:
                response.pop('context')

        return response

    def set_payload(self, payload):
        self.event['payload'] = payload

    def set_payload_endpoint(self, payload_endpoints):
        self.payload_endpoints = payload_endpoints

    def set_payload_endpoints(self, payload_endpoints):
        if 'endpoints' not in self.event['payload']:
            self.event['payload']['endpoints'] = []

        self.event['payload']['endpoints'] = payload_endpoints

To save the file, under File, select Save.
To deploy the function, select Deploy.

In the green box at the top of the Lambda > Functions > my-smart-home-skill page, you see a message that says that the function updated successfully.

Substep e: Test the Lambda function

After you save your skill code, you can invoke the Lambda function and view the results in the AWS developer console. The following code examples send an Alexa.Discovery request and an Alexa.PowerController request to turn on the light.

Define a discovery test

On the Lambda > Functions > my-smart-home-skill page, select the Test tab.
Under Test event, select Create new event.
For Event name, enter DiscoveryTest.
For Template, from the drop-down menu, select Alexa Smart Home Discovery Request.
In the code editor, replace the existing code with the following test code.

Copied to clipboard.

{
    "directive": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover",
            "payloadVersion": "3",
            "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "payload": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            }
        }
    }
}

To save the test code, click Save changes.

Define a Power on test

Under Test event, select Create new event.
For Event name, enter PowerOnTest.
For Template, from the drop-down menu, select Alexa Smart Home Control Turn On Request.
In the code editor, replace the existing code with the following test code.

Copied to clipboard.

{
  "directive": {
    "header": {
      "namespace": "Alexa.PowerController",
      "name": "TurnOn",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "1bd5d003-31b9-476f-ad03-71d471922820",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "sample-light-01",
      "cookie": {}
    },
    "payload": {}
  }
}

To save the test code, click Save changes.

To test your Lambda function on the AWS developer console

To open the test, under Test event, on the drop-down menu under Event name, select DiscoveryTest.
To run the test, under Test event, click Test.
If the test is successful, you see Execution result: succeeded.
To view the logs, in the Execution result box, expand Details.
To close the logs, click x.
Repeat Steps 1–4 for PowerOnTest.

Substep f: Copy the resource name

Every Lambda function has an Amazon Resource Name (ARN) that defines the endpoint to the function. Alexa accesses your skill code by the ARN.

The following image shows a sample ARN displayed in the Lambda console.

Formatted resource name for the smart home skill.

To copy the Lambda function ARN in the AWS developer console

At the top of the Lambda > Functions > my-smart-home-skill page, select Copy ARN.
In a convenient place, such as Notepad on Windows or TextEdit on Mac, paste the ARN.
You use this value in Step 3: Configure the Service Endpoint.

Last updated: Oct 14, 2022