Skip to content
This repository has been archived by the owner on Jan 16, 2024. It is now read-only.

Ubuntu Linux Quick Start Guide

Jump to bottom
brest-amzn edited this page Nov 1, 2019 · 25 revisions

These instructions will get you up and running on a machine running Ubuntu Linux 16.04 LTS. For all other distributions, please review dependencies and Cmake parameters for Generic Linux.

Prerequisites

  • Ubuntu Linux 16.04 LTS
  • Hardware audio input/output (microphone and speakers or headphones)

Get started

  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 
    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-0 \ 
gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly \
gstreamer1.0-libav gstreamer1.0-doc gstreamer1.0-tools \ 
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. Verify that the openssl and nghttp2 dependencies are installed; these dependencies are using to connect to AVS using HTTP:

    curl -version

    Sample output

    curl 7.65.0 (x86_64-apple-darwin17.7.0) libcurl/7.65.0 OpenSSL/1.0.2r zlib/1.2.11 brotli/1.0.7 c-ares/1.15.0 libssh2/1.8.2 nghttp2/1.38.0 librtmp/2.3

    If they are installed, you can proceed to step 5.

    If they aren't installed, you'll need to manually install them:

    cd $HOME/my_project/third-party
sudo apt-get -y install build-essential nghttp2 libnghttp2-dev libssl-dev
wget https://curl.haxx.se/download/curl-7.63.0.tar.gz
tar xzf curl-7.63.0.tar.gz

cd curl-7.63.0
./configure --with-nghttp2 --prefix=/usr/local --with-ssl

make && sudo make install
sudo ldconfig

    Verify curl:

    Now that you've manually installed the curl dependencies, verify that you can run curl:

    curl -I https://nghttp2.org/

    If the request succeeds, you will see a message like this:

    HTTP/2 200
date: Fri, 15 Dec 2017 18:13:26 GMT
content-type: text/html
last-modified: Sat, 25 Nov 2017 14:02:51 GMT
etag: "5a19780b-19e1"
accept-ranges: bytes
content-length: 6625
x-backend-header-rtt: 0.001021
strict-transport-security: max-age=31536000
server: nghttpx
via: 2 nghttpx
x-frame-options: SAMEORIGIN
x-xss-protection: 1; mode=block
x-content-type-options: nosniff

  5. Clone the SDK into the ~/my_project/source folder:

    cd $HOME/my_project/source
git clone git://github.com/alexa/avs-device-sdk.git

  6. Install and configure PortAudio (a required audio input/output library), and then make your build.

    cd ../third-party
wget -c http://www.portaudio.com/archives/pa_stable_v190600_20161030.tgz
tar xf pa_stable_v190600_20161030.tgz

cd portaudio
./configure --without-jack && make

Build the SDK

  1. 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.

    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

  2. Finish building the SDK from your build directory:

     make SampleApp -j2

    If you want to build the full SDK, including unit and integration tests, run make instead of make SampleApp. You can use the arguments j2,-j3 or j4 to run processes in parallel during make.

Include Bluetooth (optional)

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

To enable Bluetooth on Linux, follow these steps:

  1. Install these dependencies:
cd $HOME
sudo apt-get install pulseaudio-module-bluetooth
  1. Include the following CMake option in your build:

BLUETOOTH_BLUEZ_PULSEAUDIO_OVERRIDE_ENDPOINTS

  1. 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

  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}       #
################################################################################################
  1. Use a browser to navigate to the URL specified in the message from the sample app.
  2. If requested to do so, authenticate using your Amazon user credentials.
  3. Enter the code specified in the message from sample app.
  4. Select “Allow”.
  5. 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!       #
########################################
  1. 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

  1. After you've built the AVS Device SDK, we recommend running integration and unit tests to make sure that the 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.

Update the SDK

To update the SDK, follow [these instructions[(https://github.com/alexa/avs-device-sdk/wiki/Updating-the-SDK).

Home

API Reference

Quick-start Guides

Other Guides + Optimizations

Development Kits

Resources

Issue Reporting Guide

Clone this wiki locally