HOWTO.md

Set up your own squeeze-alexa

Prerequisites

• A running LMS instance on a Linux-ish server or NAS (and some squeezebox players)
• An Amazon Echo / Echo Dot
• An Amazon developer account, and an Alexa one (tip: use the same email, or you'll wish you had)
• A router that supports port forwarding, and ideally DDNS of some sort (nearly all modern routers do).
• Some time and a little knowledge of: Linux, networking, AWS / Lambda, SSL
• Optional: a domain name, and a "real" (not self-signed) SSL certificate to match.

About this guide

• This is still a work in progress but improving all the time - and you can help!
• The documentation is versioned - so make sure you're using the docs for the same squeeze-alexa version you're installing (e.g. here's the v1.3 README).
• If you've followed this guide and are getting stuck, see TROUBLESHOOTING, or join the Gitter chat.
• If you want to add some helpful detail to make it easier for others, that's great, check CONTRIBUTING - but please raise an issue first.

Choose your networking

🆕 There are now two ways squeeze-alexa can work: SSL tunnel mode, or MQTT mode. These are referred to as transports.

SSL Tunnel

• The original and fastest
• Need a server that can run ssltunnel or newer ha-proxy.
• Need a router / firewall / ISP that can map incoming network ports.
• Documentation, FAQs and diagnostics right here.

MQTT Bridge

• Works on all networking / firewalls including 3G / 4G setups.
• Still experimental. It definitely works, but no documentation around much of this yet.
• Relies on more AWS infrastructure (AWS IoT)
• Need a server that can run Python (3.5+), to run mqtt-squeeze (or: write your own...)

So, you decide, then set up SSL transport or set up MQTT transport.

Set up your environment

Requirements

• Python 3.6+ (which will have pip), although 3.5 should work too (untested).
• Pipenv - just run pip install pipenv.
• Bash (or similar shell) - use Git for Windows if you're on Windows.
• A text editor / IDE e.g. Atom, PyCharm, vim, Sublime etc.

Optional: building from source

If you're installing the latest and greatest, or you prefer the developer-focused methods, you'll also need:

• Git (and Git for Windows if you're on Windows)
• GNU gettext for translations. On Linux, Debian-flavoured: sudo apt-get install gettext.py, or on Fedora etc (yum install gettext.py). For MacOS, brew install gettext.py && brew link --force gettext.py On Windows, install GetText for Windows.

Set up your Alexa Skill

Get squeeze-alexa

squeeze-alexa has official releases on Github. It is recommended to choose from these, but if you want the very latest (or plan to contribute yourself), get the master branch (no guarantees though generally the testing ensures it's fully working)*[]:

from a release

• Download a a release ZIP (or latest master)
• and extract this to your computer, e.g. to a direcotry like /home/me/workspace/squeeze-alexa.

from Source code

Make sure you have everything detailed in requirements above set up.

• Clone the repo: git clone [email protected]:declension/squeeze-alexa.git.
• You can / should still choose a release tag (e.g. git checkout v1.1), or go with bleeding edge (HEAD). Note you will have to run a release process now to get the translations
• Run the translation script: bin/compile-translations, else you'll get errors about like No translation file found.

Configure with your settings

ℹ️ All directories referred to here are relative to the directory you just set up (unless starting with /).

• Edit squeezealexa/settings.py, filling in the details as detailed there.
• Make sure your squeeze-alexa.pem file is moved to the root of the etc/certs directory (or wherever your CERT_DIR points to).

AWS overview

AWS can be daunting for newcomers and pros alike. The console and range of services is ever increasing, and they love changing things too. The first thing to remember is there are two interesting dashboards:

1. Your Amazon developer dashboard for developing and testing Amazon-related products including your Alexa skills...
2. The AWS Console, for administering all things AWS (notably Lambdas)

Create an ASK Custom Skill in your developer account

Overview

• Like most useful skills it should be a Custom Skill
• Follow one of the guides ideally e.g. Deploying a Sample Custom Skill To AWS Lambda.
• For squeeze-alexa > 1.2, use Python 3.6, or if not, perhaps choose an older release.
• Select an AWS region close to you (for better performance).
• The defaults are generally fine (those in lambda.json).
• You'll have to define the handler name - handler.lambda_handler.

After clicking through to the ASK section of the site, add a new Alexa Skill, then continue here

Skill Information

• Use the Custom Interaction Model
• Choose a language / region. It's been tested in English (UK), English (US) and German (Germany). If you want to help translate, please see the CONTRIBUTING guide.
• Choose your own Name (a reference really) and Invocation Name (what you use to talk to Alexa with). The advantage of not needing Amazon certification is you can be "more creative" about your naming...
• Select yes for Audio Streaming API, no for Video App and Render Template options.

As a picture is worth a thousand words, here's roughly what your Lambda function view should look like

Update the Interaction Model

The interaction model is the guts of how Alexa skills are invoked before they even get to your own code. Getting this right has been a lot of the magic of building a skill like squeeze-alexa, so hang tight.

Using the Skill Builder (v1) intents JSON...

Note: This has only been tested for en_US.

• The v1 intents is in metadata/intents/v1/locale/en_US
• In your Amazon Developer portal, configure your new skill:
  • Click on the JSON Editor under Intents
  • Copy-paste the v1 intents.json into the JSON editor It should look something like this:

...or using the original (v0) intents JSON

• These are kept here in metadata/intents
• In your Amazon Developer portal, configure your new skill:
  • Copy-paste the universal intents.json into the Intents schema
  • Copy-paste the utterances for your language as the sample utterances
• Add Slots. In theory these are optional, but you'll have to edit the interaction model if you opt out. Better just do to this (for British English, but you can choose another language):
  • Add a new slot type PLAYER, and copy players.txt in there, adding your player names if it helps.
  • Add a new slot type GENRE, and copy genres.txt in there, extending if necessary.
  • Add a new slot type PLAYLIST, and copy playlists.txt in there, adding your own for better results (avoiding short words helps, I find)

Here's another thousand words on roughly what you're aiming for:

Configuration

• Use the AWS ARN for your new AWS Lambda function. This is where the linkage between the AWS Console world and this Amazon Developer account becomes important. You'll have to read some Alexa + Lambda docs for full details.
• You don't want account linking. One day squeeze-alexa may implement this and build a server, but probably not.
• The new features (since 2016) are all unnecessary for squeeze-alexa, so no permissions necessary

Lambda setup

From your AWS console, select Lambda. Again, best to refer to the official the guides ideally e.g. Deploying a Sample Custom Skill To AWS Lambda. Here's what your Lambda function view should look like

Upload the customised skill

Create the zip file

• To build the package, use the helpful create_zip.sh script:

bin/create_zip.sh

To upload, you can choose:

Upload with the GUI

• Upload the created lambda_function.zip in the AWS Lambda interface (as described here)

...or with the AWS CLI

• You can use the AWS CLI update-function-code call to upload the zip from the manual step.
• Make sure you have the AWS CLI installed (e.g. pip install awscli) and have logged in (aws configure).
• Then

aws lambda update-function-code --zip-file fileb://lambda_function.zip --function-name squeezebox

(adjusting for your own function name, of course)

Install your Skill on your Echo

• Make sure you've enabled the testing checkbox for this skill in the developer portal
• In the Alexa app, you should see your Squeeze Alexa skill listed under Skills -> My Skills
• Do not submit the skill for certification. As the author of this software I am not allowing this under the license (or indemnifying any consequences of doing so), but more to the point it won't pass anyway.

Have fun with squeeze-alexa

Try some of the examples in the README! If you have something not supported, raise an issue.