Alexa Skill Setup

Runbook for wiring the deployed AWS edge (Terraform) to an Alexa Smart-Home skill, linking the account, and verifying end-to-end. The manifest and account-linking templates live in skill-package/.

1. Create the skill (placeholder endpoint)

There is a chicken-and-egg between the skill ID and the Lambda: the directive Lambda's permission requires the skill ID (alexa_skill_id Terraform variable), and the skill needs the Lambda ARN as endpoint. Resolve it in this order:

1. Alexa Developer Console → Create Skill → type Smart Home, language German (DE) (de-DE), payload version v3 — or use skill-package/skill.json with the ASK CLI.
2. Copy the Skill ID (amzn1.ask.skill.…) from the console.

2. Deploy the AWS edge with the skill ID

cd terraform
./deploy.sh migrate --tfvars terraform.tfvars \
  -var "alexa_skill_id=amzn1.ask.skill.<your-skill-id>"
terraform output deployment_summary

3. Terraform outputs → console fields

Terraform output	Alexa Developer Console field
directive_lambda_arn	Smart Home → Default endpoint (and Europe / India)
oauth_authorize_url	Account Linking → Web Authorization URI
oauth_token_url	Account Linking → Access Token URI

The remaining deployment_summary values (beacon_bucket_name, beacon_object_key, shared_secret_param) configure the home server's beacon publisher and HMAC signing — not the console.

4. Account linking

Console → Account Linking (values mirror skill-package/accountLinking.json):

Field	Value
Auth grant type	Auth Code Grant
Web Authorization URI	oauth_authorize_url output
Access Token URI	oauth_token_url output
Client ID	alexa-skill (free-form; the server binds it to the auth code)
Client Secret	any non-empty value — the server is a PKCE-only public client and ignores it
Authentication Scheme	Credentials in request body
Scope	smart_home
Domain list / redirect URLs	leave empty / defaults

After saving, copy the three Alexa Redirect URLs shown in the console into the home server's PANTAU_OAUTH_ALLOWED_REDIRECT_URIS (comma-separated) and restart the server.

Home-server prerequisites:

• PANTAU_JWT_SECRET, PANTAU_SHARED_SECRET set (the latter matching the SSM parameter from shared_secret_param).
• A user created via uv run pantau-users add <username>.
• Tunnel running and the beacon published to S3 (endpoint.json).

Then: Alexa app → skill → Enable to use → log in on the home server's login page. The token exchange runs Authorization Code + PKCE (S256 is enforced by the server; verify during E2E that Alexa sends code_challenge — see risks below).

5. Device discovery

Alexa app → Geräte suchen (or say „Alexa, suche nach neuen Geräten"). All endpoints from config/devices.yaml (channels, TV audio, blinds, thermostats) must appear. After every change to devices.yaml, re-run discovery.

Pre-check without hardware: invoke the Lambda with scripts/sample-events/discovery.json (see scripts/sample-events/README.md).

6. E2E verification checklist

Infrastructure (KONZEPT §12):

• [ ] terraform plan/apply clean; Lambda answers the sample events (aws lambda invoke, see scripts/sample-events/).
• [ ] Beacon updater writes endpoint.json; Lambda's conditional GET picks up a changed tunnel URL.
• [ ] Account linking completes in the Alexa app; token refresh works (wait > 60 min, issue a command).
• [ ] Directive latency < 8 s, token endpoint < 4.5 s (watch cold starts).

German utterances (verify against the real de-DE NLU model, KONZEPT §10):

• [ ] „Alexa, schalte ZDF ein" → TV activity starts, channel 2 — robust (PowerController device).
• [ ] „Alexa, mach die Rollos in der Küche halb runter" → blind at 50 %. If „halb" is not understood, use the fallback „… auf 50 Prozent" (RangeController semantics).
• [ ] „Alexa, schalte den Fernseher stumm" → mute on; „Alexa, schalte den Ton ein" → mute off (routing to Speaker.SetMute(false) is uncertain — mitigation: optional Ton PowerController synonym device).
• [ ] „Alexa, stell die Heizung im Wohnzimmer auf 22 Grad" → FRITZ!Box target temperature 22 °C.

7. Known risks (documented, KONZEPT §10)

• Mute drift — Harmony only offers a mute toggle; the server keeps an assumed state. Muting via the original remote desynchronizes it (residual risk, accepted).
• NLU phrasing — exact German sentences are decided by Alexa's Smart-Home NLU, not by this project. Verify the utterances above early on the real model and prefer the documented fallbacks („auf 50 Prozent", Ton synonym device).
• Channel selection depends on the Harmony activity name and digit timing; PKCE support of Alexa's account-linking flow must be confirmed during E2E (the token endpoint rejects exchanges without code_verifier).