OneBusAway skill for Alexa

Are you ready to ask your Amazon Echo, "Alexa, where's my bus?"

This project is an implementation of the OneBusAway open-source platform for real-time transit info for Amazon's Alexa Voice Service.

Install and Use

Enabling the OneBusAway skill

To enable this skill on your Alexa device, you can say, "Enable OneBusAway skill."

You can also search for and enable skills in the Alexa app:

Open the Alexa app.
Open the left navigation panel, and then select Skills.
Use the search bar to enter "OneBusAway".
Tap on the "OneBusAway" skill, and select Enable Skill.

Using the OneBusAway skill

Just say "Alexa, open OneBusAway" to get started. You'll set your city and favorite stop, using the stop number. Then, just say "Alexa, open OneBusAway" to get arrival times for your favorite stop. You can find your stop number on the placard in the bus zone, in your OneBusAway mobile app, or on your agency website. If you have trouble finding your stop number, see our guide for "Finding your stop number".

Other features - say Alexa, ask OneBusAway to...:

...filter routes to filter out arrivals for particular routes for your currently selected stop
...enable clock times to announce times in a clock format like "at 10:25am" instead of "in 5 minutes"
...set my stop to X to change your stop to the specified number
...set my city to X to change your city to the specified city
...repeat to repeat the last message
...enable experimental regions to enable regions that may be unstable and without real-time info

Refer to interaction model/utterances.txt for the full list of spoken phrases we support.

Our user interface flow diagram also defined how you can interact with the skill.

Available cities

The OneBusAway skill is currently available in the following cities:

Atlanta, GA
Puget Sound, WA
Rogue Valley Transportation District, Oregon
San Diego Metropolitan Transit System, California
Tampa, FL
Washington, D.C.
York, Canada

See OneBusAway Deployments for more information about available OneBusAway regions.

Privacy Policy

See our Privacy Policy to better understand what information the OneBusAway Alexa skill uses when you request transit arrival information.

Contributing

Want to make OneBusAway Alexa better? We welcome collaboration! See our Contributing Guide for more details.

Develop

The application backing the skill was designed to run in AWS.

The set up process will be a bit circuitous, because, for security reasons, you want Lambda to run your code only if triggered by Alexa, rather than some random Internet visitor or script kiddie. To do this, we must create a skill first, and then supply its unique skill id to Lambda. But, to create a skill, a backing Lambda function should already be deployed. This is resolved by deploying a placeholder Lambda function first, and updating it later.

Therefore, the process is as follows:

Prepare AWS environment
Build the project
Deploy Lambda function. At this point this is only a placeholder needed to proceed with Alexa Skill set up.
Set up Alexa Skill backed by the Lambda function.
Note Alexa Skill id, supply it to the Lambda function, rebuild and redeploy.

1. Prepare AWS environment

Log into your AWS Console and switch to the "N. Virginia" region (currently, the only region that supports Alexa development)
Сreate a new CloudFormation Stack from the template aws/cloudformation/onebusaway.template.
Name your stack "onebusaway-alexa" for consistency with existing documentation.
On Review page under Capabilities section acknowledge "that this template might cause AWS CloudFormation to create IAM resources."
Click "Create" and wait for AWS to complete execution.
Switch to the Output tab of your new stack and note the output parameters. These are access keys and resource ARNs which you will need in the next sections.

You can examine AWS resources created from this template on the Resources tab.

Note that two distinct sets of AWS access credentials are being generated: {lambdaDeploymentAccessKey} and {lambdaDeploymentSecretKey} are for deploying Lambda functions, whereas {appExecutionAccessKey} and {appExecutionAccessSecret} are for running the application.

You can also use CloudFormation from command line with AWS CLI.

2. Build the project

Install the Java Platform SE Development Kit (JDK) and Maven.
Clone this repository.
Build this project on the command line with mvn package. Look for "BUILD SUCCESS". Resulting JAR is target/onebusaway-alexa-1.0-jar-with-dependencies.jar

3. Deploy Lambda function

Upload to Amazon Lambda with:

        mvn lambda:deploy-lambda \
            -DaccessKey={lambdaDeploymentAccessKey} \
            -DsecretKey={lambdaDeploymentSecretKey} \
            -Ds3Bucket={lambdaDeploymentS3Bucket} \
            -Dregion=us-east-1 \
            -DlambdaRoleArn={lambdaExecutionRoleARN}

...where {lambdaDeploymentAccessKey}, {lambdaDeploymentSecretKey}, {lambdaDeploymentS3Bucket} and {lambdaExecutionRoleARN} are values generated by CloudFormation during AWS infrastructure set up.

From the AWS Console > Lambda, open the newly created Lambda function and add a Trigger (Event Source) of type Alexa Skills Kit.
Note the ARN of the Lambda function at the top right corner of the screen. You will use it to set up a new Alexa Skill in the next section.

See the lambda maven plugin homepage for more information on deploying.

4. Set up Alexa Skill

Go to the Amazon Developer Console > Alexa
Add a new skill. Set Skill Type to Custom Interaction Model, set Invocation Name to "one bus away". Name can be anything since this is your development version.
Paste the contents of file interaction model/schema.json into "Intent Schema" text box.
Under "Custom Slot Types," click on "Add Slot Type". Under "Enter type", add TRANSIT_MODES. Under "Enter values", paste the contents of the file interaction model/customSlotTypes/TRANSIT_MODES.
Under "Custom Slot Types," click on "Add Slot Type". Under "Enter type", add AMAZON.US_CITY. Under "Enter values", paste the contents of the file interaction model/customSlotTypes/AMAZON.US_CITY.
Into "Sample Utterances" text box, paste the contents of file interaction model/utterances.txt.
On Configuration page set up your endpoint by plugging in your Lambda function's ARN. Go Next. That creates the skill, however it is not functional yet.
At the top of the screen note application ID. You will use it to configure Lambda code.

5. Configure, rebuild and redeploy Lambda function

Create src/main/resources/onebusaway.properties with the following parameters:

skill-app-id-development=
aws.key-id=
aws.secret-key=
googlemaps.api-key=
onebusaway.api-key=

Fill in the values:

skill-app-id-development is Alexa Skill ID from previous step

aws.key-id and aws.secret-key are {appExecutionAccessKey} and {appExecutionSecretKey} respectively as generated by CloudFormation

googlemaps.api-key Google Maps GeoCoding API Key which can be obtained from Google Developers

onebusaway.api-key can be obtained from your local OBA region. Typically, you can use TEST while are you waiting for a key.

Build this project on the command line with mvn package.
Upload updated .jar to Lambda.

CAUTION: Every time you re-deploy to Lambda using the lambda-maven-plugin, you must manually re-add "Alexa Skills Kit" as the function's Trigger. Support for Event Source configuration is coming. For now, you do not need to do this if you deploy your code through the Lambda UI in AWS Console.

Testing without an Alexa device

Don't have an Amazon Echo? No worries, there are a few options.

Alexa Skill Testing Tool - It simulates the Echo experience within your web browser (successfully tested with Firefox - Chrome and Microsoft Edge don't seem to work).
Roger, with Alexa - Roger is a free group voice messenger app, and it supports communicating with Alexa. See this Engadget article for details. Roger shut down on March 15th, 2017.
Amazon App on iOS - You can now access Alexa skills via the Amazon iOS app. See this article for details.

Just remember to log in using the same Amazon account that you've used above to set up the skill.

License

Apache v2.0

Puneethkumarck/onebusaway-alexa