Awesome
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. Note that you first need to set up the skill with a non-experimental region and stop that are supported by default before invoking this command - see this post for details.
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
- Spokane, WA
- 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 istarget/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/newSchema.json
into "JSON Editor" under interaction model. - Save and build the model.
- On Endpoint 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.
4.1 Personalize your skill
To set up your skill to support personalization, you must follow these steps.
- Set up your skill to request personalization permissions.When you create or edit a custom skill, you can turn on permissions for Skill Personalization in the developer console.
- In the developer console, create or open your skill.
- Select the Build tab, and select Permissions at the bottom left.
- In the Permissions section, turn on the toggle for Skill Personalization.
- You can also edit the permissions in the skill manifest for your skill directly to add the personalization scope alexa::person_id:read if you are using SMAPI or ASK CLI to build your skill.
- Set up your skill service to use personalization in its responses, if Personalize skills is toggled on for a recognized user.
- Make sure your skill service gracefully handles those cases where a user is not recognized, or a user refuses permission for personalization.
4.2 Listen to skill event (OPTIONAL)
- Currently OneBusAway supports SkillEnabled and SkillDisabled events.
- The ONLY WAY to enable your test skill to listen to events is using Skill Management API (SMAPI), please follow the Quick Start: Alexa Skills Kit Command Line Interface (ASK CLI) to install ASK CLI.
- After you setup CLI, please using
ask api get-skill -s {skillId} > skill.json
to get your skill schema inskill.json
file, add the event subscription JSON blob below to skill.json, and runask api update-skill -s {skillId} -f skill.json > skill.json
to update the schema, reference: Add Events to Your Skill
Event subscription JSON blob.
"event": {
"endpoint": {
"uri": "{lambdaExecutionRoleARN}"
},
"regions": {
"NA": {
"endpoint": {
"uri": "{lambdaExecutionRoleARN}"
}
}
},
"subscriptions": [
{
"eventName": "SKILL_ENABLED"
},
{
"eventName": "SKILL_DISABLED"
}
]
}
Example of skill schema with event subscription.
{
"manifest": {
"apis": {
"...":"..."
},
"events": {
"subscriptions": [
{
"eventName": "SKILL_ENABLED"
},
{
"eventName": "SKILL_DISABLED"
}
],
"regions": {
"NA": {
"endpoint": {
"uri": "{lambdaExecutionRoleARN}"
}
}
},
"endpoint": {
"uri": "{lambdaExecutionRoleARN}"
}
},
"manifestVersion": "x.x",
"permissions": [
{"...":"..."}
],
"privacyAndCompliance": {
"...":"..."
},
"...":"..."
},
"...":"..."
}
}
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.