alexa-house-control/README.md

Water Recirculation Alexa Skill

An Alexa skill that triggers water recirculation on Rinnai tankless water heaters.

Usage

"Alexa, ask house to start the hot water"

This will authenticate with the Rinnai API and start a 15-minute recirculation cycle.

Building

Requires Zig 0.15 and mise for version management.

The build defaults to aarch64-linux for AWS Lambda Graviton (arm64) deployment.

# Debug build (arm64)
zig build

# Release build (arm64)
zig build -Doptimize=ReleaseFast

# Create Lambda deployment package
zig build -Doptimize=ReleaseFast package

# Build for native target (e.g., for local testing)
zig build -Dtarget=native

Dependencies

• lambda-zig - AWS Lambda runtime for Zig
• controlr - Rinnai API client (provides rinnai module)

Deployment

Prerequisites

• AWS CLI configured with appropriate credentials
• mise (for zig and bun version management)

1. Build the Package

mise exec -- zig build -Doptimize=ReleaseFast package

This creates function.zip containing the arm64 bootstrap executable.

2. Create Lambda Function (first time only)

aws lambda create-function \
  --function-name water-recirculation \
  --runtime provided.al2023 \
  --handler bootstrap \
  --architectures arm64 \
  --role arn:aws:iam::ACCOUNT_ID:role/lambda_basic_execution \
  --zip-file fileb://function.zip \
  --timeout 30 \
  --memory-size 128

3. Set Environment Variables

aws lambda update-function-configuration \
  --function-name water-recirculation \
  --environment "Variables={COGNITO_USERNAME=your@email.com,COGNITO_PASSWORD=your_password}"

4. Update Function Code (subsequent deploys)

mise exec -- zig build -Doptimize=ReleaseFast package

aws lambda update-function-code \
  --function-name water-recirculation \
  --zip-file fileb://function.zip

5. Deploy Alexa Skill

First time setup - configure ASK CLI (opens browser for Amazon login):

mise exec -- bunx ask-cli configure

Deploy the skill:

mise exec -- bunx ask-cli deploy

This will:

• Create the Alexa skill in your developer account
• Upload the interaction model
• Link to the Lambda endpoint

After deployment, add the Alexa Skills Kit trigger permission to Lambda:

aws lambda add-permission \
  --function-name water-recirculation \
  --statement-id alexa-skill \
  --action lambda:InvokeFunction \
  --principal alexa-appkit.amazon.com \
  --event-source-token amzn1.ask.skill.YOUR_SKILL_ID

Project Structure

water_recirculation/
├── build.zig              # Build configuration (defaults to arm64-linux)
├── build.zig.zon          # Dependencies (lambda-zig, controlr)
├── ask-resources.json     # ASK CLI deployment config
├── src/
│   └── main.zig           # Alexa request handler
├── skill-package/
│   ├── skill.json         # Alexa skill manifest
│   └── interactionModels/
│       └── custom/
│           └── en-US.json # Interaction model
└── function.zip           # Lambda deployment package (after build)

Sample Utterances

• "start the hot water"
• "turn on the hot water"
• "heat the water"
• "preheat the water"
• "start recirculation"
• "warm up the water"

Lambda Details

• Function: water-recirculation
• Region: us-west-2
• Architecture: arm64 (Graviton)
• Runtime: provided.al2023
• ARN: arn:aws:lambda:us-west-2:932028523435:function:water-recirculation

Alexa Skill

• Skill ID: amzn1.ask.skill.c373c562-d574-4f38-bd06-001e96426d12
• Invocation: "Alexa, ask house to..."

License

MIT