237 lines
6.3 KiB
Markdown
237 lines
6.3 KiB
Markdown
# 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](https://ziglang.org/) and [mise](https://mise.jdx.dev/) for version management.
|
|
|
|
The build defaults to `aarch64-linux` for AWS Lambda Graviton (arm64) deployment.
|
|
|
|
```bash
|
|
# 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](https://git.lerch.org/lobo/lambda-zig) - AWS Lambda runtime for Zig
|
|
- [controlr](https://git.lerch.org/lobo/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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
# .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](#deployment-setup))
|
|
2. **Amazon Developer Account** with ASK CLI authenticated (`bun x ask configure`)
|
|
3. **Rinnai credentials** in `.env` file (see [Rinnai Credentials](#3-rinnai-credentials))
|
|
|
|
### Full Deployment (Lambda + Alexa Skill)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|