Skip to content

Latest commit

 

History

History
246 lines (179 loc) · 13.8 KB

HOWTO.md

File metadata and controls

246 lines (179 loc) · 13.8 KB
Raw

Set up your own squeeze-alexa

Prerequisites

  • A Linux server, NAS (e.g. Synology) or even Raspberry Pi
  • LMS, typically running on the above server.
  • Some Squeezebox players - even if they're Chromecasts, RPIs other compatible devices.
  • At least one Amazon Echo device
  • An Amazon developer account, and an Alexa one (:information_source: use the same email, or you'll wish you had)
  • Some time and a little knowledge of: Linux, networking, AWS, Alexa, and SSL.
  • (SSL only): A router that supports port forwarding, and ideally DDNS of some sort (nearly all modern routers do).

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 alternative 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 tunnel...)

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).
  • Poetry - just run pip install poetry.
  • 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.
  • Recommended for MacOS: install coreutils if you haven't already (brew install coreutils)

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 zip

  • Release zips should have only what you need to set up and install your - not translator / developer tests, scripts etc.
  • Due to a few release problems, not all releases have these zips currently (follow the source code method instead)
  • 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.

...or from source code

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

  • Clone the repo: git clone git@github.com:declension/squeeze-alexa.git (or download a source zip from the releases page)
  • You can / should still choose a release tag (e.g. git checkout v1.1), or go with bleeding edge (HEAD).
  • Run the build: bin/build.sh 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.
  • Most of these can be left as-is, but you'll definitely need to fill in your APPLICATION_ID and your transport settings (hostnames / ports etc).
  • 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

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

Skill Information

  • Use the Custom Interaction Model
  • Choose a default language / region - see the README for supported languages. 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 all the other interfaces.

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

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

ℹ️ This is currently only translated for en_US and en_GB (see #103)

  • 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 (or drag & drop) the v1 intents.json into the JSON editor It should look something like this: Intents V1 screenshot
    • Save the model and build it.
...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: Slots screenshot

Endpoint configuration
  • This is where the linkage between the AWS Console world and this Amazon Developer account becomes important.
  • Once ready, enter the AWS ARN for your new AWS Lambda function (see below). 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 (since 2016) permissions (Address, lists, payment etc) are all unnecessary for squeeze-alexa, so leave them disabled.

AWS setup

🆕 As of v2.1, you can use deploy.py to automate the AWS Lambda creation / update including IAM permissions, etc (BETA). The script will output your Lambda ARN, for convenience in finishing the setup.

Manual lambda setup

If you prefer / have to do the setup manually...

  • From your AWS console, select Lambda.
  • Refer to the official the guides ideally e.g. Deploying a Sample Custom Skill To AWS Lambda.
  • Don't forget to create an IAM role for your skill.
  • Here's what your Lambda function view should look like Lambda console screenshot
  • Take a note of the ARN for your new lambda, to use in your Skill setup (See Endpoint Configuration above)

Upload the customised skill

If you chose building from source originally (developer-style), you need to build the project first. This runs various scripts and produces a minimal deployment directory of dist/, ready to zip.

Use the helpful build.sh script:

bin/build.sh

If not (so you probably won't even have the build script), you can skip this bit

Upload the zip file

To upload, you can choose:

🆕 deploy and set up AWS Lambda automatically

You'll need:

  • To be logged in to AWS CLI (Use aws configure or edit ~/.aws/config yourself with your secrets)
  • Your Alexa Skill ID (Click View skill ID in the Alexa Skills home page, or you can see it in the URLs). It starts amzn1.ask.skill...
bin/deploy.py aws --skill SKILL_ID

This creates or updates your AWS Lambda automatically Try deploy.py --help for details.

...or upload yourself

  • 🆕 Use the deploy.py script to (only) create a zip: 
    bin/deploy.py zip
    ℹ️ This uses the dist/ directory if it exists, else assumes you're using an expanded release zip (no tests / translation source / dev scripting etc).
  • Upload the created lambda_function.zip in the AWS Lambda interface (as described here)
  • ...or if you prefer, use the AWS CLI update-function-code call to upload the zip
    • 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 squeeze-alexa
      (adjusting for your own function name, of course)

Install your Skill on your Echo

  • You might need to enable the testing checkbox for this skill in the developer portal, though this seems to have moved.
  • 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.