Endpoints

The Alexa Voice Service (AVS) Device SDK 1.17 adds support for 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 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.

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

Capability Interfaces 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 a preset setting on the endpoint. Use Multiple instances of the toggle controller to control different toggle settings on the endpoint.
  • RangeController: Change the range of a preset setting. Use Multiple instances of the range controller to control different range settings on the endpoint.
  • ModeController: Change preset modes on an endpoint. Use Multiple instances of the mode controller to control different mode settings on the endpoint.

How to enable endpoints

You define endpoints with a friendlyName. You use this name 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 discoball endpoint in the Sample App. For demonstration purposes, the endpoint has a hardcoded friendlyName value of discoball. You can change the name to anything you want.

In the Sample App, endpoints are disabled by default. To enable them, 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 information about configuring Cmake for endpoints, see the Cmake parameters page.

Control the endpoint by voice

  • “Alexa, turn discoball on.”
  • “Alexa, increase discoball's speed.”
  • “Alexa, change discoball's mode to green.”

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

  • “Alexa, what is discoball's speed?”
  • “Alexa, what is discoball's mode?”

Control the endpoint through the Companion App

From the Companion App, the discoball endpoint appears as a Smart Home device that you can control 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 controller directives are received.