API Reference

Appliance class

class askhome.Appliance(request=None)

Appliance subclasses are used to describe what actions devices support.

Methods of subclasses can be marked with decorators (like @Appliance.action) and are used to generate the Alexa DiscoverApplianceResponse. Alexa control and query requests are then routed to the corresponding decorated method.

Appliance subclass can also contain a Details inner class for instance defaults during discovery (see Smarthome.add_appliance for possible attributes).

request

Request – Currently processed request.

id

str – Identifier of the appliance from the appliance.applianceId of request payload.

additional_details

dict – Information that was sent for the DiscoverAppliancesRequest. Some instance specific details can be saved here.

__init__(request=None)

Appliance gets initialized just before its action methods are called. Put your logic for preparation before handling the request here.

classmethod action(func)

Decorator for marking the method as an action sent for the DiscoverAppliancesRequest.

The action name is generated from the camelCased method name (e.g. turn_on -> turnOn). The decorated method should take request as an argument, specific subclass of Request is passed for each action.

Possible action methods and their corresponding Request types passed are:
classmethod action_for(*args)

Decorator similar to the action decorator, except it doesn’t generate the action name from the method name. All action names that should lead to the decorated method are passed as arguments to the decorator.

actions

dict(str, function) – All actions the appliance supports and their corresponding (unbound) method references. Action names are formatted for the DiscoverAppliancesRequest.

request_handlers

dict(str, function) – All requests the appliance supports (methods marked as actions) and their corresponding (unbound) method references. For example action turn_on would be formatted as TurnOnRequest.

class Details

Inner class in Appliance subclasses provides default values so that they don’t have to be repeated in Smarthome.add_appliance.

Smarthome class

class askhome.Smarthome(**details)

Holds information about all appliances and handles routing requests to appliance actions.

appliances

dict(str, (Appliance, dict)) – All registered appliances with details dict.

details

dict – Defaults for details of appliances during DiscoverAppliancesRequest.

__init__(**details)
Parameters:details (dict) – Defaults for details of appliances during DiscoverAppliancesRequest. See add_appliance method for possible values.
add_appliance(appl_id, appl_class, name=None, description=None, additional_details=None, model=None, version=None, manufacturer=None, reachable=None)

Register Appliance so it can be discovered and routed to.

The keyword arguments can be also defined in Smarthome.__init__ and Details inner class in the appliance. Resulting value is resolved in order of priority: Smarthome.add_appliance kwargs -> Appliance.Details -> Smarthome.__init__ kwargs

Parameters:
  • appl_id (str) – Unique identifier of the appliance, needs to be consistent across multiple discovery requests for the same device. Can contain any letter or number and the following special characters: _ - = # ; : ? @ &. Cannot exceed 256 characters.
  • appl_class (Appliance) – Appliance subclass with marked actions.
  • name (str) – Friendly name used by the customer to identify the device. Cannot exceed 128 characters and should not contain special characters or punctuation.
  • description (str) – Human-readable description of the device. This value cannot exceed 128 characters. The description should contain a description of how the device is connected. For example, “WiFi Thermostat connected via Wink”.
  • additional_details (dict(str, str)) – Some instance specific details can be saved here. This field is sent back every time a request on that appliance is made. Cannot exceed 5000 bytes.
  • model (str) – Device model name. Cannot exceed 128 characters.
  • version (str) – Vendor-provided version of the device. Cannot exceed 128 characters.
  • manufacturer (str) – Name of device manufacturer. Cannot exceed 128 characters.
  • reachable (bool) – Indicate if device is currently reachable.
prepare_handler(func)

Decorator for a function that gets called before every request. Useful to modify the request processed, for instance add data to Request.custom_data

discover_handler(func)

Decorator for a function that handles the DiscoverAppliancesRequest instead of the Smarthome. This can be useful for situations where querying the list of all devices is too expensive to be done every request. Should be used in conjunction with the get_appliance_handler decorator.

get_appliance_handler(func)

Decorator for a function that handles getting the Appliance subclass instead of the Smarthome. Should be used in conjunction with the get_appliance_handler decorator.

healthcheck_handler(func)

Decorator for a function that handles HealthCheckRequest. Behaves the same as a regular action method.

lambda_handler(data, context=None)

Main entry point for handling requests. Pass the AWS Lambda events here.

Requests

askhome.requests.create_request(data, context=None)

Create a specific Request subclass according to the request type.

Each Request subclass has specific properties to access request data more easily and differing response arguments for direct response creation.

class askhome.requests.Request(data, context=None)

Base Request class for parsing Alexa request data.

data

dict – Raw event data from the lambda handler.

context

object – Context object from the lambda handler.

header

dict – Header of the Alexa request.

payload

dict – Payload of the Alexa request.

name

str – Request name from the name field in header.

access_token

str – OAuth token from the accessToken field in payload.

custom_data

Any – Attribute for saving custom data through Smarthome.prepare_handler

__init__(data, context=None)
appliance_id

str – Identifier of the appliance from the appliance.applianceId of request payload.

appliance_details

dict – Information that was sent for the DiscoverApplianceRequest in field appliance.additionalApplianceDetails

response_header(name=None)

Generate response header with copied values from the request and correct name.

raw_response(payload=None, header=None)

Compose response from raw payload and header dicts

response(*args, **kwargs)

Return response with empty payload. Arguments and implementation of this method differ in each Request subclass.

exception_response(exception)

Create response from exception instance.

class askhome.requests.DiscoverRequest(data, context=None)

Request class for Alexa DiscoverAppliancesRequest.

response(smarthome)

Generate DiscoverAppliancesResponse from appliances added to the passed Smarthome.

Details of each appliance are resolved in order of priority: Smarthome.add_appliance kwargs -> Appliance.Details -> Smarthome.__init__ kwargs

class askhome.requests.PercentageRequest(data, context=None)

Request class for Alexa Increment/Decrement/SetPercentageRequest.

percentage
delta_percentage
class askhome.requests.ChangeTemperatureRequest(data, context=None)

Request class for Alexa Increment/Decrement/SetTargetTemperatureRequest.

temperature
delta_temperature
response(temperature, mode=None, previous_temperature=None, previous_mode=None)
Parameters:
  • temperature (float) – Target temperature set by the device, in degrees Celsius.
  • mode (str) – Temperature mode of device. Can be ‘AUTO’, ‘COOL’ or ‘HEAT’.
  • previous_temperature (float) – Previous target temperature in degrees Celsius.
  • previous_mode (str) – Previous temperature mode.
class askhome.requests.GetTargetTemperatureRequest(data, context=None)

Request class for Alexa GetTargetTemperatureRequest.

response(temperature=None, cooling_temperature=None, heating_temperature=None, mode='AUTO', mode_name=None, timestamp=None)
Parameters:
  • temperature (float) – Target temperature set by the device, in degrees Celsius.
  • cooling_temperature (float) – Target temperature (setpoint) for cooling, in degrees Celsius, when a device has dual setpoints. Usually combined with heatingTargetTemperature.
  • heating_temperature (float) – Target temperature (setpoint) for heating, in degrees Celsius, when a device has dual setpoints. Usually combined with coolingTargetTemperature.
  • mode (str) – Temperature mode of device. Can be one of ‘AUTO’, ‘COOL’, ‘HEAT’, ‘ECO’, ‘OFF’, ‘CUSTOM’.
  • mode_name (str) – Friendly name of the mode when it differs from the canonical name. Required when mode is ‘CUSTOM’.
  • timestamp (datetime|str) – Time when the information was last retrieved.
class askhome.requests.TemperatureReadingRequest(data, context=None)

Request class for Alexa GetTemperatureReadingRequest.

response(temperature, timestamp=None)
Parameters:
  • temperature (float) – Current temperature reading, in degrees Celsius.
  • timestamp (datetime|str) – Time when the information was last retrieved.
class askhome.requests.LockStateRequest(data, context=None)

Request class for Alexa Get/SetLockStateRequest.

lock_state
response(lock_state, timestamp=None)
Parameters:
  • lock_state (str) – Can be ‘LOCKED’ or ‘UNLOCKED’ for GetLockStateRequest, can be only ‘LOCKED’ for SetLockStateRequest (for security reasons).
  • timestamp (datetime|str) – Time when the information was last retrieved.
class askhome.requests.HealthCheckRequest(data, context=None)

Request class for Alexa HealthCheckRequest.

response(healthy, description)

Exceptions

exception askhome.exceptions.AskhomeException(*args, **kwargs)

Base askhome exception from which all inherit.

These exceptions can be raised in Appliance actions or manually passed to Request.exception_response to create an error response.

namespace = 'Alexa.ConnectedHome.Control'
__init__(*args, **kwargs)
Parameters:
  • name (str) – Custom error name in header of generated response
  • payload (dict) – Custom payload of generated response
exception askhome.exceptions.ValueOutOfRangeError(min_val, max_val, *args, **kwargs)

Amazon docs: Indicates a customer request would set a target value to a value out of its supported range. For example, a customer asks, “Alexa, set the kitchen to 1000 degrees”.

__init__(min_val, max_val, *args, **kwargs)
exception askhome.exceptions.TargetOfflineError(*args, **kwargs)

Amazon docs: Indicates that the target device is not connected to the customer’s device cloud or is not on.

exception askhome.exceptions.NoSuchTargetError(*args, **kwargs)

Amazon docs: Indicates that the target device cannot be found, meaning it was never configured by the end-user.

exception askhome.exceptions.BridgeOfflineError(*args, **kwargs)

Amazon docs: Indicates the target device is connected to a home automation hub or bridge, which is powered off.

exception askhome.exceptions.DriverInternalError(*args, **kwargs)

Amazon docs: Indicates a generic runtime error within the skill adapter. When possible, a more specific error should be returned.

exception askhome.exceptions.DependentServiceUnavailableError(service_name, *args, **kwargs)

Amazon docs: Indicates that a skill adapter dependency is unavailable and the skill adapter cannot complete the request.

__init__(service_name, *args, **kwargs)
exception askhome.exceptions.TargetConnectivityUnstableError(*args, **kwargs)

Amazon docs: Indicates the cloud-connectivity for the target device is not stable and reliable.

exception askhome.exceptions.TargetBridgeConnectivityUnstableError(*args, **kwargs)

Amazon docs: Indicates that cloud-connectivity for a home automation hub or bridge that connects the target device is unstable and unreliable.

exception askhome.exceptions.TargetFirmwareOutdatedError(min_version, cur_version, *args, **kwargs)

Amazon docs: Indicates that the target device has outdated firmware.

__init__(min_version, cur_version, *args, **kwargs)
exception askhome.exceptions.TargetBridgeFirmwareOutdatedError(min_version, cur_version, *args, **kwargs)

Amazon docs: Indicates that the home automation hub or bridge that connects the target device has outdated firmware.

__init__(min_version, cur_version, *args, **kwargs)
exception askhome.exceptions.TargetHardwareMalfunctionError(*args, **kwargs)

Amazon docs: Indicates that the target device experienced a hardware malfunction.

exception askhome.exceptions.TargetBridgeHardwareMalfunctionError(*args, **kwargs)

Amazon docs: Indicates that the home automation hub or bridge connecting the target device experienced a hardware malfunction

exception askhome.exceptions.UnableToGetValueError(error_code, error_description=None, *args, **kwargs)

Amazon docs: Indicates that an error occurred while trying to get the specified value on the target device. When returning this error, an appropriate error_code value enables Alexa to respond appropriately for different kinds of failures. You only need to generate an error code appropriate for the target device.

namespace = 'Alexa.ConnectedHome.Query'
__init__(error_code, error_description=None, *args, **kwargs)
Parameters:
  • error_code (str) –

    Possible error codes are:

    • DEVICE_AJAR: Cannot get the specified state because the door is open.
    • DEVICE_BUSY: The device is busy
    • DEVICE_JAMMED: The device is jammed.
    • DEVICE_OVERHEATED: The device has overheated.
    • HARDWARE_FAILURE: Request failed because of an undetermined hardware failure.
    • LOW_BATTERY: The device’s battery is low
    • NOT_CALIBRATED: The device is not calibrated.
  • error_description (str) – non-required custom description
exception askhome.exceptions.UnableToSetValueError(error_code, error_description=None, *args, **kwargs)

Amazon docs: Indicates that an error occurred while trying to set the specified value on the target device. When returning this error, an appropriate error_code value enables Alexa to respond appropriately for different kinds of failures. You only need to generate error codes appropriate for the target device.

__init__(error_code, error_description=None, *args, **kwargs)
Parameters:
  • error_code (str) –

    Possible error codes are:

    • DEVICE_AJAR: Cannot get the specified state because the door is open.
    • DEVICE_BUSY: The device is busy
    • DEVICE_JAMMED: The device is jammed.
    • DEVICE_OVERHEATED: The device has overheated.
    • HARDWARE_FAILURE: Request failed because of an undetermined hardware failure.
    • LOW_BATTERY: The device’s battery is low
    • NOT_CALIBRATED: The device is not calibrated.
  • error_description (str) – non-required custom description
exception askhome.exceptions.UnwillingToSetValueError(error_code='ThermostatIsOff', error_description=None, *args, **kwargs)

Amazon docs: Indicates that the target device partner is unwilling to set the requested value on the specified device. Use this error for temperature settings.

__init__(error_code='ThermostatIsOff', error_description=None, *args, **kwargs)
exception askhome.exceptions.RateLimitExceededError(rate_limit, time_unit='HOUR', *args, **kwargs)

Amazon docs: Indicates that the maximum number of requests that a device accepts has been exceeded. This message provides information about the maximum number of requests for a device and the time unit for those requests. For example, if a device accepts four requests per hour, the message should specify 4 and HOUR as rate_limit and time_unit, respectively.

__init__(rate_limit, time_unit='HOUR', *args, **kwargs)
exception askhome.exceptions.NotSupportedInCurrentModeError(current_mode, *args, **kwargs)

Amazon docs: Indicates that the target device is in a mode in which it cannot be controlled with the Smart Home Skill API, and provides information about the current mode of the device.

__init__(current_mode, *args, **kwargs)
exception askhome.exceptions.ExpiredAccessTokenError(*args, **kwargs)

Amazon docs: Indicates that the access token used for authentication has expired and is no longer valid.

exception askhome.exceptions.InvalidAccessTokenError(*args, **kwargs)

Amazon docs: Indicates that the access token used for authentication is not valid for a reason other than it has expired.

exception askhome.exceptions.UnsupportedTargetError(*args, **kwargs)

Amazon docs: Indicates that the target device is not supported by the skill adapter.

exception askhome.exceptions.UnsupportedOperationError(*args, **kwargs)

Amazon docs: Indicates that the requested operation is not supported on the target device.

exception askhome.exceptions.UnsupportedTargetSettingError(*args, **kwargs)

Amazon docs: Indicates that the requested setting is not valid for the specified device and operation.

exception askhome.exceptions.UnexpectedInformationReceivedError(faulting_parameter, *args, **kwargs)

Amazon docs: The request message or payload could not be handled by the skill adapter because it was malformed.

__init__(faulting_parameter, *args, **kwargs)

Utils

askhome.utils.get_action_string(func_name)

Transform function name to Alexa action

askhome.utils.get_request_string(func_name)

Transform function name to Alexa request name

askhome.utils.rstrip_word(text, suffix)

Strip suffix from end of text