AVS Device SDK Smart Home Endpoints


Device makers wishing to add Smart Home functions to their AVS device can now do so without requiring the implementation of a separate Alexa skill or custom cloud interface. For example, you can control and customize Smart Home devices with unique device names. By enabling Smart Home functionality for AVS devices, device developers can add custom voice control to hardware of a device and support connected endpoints. The initial release makes the following Smart Home capabilities available to AVS devices and their connected endpoints.

You can read more about configuring endpoints with AVS on the following pages:

Tutorial

To start developing with endpoints, see the following tutorial Create an Alexa Built-in Disco Ball.

Capability Agents added to the SDK

  • PowerController: Turn the endpoint on or off. Only a single instance of the power controller can exist on an endpoint.
  • ToggleController: Toggle endpoint properties on and off. Use multiple instances of the toggle controller to control different toggles on the endpoint.
  • RangeController: Changes the value of a property within a range. Use multiple instances of the range controller to control different values on the endpoint.
  • ModeController: Activates a particular endpoint mode. Use multiple instances of the mode controller to control different modes on the endpoint.

How to enable endpoints

You define endpoints with a friendlyName. You use this endpoint to refer to it in utterances. For instance, you can say “Alexa, turn off the microwave”. In this example, "microwave" is the friendlyName on the device that controls the microwave.

To learn how to control an endpoint, see the disco ball endpoint in the sample app. For demonstration purposes, the endpoint has a hard coded friendlyName value of discoball. You can change the name to anything you want.

By default, the sample app disables all endpoints. To enable endpoints, recompile the SDK with the following CMake option, -DENABLE_ALL_ENDPOINT_CONTROLLERS=ON. Here is a full CMake command for reference.

cmake $HOME/my_project/source/avs-device-sdk \
-DGSTREAMER_MEDIA_PLAYER=ON \
-DPORTAUDIO=ON \
-DPORTAUDIO_LIB_PATH=$HOME/my_project/third-party/portaudio/lib/.libs/libportaudio.a \
-DPORTAUDIO_INCLUDE_DIR=$HOME/my_project/third-party/portaudio/include \
-DCMAKE_BUILD_TYPE=DEBUG \
-DENABLE_ALL_ENDPOINT_CONTROLLERS=ON

You can also control individual controllers, for example:

Use all controllers except the PowerController

-DENABLE_ALL_ENDPOINT_CONTROLLERS=ON \
-DENDPOINT_CONTROLLERS_POWER_CONTROLLER=OFF

Only use PowerController and ModeController

-DENDPOINT_CONTROLLERS_POWER_CONTROLLER=ON \
-DENDPOINT_CONTROLLERS_RANGE_CONTROLLER=ON

For more details about configuring CMake for endpoints, see the CMake parameters page.

Control the endpoint by voice

  • "Alexa, turn disco ball on."
  • "Alexa, increase discoball's speed."
  • "Alexa, change discoball's mode to green."

You can also query the state of the endpoint by using the following utterances:

  • "Alexa, what is disco ball's speed?"
  • "Alexa, what is disco ball's mode?"

Control the endpoint through the companion app

In the companion App, the discoball endpoint appears as a Smart Home device that you can control by using the GUI.

Configuring your own endpoints

You can combine the controller capabilities to build complex endpoints. For example, you could combine the PowerController, ModeController, ToggleController, and RangeController to design a smart air conditioner.

The power controller turns the air conditioner on or off. One range controller controls the fan speed and another range controller controls the temperature. A mode controller changes between preset air conditioner modes, such as "dry," "cool," or "fan." A toggle controller toggles the energy-saver mode.

For each controller capability, the SDK also provides a controller interface. You can create implementations of the controller interfaces to perform various actions – for example, extend the power controller interface so it sends a signal to turn on an endpoint. You can see an example of a controller interface implementation in the sample app. Here, the discoball endpoint uses a controller interface to print a message on the screen when receiving controller directives.

Dynamic endpoints

Dynamic endpoints allow you to add, modify, or delete endpoints at any point after the DefaultClient connects to AVS.

The updated interfaces that support dynamic endpoints include:

Dynamic endpoint example

You can experiment with a sample dynamic endpoint in the sample app by building the SDK with the following CMake flags, ENABLE_ALL_ENDPOINT_CONTROLLERS and ENDPOINT_CONTROLLERS_POWER_CONTROLLER.

Here is an example CMake command with the sample dynamic endpoint available in the sample app. After the sample app builds, select y in the sample app main menu to add a dynamic endpoint, modify its friendly name, and delete it.

cmake $HOME/my_project/source/avs-device-sdk \
-DGSTREAMER_MEDIA_PLAYER=ON \
-DPORTAUDIO=ON \
-DPORTAUDIO_LIB_PATH=$HOME/my_project/third-party/portaudio/lib/.libs/libportaudio.a \
-DPORTAUDIO_INCLUDE_DIR=$HOME/my_project/third-party/portaudio/include \
-DCMAKE_BUILD_TYPE=DEBUG \
-DENABLE_ALL_ENDPOINT_CONTROLLERS=ON
-DENDPOINT_CONTROLLERS_POWER_CONTROLLER=ON

Was this page helpful?

Last updated: Sep 28, 2021