Smart Home Skills Configuration

By entering the Alexa Developer Console you can add a new Skill by clicking on the Create Skill button.

Enter the name of your skill (e.g. Visentin Ovens) and then select the Smart Home and Custom boxes.

Once a skill has been created, you must configure the various pages.

SMART HOME

Select Payload version to V3

In the Default endpoint enter the ARN of your Lambda function used by Alexa to perform API requests to the Servitly backend. Refer to the Lamda Function Configuration paragraph about ARN.

MODEL

Ensure that only Smart Home is selected.

ACCOUNT LINKING

This is the page where you must configure the account linking between Alexa and Servitly.

• Web Authorization URI: https://am-alx.servitly.com/oauth/authorize

• Access Token URI: https://am-alx.servitly.com/oauth/token

• Client ID: The API key you have selected within the Alexa plugin.

• Client secret: The secret key of the API key you have selected within the Alexa plugin.

• Authentication Scheme: Credentials in request body

• Scope: user_info

Lambda Function

Within your AWS account, you have to create a new Lamda based on Node.js

Click the Add Trigger button, select Alexa and insert the Skill ID in order to authorize Alexa to call the Lambda function.

Here is an example of AWS Lambda you can use as a starting point. Note that, this example is based on NodeJS, and uses CommonJS modules, so you need to configure the index.js file instead of the *.mjs, which is based on ES modules.

// Copyright 2024 Servitly. All Rights Reserved.
//
// This script is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied.
const https = require('https');
exports.handler = async function (request, context) {
    
    function log(severity, message1, message2) {
        console.log("[" + severity + "] " + message1 + " " + message2);
    }
    
    async function handleRequest(request, context) {
        const options = {
            hostname: 'am-alx.servitly.com',
            path: '/api/smart-home',
            method: 'POST',
            port: 443,
            headers: {
                'Content-Type': 'application/json'
            },
        };
        return new Promise((resolve, reject) => {
            const req = https.request(options, res => {
                let rawData = '';
                res.on('data', chunk => {
                    rawData += chunk;
                });
                res.on('end', () => {
                    try {
                        resolve(JSON.parse(rawData));
                    } catch (err) {
                        reject(new Error(err));
                    }
                });
            });
            req.on('error', err => {
                reject(new Error(err));
            });
            req.write(JSON.stringify(body));
            req.end();
        });
    }
    
    log("DEBUG", "REQUEST", JSON.stringify(request));
    await handleRequest(request, context).then(response => {
        console.log("DEBUG", "RESPONSE", JSON.stringify(response));
        context.succeed(response);
    }).catch(error => {
        console.log("ERROR", "ERROR", JSON.stringify(error));
        context.fail(error);
    });
};

You can check the Monitoring tab to verify requests made to the function. Pay attention that the Monitor tab may require several minutes before display up to date logs.

Custom Skill Configuration

In the case Smart Home skills are not enough, you can create your own custom skill. Custom skills require to configure the account linking, which is the same as for Smart Home.

You can refer to this guide in order to define custom skills.

Within the Custom Skill endpoint configuration, instead of a Lambda function, you can use the following direct endpoint URL.

https://am-alx.servitly.com/api/custom-skill

Remember to select "My development endpoint is a sub-domain of a domain that has a wildcard certificate from a certificate authority". This beacuse the Servitly certificate is a wild card certificate.

Home Assistant Configuration

For each thing definition, you can now configure how the product can interact with the Alexa assistant.

To configure the Home Assistant you need to:

1. Enter the Remote Control / Home Assistants page.

2. Select the Thing Definition to edit.

3. Press the Add Home Assistant button and select Alexa.

4. Configure the Devices to display in the Alexa App.

If the product is complex, you can configure multiple devices that will appear in the Alexa App as separate devices. For example, considering a heating system, you can have several zones to be controlled separately. Each device will have its own traits, and will go to interact with and control a particular aspect of the connected product.

In case the number of devices depends on the type of installation, you can choose a metric of the thing that provides the number of devices to be generated. In this case, each Device will also need to define the Index property needed to determine which Devices to enable depending on Index Device Count metric vlaue (metric.value <= device.index).

Within each Device you can configure:

• Name: the name to be displayed in the Alexa App.
  You can use placeholders to include thing properties (e.g. ${thing.name})

• Device Type: the type of the device to generate (e.g. Thermostat).
  For a complete list of available devices and their description, refer to the Alexa documentation.

• Device Name Metric: the metric whose value can be used as device name.

• Index: in case of dynamic devices, the index used to enable the device according to the Indexed Device Count Metric.

• Capabilities: the list of Alexa interfaces associated to this device.
  Refer to the Capabilities section below.

CustomIntent

PowerController

TemperatureSensor

ThermostatController

Alexa App configuration

This is the final step to control your connected product through Alexa, this step generally is up to the end-users.

You can follow this guide to configure the Amazon Alexa App.

Thing Discovery

By default, when the user has connected the account to the Alexa app, discovery will return all things visible to the user.

Alternatively, you can let the user decide which things should be visible in the Alexa app. To do this, you need to add a boolean property to the things, named "assistantEnabled."
In this way, for each thing, the user is free to enable or disable each from the home assistant discovery and control.

Submit your skill for certification

To promote your Skill to production and make it public, you must submit the Skill for certification, and this requires to:

• implement beta testing;

• complete the quesionaires about securtity and privacy;

• provide all graphic resources and texts;

• verify your brand, you must ensure that you are authorized to use the name you gave the Skill.

For a complete list of steps to perform you can ref to the Steps to Build a Custom Skill documetation page.

Note that you can wait up to 30 days to get feedback from the certification team, and you will probably have to resubmit your skill to correct minor problems. Therefore, be careful to plan the release of Skill well in advance. In case you are certifying a custom skill, more time may be required by the certification team.