Step 2: Implement Add-on Code

In the previous step, you created a new smart home add-on in the Alexa developer console. Now you implement your smart home add-on code as an Amazon Web Services (AWS) Lambda function. This function consists of your add-on code, configuration information, and an Identity and Access Management (IAM) role that allows Lambda to run the add-on 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 add-on. 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.

Substeps to implement add-on code in the AWS console

Complete the following substeps to implement the code that controls a virtual light bulb.

Create an IAM role
Create a Lambda function
Add add-on code
Test the Lambda function
Copy the resource name

Substep 2.1: Create an IAM role

In this substep, you attach a smart home policy to a new IAM role. In Step b, you assign the role to your Lambda function. To create an IAM role for your AWS Lambda function in the AWS developer console

Sign in to the AWS management console.
Open the IAM Dashboard.
On the IAM Identity Center navigation pane, under Access management, choose Roles.
On the IAM > Roles page, choose Create role.
On the IAM > Roles > Create role page, enter the following information:
1. For Trusted entity type, select AWS service.
2. Under Use cases, select Lambda, and then choose Next.
Under Add permissions, use the filter to find the policy called AWSLambdaBasicExecutionRole.
Select the check box next to the AWSLambdaBasicExecutionRole policy and AWS managed type, and then choose Next.
Under Name, review, and create page, for Role name, enter lambda_smart_home_add-on_role, and then, at the bottom of the page, choose Create role.

Now, you can see the lambda_smart_home_add-on_role in the list of available roles.

Substep 2.2: 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 add-on code. To create an AWS Lambda function in the AWS developer console

Navigate to the Lambda console.
If you’ve created Lambda functions, the console displays a list of your functions.
On the Functions page, choose Create function.
Select Author from scratch.
In the Basic information pane, enter the following information:
1. For Function name, enter my-smart-home-add-on.
2. For Runtime, choose a version of Python or Node.js.
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 choose Create function.
On the Lambda > Functions > my-smart-home-add-on page, under Function overview, choose + Add trigger.
On the Add trigger page, enter the following information to trigger your add-on:
1. For Trigger configuration, select Alexa.
2. For Choose an Alexa product, select Alexa Smart Home.
3. For SkillID, paste the skill ID that you saved in Step 1: Create a Smart Home Add-on.
4. To add the trigger to invoke your add-on, choose Add.

Substep 2.3: Add add-on code

Now, you add the example add-on code to your Lambda function. The example code contains a discovery response to model the light bulb and an Alexa response to control the light bulb. On receipt of a directive from Alexa, the Lambda function executes your add-on code. The discovery response identifies the light bulb endpoint and includes as much identifying information about the endpoint as possible, such as manufacturer, model, and serial number. In addition, the discovery response identifies the capabilities of the light bulb. In this example, the response includes the Alexa.PowerController interface to indicate that the customer can turn the light bulb on and off. For more details about discovery, see About Alexa Discovery. After the customer asks Alexa to turn the light bulb on, Alexa sends a TurnOn directive to the add-on. In response, the add-on calls the appropriate interface in the device cloud to turn on the bulb, and then responds to Alexa with the current state of the light bulb endpoint. A fully functional smart home add-on might include a combination of capability interfaces that best represent the features of the endpoint device. And, the add-on usually supports state and change reporting to keep Alexa up-to-date on the status of the device. For available Smart Home interfaces that you can use to model your device type, see List of Alexa Interfaces and Supported Languages. Add the code to your Lambda function

On the Lambda > Functions > my-smart-home-add-on page, to view the code editor, select the Code tab.
Choose the language for your add-on code. For Node.js, your add-on code resides in the file, index.js or index.mjs. For the tutorial, rename index.mjs to index.js.
For Python, your add-on code resides in the file, lambda_function.py.
Open index.js (Node.js) or lambda_function.py (Python).
In the Code source pane, paste the Node.js or Python code into the code editor, replacing any existing code. The example smart home add-on code supports the AcceptGrant, Discovery, TurnOn, and TurnOff directives for the virtual light bulb.

Example smart home add-on code

Node.js
Python

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

# -*- 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 build and load the function, under DEPLOY, choose Deploy.
Make sure to deploy the function after each update that you make.

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

Substep 2.4: Test the Lambda function

After you deploy your add-on 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 to report the endpoint capabilities and an Alexa.PowerController request to turn on the light. Define a discovery test

On the Lambda > Functions > my-smart-home-add-on page, choose the Test tab.
Under Test event action, select Create new event.
For Event name, enter DiscoveryTest.
For Template, expand the dropdown list, and then select Alexa Smart Home Discovery Request.
In the Event JSON code editor, replace the existing code with the following test code.

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

To save the test code, choose Save.

Define a Power on test

Under Test event, select Create new event.
For Event name, enter PowerOnTest.
For Template, expand the dropdown list, and then select Alexa Smart Home Control Turn On Request.
In the code editor, replace the existing code with the following test code.

{
  "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-add-on"
      },
      "endpointId": "sample-light-01",
      "cookie": {}
    },
    "payload": {}
  }
}

To save the test code, choose Save changes.

To test your Lambda function on the AWS developer console

To open the test, under Test event, expand the dropdown list under Event name, and then select DiscoveryTest.
To run the test, under Test event, choose 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, choose x.
Repeat Steps 1–4 for the PowerOnTest event.

Substep 2.5: Copy the resource name

Every Lambda function has an Amazon Resource Name (ARN) that defines the endpoint to the function. Alexa accesses your add-on code by the ARN. The following image shows a sample ARN displayed in the Lambda console. Formatted resource name for the smart home add-on.

Formatted resource name for the smart home add-on.

To copy the Lambda function ARN in the AWS developer console

At the top of the Lambda > Functions > my-smart-home-add-on page, choose 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.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Substeps to implement add-on code in the AWS console

Substep 2.1: Create an IAM role

Substep 2.2: Create a Lambda function

Substep 2.3: Add add-on code

Substep 2.4: Test the Lambda function

Substep 2.5: Copy the resource name

​Substeps to implement add-on code in the AWS console

​Substep 2.1: Create an IAM role

​Substep 2.2: Create a Lambda function

​Substep 2.3: Add add-on code

​Substep 2.4: Test the Lambda function

​Substep 2.5: Copy the resource name

Substeps to implement add-on code in the AWS console

Substep 2.1: Create an IAM role

Substep 2.2: Create a Lambda function

Substep 2.3: Add add-on code

Substep 2.4: Test the Lambda function

Substep 2.5: Copy the resource name