# 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