Linux Reference Guide

This guide assumes familiarity with Linux and requires you to build dependencies from source.

Get started

Follow these steps:

1. Update and install the latest packages using apt-get:

   sudo apt-get update && sudo apt-get upgrade -y

2. Set up the SDK build environment.

   Create a my_project folder, and these subfolders:

   • build
   • source
   • third-party
   • application-necessities > sound-files

   Note: The following examples designate ~/ as the SDK installation location; be sure to replace all instances of ~/ in this guide with your explicit path.

   cd $HOME
   mkdir my_project
   
   cd my_project
   mkdir build source third-party application-necessities
   
   cd application-necessities
   mkdir sound-files

3. Install the core SDK dependencies:

   cd $HOME
   sudo apt-get install -y git gcc cmake openssl clang-format libgstreamer1.0-dev \
   libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-good \
   libgstreamer-plugins-good1.0-dev libgstreamer-plugins-bad1.0-dev \
   gstreamer1.0-libav pulseaudio doxygen libsqlite3-dev repo libasound2-dev

   IMPORTANT: Make sure that command ran successfully, and that no errors were thrown. If for any reason the install command fails, run brew install for each dependency individually.

4. Clone the AVS Device SDK into your $HOME/my_project/source folder:

   git clone https://github.com/alexa/avs-device-sdk.git

Build the AVS Device SDK

You can use CMake parameters to customize the sample app. For example, to get debug logs from the sample app, include the -DCMAKE_BUILD_TYPE=DEBUG option. To build with Bluetooth, see Build with Bluetooth.

In this example, it enables GStreamer and PortAudio, specifies the curl-openssl library location, and enables debug logging:

cd $HOME/my_project/build

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

Linux supports wake word detectors from Sensory and Kitt.ai. Each requires a license from the provider. For instructions to build with a wake word detector, please see Cmake parameters.

Build with Bluetooth

Building with Bluetooth is optional, and is currently limited to Linux and Raspberry Pi for A2DP-SINK, A2DP-SOURCE, AVRCPTarget, and AVRCPController profiles.

1. Install these dependencies:

   • Core Bluetooth dependencies
   • libpulse-dev
   • PulseAudio
   • PulseAudio bluetooth modules:

   cd $HOME
   sudo apt-get install pulseaudio-module-bluetooth
   

2. Include the following CMake option in your build:

BLUETOOTH_BLUEZ_PULSEAUDIO_OVERRIDE_ENDPOINTS

3. AVRCPTarget (if applicable)

If you are using the AVRCPTarget profile, you'll need to enable permissions for BlueZ to interact with "org.mpris.MediaPlayer2.Player".

To do this, open /etc/dbus-1/system.d/bluetooth.conf and add <allow send_interface="org.mpris.MediaPlayer2.Player"/> to your root policy.

For example:

<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>

  <!-- ../system.conf have denied everything, so we just punch some holes -->

  <policy user="root">
	...
   	<allow send_interface="org.mpris.MediaPlayer2.Player"/>
  </policy>

...

</busconfig>

Authorization

Before you can use the Device SDK sample app, you'll need to authorize it with the Alexa cloud in order to leverage the full range of Alexa capabilities and features available to the sample app.

Prerequisites

You must register an AVS Product and Create a Security Profile, if you haven't already.

Note: The product must be enabled for code-based linking.

Dependencies

Name	Description	Location
AlexaClientSDKConfig.json	The configuration file that you'll use to authorize the sample app with the Alexa cloud.	Comes with the SDK: avs-device-sdk/Integration/AlexaClientSDKConfig.json
genConfig.sh	The configuration file generator.	Comes with the SDK: avs-device-sdk/tools/Install/genConfig.sh
config.json	Downloaded when you created a security profile during the product registration process.	Your download location.

1. First, move the config.json file into the avs-device-sdk/tools/Install directory:

   mv $HOME/Downloads/config.json $HOME/my_project/source/avs-device-sdk/tools/Install

2. Next, create a database directory; this is the dynamic database used by AlexaClientSDKConfig.json:

   mkdir $HOME/my_project/build/Integration/database

3. Now, run genConfig.sh from the $HOME/my_project/source/avs-device-sdk/tools/Install directory, with these arguments:

   Arguments:

   1. config.json - Downloaded when you created a security profile during the product registration process.
   2. device_serial_number - the device serial number can be any unique alpha-numeric string (up to 64 characters). You should use the device serial number to identify your product or application instance. Many developers choose to use a product's SKU for this value.
   3. db_path - The directory where the dynamic database used by AlexaClientSDKConfig.json is stored, such as: ~/my_project/build/Integration/database.
   4. SDK source directory - Path to the avs-device-sdk source code, such as: ~/my_project/source/avs-device-sdk
   5. AlexaClientSDKConfig.json location - Path to the AlexaClientSDKConfig.json file, such as: ~/my_project/build/Integration/AlexaClientSDKConfig.json.

   For example:

   cd $HOME/my_project/source/avs-device-sdk/tools/Install
   
   bash genConfig.sh config.json device_serial_number \
   $HOME/my_project/build/Integration/database \
   $HOME/my_project/source/avs-device-sdk \
   $HOME/my_project/build/Integration/AlexaClientSDKConfig.json

   IMPORTANT: Create a backup of your AlexaClientSDKConfig.json file. Subsequent builds will reset the contents of this file.

2. Finish authorization using Login with Amazon

1. Navigate to your build folder, and initialize the SampleApp:

   cd $HOME/my_project/build
   ./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json

2. Wait for the sample app to display a message like this:

##################################
#       NOT YET AUTHORIZED       #
##################################
################################################################################################
#       To authorize, browse to: 'https://amazon.com/us/code' and enter the code: {XXXX}       #
################################################################################################

3. Use a browser to navigate to the URL specified in the message from the sample app.
4. If requested to do so, authenticate using your Amazon user credentials.
5. Enter the code specified in the message from sample app.
6. Select “Allow”.
7. Wait for the sample app to report that it is authorized, and that Alexa is idle. It will look something like this:

###########################
#       Authorized!       #
###########################
########################################
#       Alexa is currently idle!       #
########################################

8. You are now ready to use the sample app! The next time you start the sample app, you won't need to go through the authorization process.

A couple more details:

• If you exit out of sample app via the k command, the CBLAuthDelegate database will be cleared and you will need to reauthorize your client.
• If you want to move this authorization to another sample app installation, you need to copy the deviceInfo object within AlexaClientSDKConfig.json to the new installation. You will also need to copy the file "$HOME/my_project/application-necessities/cblAuthDelegate.db" to the new installation, and update AlexaClientSDKConfig.json in the new installation so that the cblAuthDelegate's databaseFilePath property points to it.

Use the sample app

Now that you have a working sample app, try an interaction with Alexa.

If you have quit the sample app, start it again:

    ./SampleApp/src/SampleApp ./Integration/AlexaClientSDKConfig.json DEBUG9

Interact with Alexa using tap-to-talk

Press T+Enter, and ask Alexa something.

For example:

User taps-to-talk (T+Enter): "Alexa, what's the weather like?"

Alexa: "Right now in Portland, it's 71 degrees with sun..."

Additional options

Interaction options

Action	Command
Tap to talk	t+Enter, followed by your query (no need to say "Alexa...").
Hold to talk	h+Enter, followed by your query (no need to say "Alexa...").
Simulate button release	h+Enter
Stop an interaction	s+Enter

Playback controls

Action	Command
Play	1
Pause	2
Next	3
Previous	4

Settings

Action	Command
View available settings	c+Enter
Adjust speaker settings	p+Enter
Report firmware version	f+Enter
Help screen	i+Enter
Reset device	k+Enter; this will erase any data stored on the device, and you will have to re-register it. This will also exit the application.
Quit	q+Enter

Run integration and unit tests

After you've authorized your sample app, run integration and unit tests to ensure that the AVS Device SDK is functioning as designed.

• Use this command to run integration tests:

  make all integration

• Use this command to run unit tests:

  make all test

For additional details, see Unit and Integration Tests.

Set up launch shortcut

You can designate aliases to launch the sample app. To do this:

1. Open ~/.bash_profile, and add these aliases and save:
   IMPORTANT: Make sure you update the paths to match your folder structure.

   alias alexac="{path_to}/{build}/SampleApp/src/SampleApp {path_to}/{build}/Integration/AlexaClientSDKConfig.json"
   alias alexacdebug="{path_to}/{build}/SampleApp/src/SampleApp {path_to}/{build}/Integration/AlexaClientSDKConfig.json DEBUG9"

2. After you've added these aliases, make sure to activate your ~/.bash_profile:

   source ~/.bash_profile

3. Now to launch the sample app, you can run this command:

   alexac