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 (seeSmarthome.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: - turn_on(
askhome.requests.Request
) - turn_off(
askhome.requests.Request
) - set_percentage(
askhome.requests.PercentageRequest
) - increment_percentage(
askhome.requests.PercentageRequest
) - decrement_percentage(
askhome.requests.PercentageRequest
) - set_target_temperature(
askhome.requests.ChangeTemperatureRequest
) - increment_target_temperature(
askhome.requests.ChangeTemperatureRequest
) - decrement_target_temperature(
askhome.requests.ChangeTemperatureRequest
) - get_target_temperature(
askhome.requests.GetTargetTemperatureRequest
) - get_temperature_reading(
askhome.requests.TemperatureReadingRequest
) - set_lock_state(
askhome.requests.LockStateRequest
) - get_lock_state(
askhome.requests.LockStateRequest
)
- turn_on(
- Possible action methods and their corresponding
-
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 inSmarthome.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__
andDetails
inner class in the appliance. Resulting value is resolved in order of priority:Smarthome.add_appliance
kwargs ->Appliance.Details
->Smarthome.__init__
kwargsParameters: - 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 theget_appliance_handler
decorator.
-
get_appliance_handler
(func)¶ Decorator for a function that handles getting the
Appliance
subclass instead of theSmarthome
. Should be used in conjunction with theget_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 differingresponse
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.
-
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 toRequest.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.
Amazon docs: Indicates that a skill adapter dependency is unavailable and the skill adapter cannot complete the request.
-
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
- error_code (str) –
-
-
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
- error_code (str) –
-
-
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.