Tips Tricks and Insights

This is the companion wiki to the 2017 AWS re:Invent chalk talk: ALX327 - Alexa Smart Home

Chalk talk abstract: Explore how to build Alexa Smart Home skills for smart devices so you can delight your customers with voice control, routines, and responsive experiences that work across multiple locales. In this session, learn the developer resources available to you today so you can ship a high quality skill quickly and effortlessly. Plenty of tips, tricks, and insights from Alexa Smart Home experts and an experienced Honeywell API evangelist.

Anatomy of a smart home skill

• Understand how smart home skills work
• ALX316 - How to Build a Backend for an Alexa Smart Home Skill -- this session will provide insight on how to build a profressional-grade backend to support your smart home skill

Why build a smart home skill?

• Delightful, natural voice user experience
• Alexa takes care of speech across [all locales]((https://developer.amazon.com/docs/smarthome/develop-smart-home-skills-in-multiple-languages.html); you just take care of the device
• Integration with Alexa multi-modal experiences for free, for example: GUI, routines
• Leverages your existing services through standard tech, for example: Lambda, OAuth
• Constantly evolving capabilities and support for new IoT devices
• Eligible for the Works with Amazon Alexa (WWAA) program

Build a skill in 5 minutes

• More like 15 minutes if you’re starting from scratch
• Use guide in GitHub
• For this chalk talk, we’ll just walk through the five easy steps with an already created skill

1. Set up Login with Amazon (LWA)
2. Create the skill
3. Create the Lambda function
4. Configure the skill
5. Test directives and proactive state updates

Lambda best practices

• Lambda is STATELESS!
• Use Lambda versioning and aliases
• Set Lambda timeout to 7 seconds or less
• Watch out for limits
• Remember to add monitoring

About monitoring

• Use Amazon CloudWatch and open source tools, e.g. awslogs
• In your Lambda, log everything, especially messageIds
• Set up CloudWatch metrics and alarms
• In CloudWatch, add a “Last Ingestion Time” column
• Be sure to redact private content in logs

Example Lambda log entry

[INFO] 2017-10-14T04:07:46.731Z 3ae87dda-b095-11e7-a34e-c77fb90d5435 { "directive": { "header": { "messageId": "b7aa9fd5-ea9e-4170-9c39-0cbe4b9a273c", "name": "Discover", "namespace": "Alexa.Discovery", "payloadVersion": "3" }, "payload": { "scope": { "token": "Atza|<REDACTED>", "type": "BearerToken" } } } }

Migrating from v2

• Look at the example Lambda in our GitHub and also check our migration guide
• Build adapters and converters
• Need to support both v2 and v3 directives during the transition period
• Call v2 Lambda from v3 Lambda

It’s all about state

• State is very important—user wins, you win
• Handle ReportState directives with as much state info as possible
• Proactive State Updates (PSU) or ChangeReports mean less traffic to your Lambda
• For “Works with Amazon Alexa” certification, all of your endpoints must support PSU for all properties (except endpoints that do not have properties/state)

Tips about device discovery

Alexa only knows about a device if your skill reports it through the Discovery interface

• Don’t forget the “Alexa” interface for each endpoint
• Double check capability versions
• Use the right display category for your device; this affects how the Alexa App displays your device
• If no devices or error encountered, return empty endpoints array
• Use a globally unique endpointId for easy debugging
• For easy debugging and save lookups on your side, store useful data in the cookie property
• Remember, this is where you declare how you handle state for your device

Send correct messages

• Validation Schemas, use them!
• Use online validators for quick testing, e.g. JSON Schema Lint
• Enable runtime validation for both Lambda and async messages, e.g. JSON Schema Libraries

Async and PSU

• Used for both deferred responses and proactive state updates (PSUs)
• In AcceptGrant flow, persist LWA tokens with Lambda region so you can send async messages to the Alexa endpoint in the correct region, for example:
  • LWA access token 1, refresh token 1, TTL 1, device ID 1, NA
  • LWA access token 2, refresh token 2, TTL 2, device ID 2, EU
• Preemptively refresh LWA access tokens. Remember that LWA access tokens expire in 1 hour (first token refreshes in 15 mins), and refresh tokens do not expire
• Multiple Alexa users can have the same device, so PSUs must be sent for all

Async and PSU (Honeywell)

• Not only multiple Alexa users, but multiple internal users on the same device
  • Alexa User 1, Honeywell User 1, TTL 1, device ID 1, NA
  • Alexa User 2, Honeywell User 2, TTL 2, device ID 1, NA
• Example of our device event data. Had to fork into multiple POST requests per LWA token (Alexa User) and Honeywell User: {"sequenceNumber":1071,"event":{"IndoorTemperature":72,"Units":"F","IndoorTemperatureStatus":"Measured","MacId":"00D02DAB5CBE","OccuredAt":"2017-10-18T21:59:07.096Z","Subsystem":"Lcc"},"receivedTime":"2017-10-18T21:59:07.323Z","queuedTime":"2017-10-18T21:59:07.096Z","macId":"00D02DAB5CBE","messageType":"ThermostatIndoorTemperatureEvent"}
• Any business logic to interpret your events into Alexa-speak
• Load peaks—thermostat schedule changeovers (3k events/min to 15k peaks)

Multi-language support

• Use the Skill Management API to easily update multi-region skills

Test, submit, publish, repeat

• Review the publishing guide