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

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

# Run tests
zig build test -Dtarget=native

Dependencies

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

Deployment Setup

Before deploying, you need to configure both AWS credentials and ASK CLI authentication.

1. AWS Credentials

AWS credentials are required for Lambda deployment. You can configure them in several ways:

Option A: AWS CLI Configuration (Recommended)

# Configure default profile
aws configure

# Or configure a named profile
aws configure --profile personal

This creates ~/.aws/credentials and ~/.aws/config files.

Option B: Environment Variables

export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_DEFAULT_REGION=us-west-2

Using a Non-Default AWS Profile

If your default AWS profile is your work account but you want to deploy to your personal account:

# Set the profile for the current shell session
export AWS_PROFILE=personal

# Or specify it per-command
zig build awslambda_deploy -Dprofile=personal
zig build deploy -Dprofile=personal

You can also set the region:

zig build awslambda_deploy -Dprofile=personal -Dregion=us-west-2

2. ASK CLI Authentication

The ASK CLI requires authentication with your Amazon Developer account to deploy Alexa skills.

First-Time Setup

# Install dependencies (if not already installed)
bun install

# Configure ASK CLI (opens browser for Amazon login). Note this takes an ungodly
# amount of time to do anything and it will look like everything is hung
bun x ask configure

This will:

1. Open your browser to sign in with your Amazon Developer account
2. Store credentials in ~/.ask/cli_config

Verify Authentication

bun x ask smapi list-skills-for-vendor

3. Rinnai Credentials

The Lambda function needs your Rinnai account credentials to authenticate with the water heater API.

Create a .env file in the project root (this file is gitignored):

# .env
COGNITO_USERNAME=your@email.com
COGNITO_PASSWORD=your_password

These credentials will be automatically deployed to Lambda when you use the -Denv-file=.env option.

Build Steps

Step	Description
zig build	Build the bootstrap executable
zig build test	Run unit tests
zig build awslambda_package	Package Lambda function into zip
zig build awslambda_iam	Create/verify IAM role
zig build awslambda_deploy	Deploy Lambda function to AWS
zig build awslambda_run	Invoke the deployed Lambda function
zig build ask_deploy	Deploy Alexa skill metadata
zig build deploy	Deploy both Lambda and Alexa skill

Build Options

Option	Description	Default
-Doptimize=ReleaseFast	Build with optimizations	Debug
-Dtarget=native	Build for local machine	aarch64-linux
-Dfunction-name=NAME	Lambda function name	zig-fn
-Dprofile=PROFILE	AWS profile to use	default
-Dregion=REGION	AWS region	from profile
-Drole-name=ROLE	IAM role name	lambda_basic_execution
-Dpayload=JSON	Payload for awslambda_run	{}
-Denv-file=PATH	Environment variables file	none
-Dallow-principal=PRINCIPAL	AWS service principal to grant invoke permission	none

Deployment

Prerequisites

Before deploying, ensure you have:

1. AWS Account with credentials configured (see Deployment Setup)
2. Amazon Developer Account with ASK CLI authenticated (bun x ask configure)
3. Rinnai credentials in .env file (see Rinnai Credentials)

Full Deployment (Lambda + Alexa Skill)

zig build deploy -Doptimize=ReleaseFast \
    -Dfunction-name=water-recirculation \
    -Dprofile=personal \
    -Dregion=us-west-2 \
    -Denv-file=.env \
    -Dallow-principal=alexa-appkit.amazon.com

This command will:

1. Build the Lambda function for arm64
2. Package it into a zip file
3. Create/update the Lambda function in AWS
4. Set environment variables from .env
5. Grant Alexa Skills Kit permission to invoke the function
6. Deploy the Alexa skill metadata via ASK CLI

Lambda Only

zig build awslambda_deploy -Doptimize=ReleaseFast \
    -Dfunction-name=water-recirculation \
    -Dprofile=personal \
    -Dregion=us-west-2 \
    -Denv-file=.env \
    -Dallow-principal=alexa-appkit.amazon.com

Alexa Skill Only

zig build ask_deploy

Project Structure

water_recirculation/
├── build.zig              # Build configuration
├── build.zig.zon          # Dependencies (lambda-zig, controlr)
├── .env                   # Rinnai credentials (gitignored, create locally)
├── ask-resources.json     # ASK CLI deployment config
├── package.json           # Node.js deps for ASK CLI
├── src/
│   └── main.zig           # Alexa request handler + tests
├── skill-package/
│   ├── skill.json         # Alexa skill manifest
│   └── interactionModels/
│       └── custom/
│           └── en-US.json # Interaction model

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