The AVS Device SDK Console Sample App Overview

Use the AVS Device SDK Console Sample Application to become familiar with the core architecture and functionality of the AVS Device SDK. The Console Sample App implements all required components and features of the SDK that you need to initiate a connection to the AVS service. The app also handles basic, primarily voice-driven, interactions with Alexa, and completes tasks, such as answering questions, playing music, setting timers and alarms, and interacting with Alexa Skills.

The console in the Console Sample App is the Terminal window on your desktop that you use to invoke and interact with the Sample App through the command line interface (CLI). The console provides you with a means of communicating usage instructions, handling input, controlling settings, and logging SDK messages.

As a device maker, you should use the Console Sample App if you only require a single-process Alexa application integration in your product for completing mostly audio-based Alexa interactions. If you plan to implement more complex multimodal features for screen-based devices, consider using the AVS SDK IPC Server Sample Application.

Quick start guides

You can build the Console Sample Application for most Linux-based platforms. Amazon provides the following quick start guides for you to run the AVS Device SDK on the following three platforms:

Basic usage

The Console Sample Application provides an Options menu to guide you through common interactions. For more details about how to use the application, see Use the AVS Device SDK Console Sample App.

+----------------------------------------------------------------------------+
|                                  Options:                                  |
| Tap to talk:                                                               |
|       Press 't' and Enter followed by your query (no need for the 'Alexa').|
| Hold to talk:                                                              |
|       Press 'h' followed by Enter to simulate holding a button.            |
|       Then say your query (no need for the 'Alexa').                       |
|       Press 'h' followed by Enter to simulate releasing a button.          |
| Stop an interaction:                                                       |
|       Press 's' and Enter to stop an ongoing interaction.                  |
| Playback Controls:                                                         |
|       Press '1' for a 'PLAY' button press.                                 |
|       Press '2' for a 'PAUSE' button press.                                |
|       Press '3' for a 'NEXT' button press.                                 |
|       Press '4' for a 'PREVIOUS' button press.                             |
| Settings:                                                                  |
|       Press 'c' followed by Enter at any time to see the settings screen.  |
| Speaker Control:                                                           |
|       Press 'p' followed by Enter at any time to adjust speaker settings.  |
| Firmware Version:                                                          |
|       Press 'f' followed by Enter at any time to report a different        |
|       firmware version.                                                    |
| Info:                                                                      |
|       Press 'i' followed by Enter at any time to see the help screen.      |
| Reset device:                                                              |
|       Press 'k' followed by Enter at any time to reset your device. This   |
|       will erase any data stored in the device and you will have to        |
|       re-register your device.                                             |
|       This option will also exit the application.                          |
| Reauthorize device:                                                        |
|       Press 'z' followed by Enter at any time to re-authorize your device. |
|       This will erase any data stored in the device and initiate           |
|       re-authorization.                                                    |
| Device Setup Complete:                                                     |
|       Press 'v' followed by Enter at any time to indicate that device      |
|       setup is complete.                                                   |
|                                                                            |
| Quit:                                                                      |
|       Press 'q' followed by Enter at any time to quit the application.     |
+----------------------------------------------------------------------------+

Dependencies

For general dependency information, see Alexa Voice Service Device SDK Dependencies. In addition, the AVS Device SDK Console Sample App requires the following dependencies for you to build.

Library Description Minimum version
PortAudio Used for handling microphone audio input to the application. v190600_20161030
GStreamer Used for handling all audio media output from the application, including music playback, Alexa voice responses, and Alerts. 1.8.3

Optional adapters

You can enable the following optional adapters with CMAKE parameters to extend the features of the Console Sample App.

Adapter Description Requires permissioned access from Amazon
Bluetooth Support for connecting Bluetooth enabled peripherals. No
Alexa captions Support for WebVTT based captioning of common Alexa Speak directives. No
Multi-Room Music (MRM) Support for running the application as part of an Alexa named music group. Yes
Wake word engine (WWE) Support for building the application with a supported WWE for hand-free voice ingress. Yes (for Amazon provided WWEs)
Alexa Communications Support for initiating and receiving calls from other Alexa-enabled devices and users. Yes
Meeting client controller Support for joining meetings - part of the Alexa for Business (A4B) product offerings. Yes
Phone call controller Support for initiating phone calls through a connected calling device. Yes

Endpoint controllers

The Console Sample App provides reference implementations of the following controller interfaces for connected peripheral endpoints. For more details, see Enable endpoints in the Sample App.

Library Description
ModeController Used for controlling connected devices with named operational modes.
PowerController Used for controlling and reporting power state of connected devices.
RangeController Used for controlling properties of a connected device that can be set to a numeric value within a range.
ToggleController Used for controlling properties of a connected device with on and off functionality.
InputController Used for controlling input of entertainment devices.

Console Input/Output

|                       Dynamic Endpoint Modification Options:                              |
|  Press 'a' followed by Enter to add an endpoint with friendly name 'light'.               |
|  Press 'm' followed by Enter to toggle the endpoint's friendly name to 'light' or 'lamp'. |
|  Press 'd' followed by Enter to delete the endpoint.                                      |
|  Press 'q' followed by Enter to exit Dynamic Endpoint Modification Options.               |
+-------------------------------------------------------------------------------------------+;

+----------------------------------------------------------------------------+
|                 Peripheral Endpoint Controller Options:                    |
|  Press '1' followed by Enter to see Power Controller Options.              |
|  Press '2' followed by Enter to see Toggle Controller Options.             |
|  Press '3' followed by Enter to see Mode Controller Options.               |
|  Press '4' followed by Enter to see Range Controller Options.              |
|  Press 'q' followed by Enter to exit Endpoint Controller Options.          |
+----------------------------------------------------------------------------+;

Configuration

In addition to the build-time configuration options that the adapters provide, the Console Sample App also uses a configuration file for runtime configuration of the app.

For details about the runtime configuration of the Sample App, see AlexaClientSDKConfig.

The following example shows the general usage of the configuration file.

/<path-to-console-sample-app-build>/.SampleApp 
     -C /<path-to-client-config>/AlexaClientSDKConfig.json
  • Replace the <path-to-console-sample-app-build> with the actual path to your Console Sample App.
  • Replace the <path-to-client-config> with the actual path to your AlexaClientSDKConfig.json file.

For platform-specific usage instructions, see the quick start guides macOS, Rasbperry Pi, and Ubuntu.