Smart Home for AVS

Device makers have used AVS to launch hundreds of products with Alexa Built-in that customers can talk to and play music, ask questions, control compatible devices, and more. However, the only way for an AVS device maker to enable voice control of their product's unique hardware was by building a separate Smart Home or Custom Alexa Skill for their device and maintaining a separate cloud service. Now, device makers can just re-use their AVS client to handle those capabilities directly, saving time and money up-front and over the lifetime of the product. Developers can integrate the new and changed APIs directly or use the AVS Device SDK 1.17 or higher.

By enabling smart home functionality for AVS devices, device developers can add custom voice control of a device's hardware functionality and support connected endpoints. The initial release makes the following smart home capabilities available to AVS devices and their connected endpoints:

  • Alexa.PowerController: Control and report on the power state of a device.
  • Alexa.ToggleController: Model properties of an endpoint that can be set to on or off, such as the oscillation feature of a fan.
  • Alexa.RangeController: Model properties of an endpoint that can be set to one of a range of continuous values, such as the speed settings on a blender or a fan.
  • Alexa.ModeController: Model properties of an endpoint that can be set to one of a discrete set of values, such as the wash cycle mode of a washing machine.

Developers integrating with AVS can assert support for these additional capabilities and use their pre-built voice and interaction models without the need to build a Smart Home Skill or a dedicated cloud service.

The following resources can help you to get started with this new functionality:

Note that taking advantage of this new functionality requires transitioning from the Capabilities API to Alexa.Discovery. This also depends on

Connected endpoints

Throughout the AVS documentation, the entity that maintains the HTTP/2 connection to Alexa is referred to as the "device," "client," or "product." In basic integrations, the device is the only entity that is the subject of user interactions and exchanges of messages with Alexa.

AVS also enables connecting additional "endpoints" to Alexa. (Note that this isn't the same use of the term as "URI endpoint" for API connections.) These connected endpoints don't maintain their own direct connections to Alexa, relying instead on the HTTP/2 device to proxy events and directives on their behalf.

From Alexa's perspective, the device and all other connected endpoints are all "endpoints". This is reflected in how a device reports both itself and connected endpoints in the same endpoints list in Alexa.Discovery. Where certain capability interfaces, mechanics, or fields apply only to the device maintaining the HTTP/2 connection, the documentation will make that clear. Otherwise, "endpoint" can refer to either the device or any connected endpoints.

Topology

Connected endpoints are analogous to those described by the Smart Home Skills Kit. When an endpoint connects through a skill, it requires that the developer maintains a cloud service that is called by an AWS Lambda function. That cloud service exchanges events and directives with Alexa on behalf of any endpoints. Therefore, the developer is responsible for the connection between the cloud service and the endpoint.

When the endpoint connects to an AVS device, the device takes the place of the cloud service, informing Alexa about the endpoint through Alexa.Discovery. When a capability interface is suitable for a connected endpoint, it will include an endpoint object in events and directives, so that when the device exchanges messages with Alexa on behalf of the endpoint, both the device and Alexa know which connected endpoint the message is about. More information is available in the Envelope Version documentation, as well as the documentation for individual capability interfaces.

Think of the device as a proxy for the endpoint, offering an abstraction layer to connected endpoints for AVS.

Note that, unlike the cloud service in a traditional Smart Home Skills integration, the device is also itself an endpoint.

Endpoint types and connectivity

Endpoints may be physical or virtual. A physical endpoint might be a light bulb, thermostat, camera, or smart lock. A virtual endpoint might be a piece of software running on the device, like an installed app.

Endpoints might be separate physical entities or integrated components. For instance, a light bulb could be separate, perhaps in a ceiling lighting fixture. Alternatively, it could be integrated into the HTTP/2 device and modeled as a connected endpoint for separate control and targeting.

Alexa-defined JSON events and directives may be passed raw between the device and endpoint or translated into a different protocol, format, encoding, or signal. The only requirement is that the semantics are preserved.

If a connected endpoint is aware of Alexa, the endpoint could run software to understand and use Alexa events and directives. In such cases, the HTTP/2 device can pass messages between the endpoint and Alexa without translation, over whatever connection exists between the device and the endpoint.

By contrast, if a connected endpoint isn't Alexa-specific, the HTTP/2 device may need to translate the Alexa messages into the appropriate signal. For example, the device may receive a TurnOn directive for a particular light bulb endpoint. The directive might then be translated into the appropriate Zigbee signal that turns on the light bulb. This applies to virtual endpoints as well. For instance, if the device receives a directive to control an Android app that is also installed on the device, it might need to translate that directive into the appropriate Android API, then translate any response into the corresponding Alexa event.

Last updated: Mar 16, 2023