Skip to content

Ubuntu Linux Quick Start Guide

leala-amzn edited this page Jun 12, 2019 · 21 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-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. 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
    wget http://curl.haxx.se/download/curl-7.54.0.tar.bz2
    tar -xvjf curl-7.54.0.tar.bz2
    
    cd curl-7.54.0
    ./configure --with-nghttp2=/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).

You can’t perform that action at this time.