Latest version: 1.0.0
This library provides a convenient way to implement the Alexa Smart Home Skill API within an agent. It takes care of the JSON verification, data parsing and response formatting.
Supported requests are:
You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.
To include this library in your project, add
#require "AlexaSmartHomeSkill.agent.nut:1.0.0"
at the top of your agent code
The constructor takes no parameters.
#require "AlexaSmartHomeSkill.agent.nut:1.0.0"
mySkill <- AlexaSmartHomeSkill();
This method makes the device accessible through the Alexa Smart Home Skill API.
applianceId specifies the device identifier. It must be unique across all devices.
applianceInfo is a table containing a number of required properties. It must contain the following keys:
| Key | Description |
|---|---|
| manufacturerName | The name of the device manufacturer |
| modelName | Device model name |
| version | The vendor-provided version of the device |
| friendlyName | The name used by the customer to identify the device |
| friendlyDescription | A human-readable description of the device |
| actions | An array of actions that the device supports. The library uses the array to verify that incoming requests can be fulfilled and are supported |
| additionalApplianceDetails | String name/value pairs that provide additional information |
Supported actions are:
The actionCallback takes the following parameters:
| Parameter | Description |
|---|---|
| session | An AlexaSmartHomeSkill.Session instance |
| applianceId | The ID of the appliance |
| action | The Smart Home API action |
| [parameter] | An optional request-specific parameter |
The actionCallback function is executed when a Smart Home API request is received. The application is supposed to respond to this request by calling a confirm, response or error method on the AlexaSmartHomeSkill.Session object passed into the callback. This response can be made asynchronously.
The library checks that appropriate confirm/response function is called in response to the incoming request: the error is returned to the application if an inappropriate function is called. Error reporting functions are also allowed to be used in response to any command.
Exceptions thrown within the actionCallback function are handled by the library and so don’t result in an error being sent back to the Alexa service.
registerAppliance() returns null if the verification succeeds, otherwise it returns an error description.
local smartToasterInfo = {
"actions": [
"turnOn",
"turnOff"
],
"additionalApplianceDetails": {
"extraDetail1": "pin1",
},
"friendlyDescription": "My super smart toaster",
"friendlyName": "SmartToaster",
"manufacturerName": "Mars Industrial",
"modelName": "Smart Toaster 1.0",
"version": "1.0"
};
// Callback executed upon Alexa request
local actionCallback = function(session, applianceId, action, params) {
server.log("Got action " + action + " for " + applianceId);
// Handle Alexa request here
}.bindenv(this);
local alexa = AlexaSmartHomeSkill();
alexa.registerAppliance("SmartToaster", smartToasterInfo, actionCallback);
The removeAppliance() method removes the device from the list of accessible appliances. All further requests to the device with the given applianceId will be rejected and an UnsupportedTargetError issued.
The method does not return a value. Attempts to remove an appliance that has already been removed are ignored.
This class is available only through the callback function registered with registerAppliance(). You should not instantiate it directly. Its main purpose is to encapsulate session data and to provide a convenient way to send responses.
This method returns the request’s additionalApplianceDetails data.
This method creates and sends a confirmation for a TurnOn request.
The method returns a message string if an error was detected, otherwise null. Possible error conditions include: the ongoing session is not related to the TurnOn command, and transport-related errors.
This method creates and sends a confirmation for a TurnOff request.
The method returns a message string if an error was detected, otherwise null. Possible error conditions include: the ongoing session is not related to the TurnOff command, and transport-related errors.
This method creates and sends a confirmation for a SetLockState request.
The method accepts the current lock state. It returns a message string if an error was detected, otherwise null. Possible error conditions include: the ongoing session is not related to the setLockState command, the state parameter is neither LOCKED nor UNLOCKED, and transport-related errors.
This method creates and sends a response to a GetLockState query.
The method accepts the current lock state. It returns a message string if an error was detected, otherwise null. Possible error conditions include: the ongoing session is not related to the getLockState command, the state parameter is neither LOCKED nor UNLOCKED, and transport-related errors.
This method creates and sends a confirmation for a setPercentage request.
The method returns a message string if an error was detected, otherwise null. Possible error conditions include: the ongoing session is not related to the setPercentage command, and transport-related errors.
The sendIncPercentageConfirm() method creates and sends a confirmation for an incrementPercentage request.
The method returns a message string if an error was detected, otherwise null. Possible error conditions include: the ongoing session is not related to the incrementPercentage command, and transport-related errors.
This method creates and sends a confirmation for a decrementPercentage request.
The method returns a message string if an error was detected, otherwise null. Possible error conditions include: the ongoing session is not related to the decrementPercentage command, and transport-related errors.
This method creates and sends a confirmation for an incrementTargetTemperature request.
The method accepts the current temperature and the temperature mode set by the device, and the temperature and temperature mode before the changes were made. It returns a message string if an error was detected, otherwise null. Possible error conditions include: the ongoing session is not related to the incrementTargetTemperature command, the mode and/or prevMode parameters is not AUTO, COOL or HEAT, and transport-related errors.
This method creates and sends a confirmation for a decrementTargetTemperature request.
The method accepts the current temperature and the temperature mode set by the device, and the temperature and temperature mode before the changes were made. It returns a message string if an error was detected, otherwise null. Possible error conditions include: the ongoing session is not related to the decrementTargetTemperature command, the mode and/or prevMode parameters is not AUTO, COOL or HEAT, and transport-related errors.
This method creates and sends a confirmation for a setTargetTemperature request.
The method accepts current temperature and temperature mode set by the device, temperature and temperature mode before changes were made.
The method accepts the current temperature and the temperature mode set by the device, and the temperature and temperature mode before the changes were made. It returns a message string if an error was detected, otherwise null. Possible error conditions include: the ongoing session is not related to the setTargetTemperature command, the mode and/or prevMode parameters is not AUTO, COOL or HEAT, and transport-related errors.
This method creates and sends a response to a getTargetTemperature query.
The method accepts a temperature mode, and a table with optional fields:
| Key | Description |
|---|---|
| targetTemperature | Indicates the target temperature set by the device in single-setpoint mode in degrees Celsius |
| coolingTargetTemperature | Indicates the target temperature (setpoint) for cooling, in degrees Celsius, when a device has dual setpoints |
| heatingTargetTemperature | Indicates the target temperature (setpoint) for heating, in degrees Celsius, when a device has dual setpoints |
| friendlyName | Indicates a device specific name for a temperature mode |
The method accepts the current temperature and the temperature mode set by the device, and the temperature and temperature mode before the changes were made. It returns a message string if an error was detected, otherwise null. Possible error conditions include: the ongoing session is not related to the getTargetTemperature command, the temperatureMode parameter is not AUTO, COOL, HEAT, OFF, ECO or CUSTOM, and transport-related errors.
This method creates and sends a response to a getTemperatureReading query.
The method accepts a temperature reading from the device. It returns a message string if an error was detected, otherwise null. Possible error conditions include: the ongoing session is not related to the getTemperatureReading command, and transport-related errors.
This method is used to notify that the target value is out of the supported range.
It accepts lowest and highest allowed values, and returns an error message string if a network problems was detected.
This method is used to notify that a partner device has rejected a requested value.
It accepts an error code in string format and a custom description, and returns an error message string if a network problems was detected.
This method is used to notify that a setting is not valid for the device or the operation.
The method returns an error message string if a network problems was detected.
This method is used to notify that a general runtime error has taken place.
The method returns an error message string if a network problems was detected.
This method is used to notify that the target device cannot be found.
The method returns an error message string if a network problems was detected.
This method is used to notify that a requested operation is not supported on the target device.
The method returns an error message string if a network problems was detected.
This method is used to notify that a message was malformed.
It accepts malformed property name, and returns an error message string if a network problems was detected.
The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.
| Version | Source Code | Notes |
|---|---|---|
| 1.0.0 | GitHub | Initial release |
AlexaSmartHomeSkill library is licensed under the MIT License.