# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repo is

ESPHome firmware configuration for an ESP32-based smart home lighting hub. The device runs on an `esp32dev` board with `esp-idf` framework, connects via Ethernet (LAN8720), and controls lights and fans throughout the house. `flows.json` contains the corresponding Node-RED automation flows that run in Home Assistant and react to input sensor state changes from this device.

## ESPHome commands

```bash
esphome compile main-hub.yaml      # compile only
esphome upload main-hub.yaml       # OTA upload
esphome logs main-hub.yaml         # stream logs from device
esphome run main-hub.yaml          # compile + upload + logs
esphome config main-hub.yaml       # validate and dump merged config
```

Secrets (wifi credentials, etc.) are expected in a `secrets.yaml` file in the same directory (WiFi is currently commented out in favor of Ethernet).

## Architecture

`main-hub.yaml` is the root config. It uses ESPHome's `packages:` feature to split the config across `packages/`:

| File | Purpose |
|---|---|
| `packages/i2c.yaml` | I2C bus definition (SDA:13, SCL:16, 200kHz) |
| `packages/pca9685.yaml` | 2× PCA9685 PWM drivers + all dimmable/color lights |
| `packages/mcp23017_outputs.yaml` | 3× MCP23017 output expanders + binary light wrappers |
| `packages/mcp23017_inputs.yaml` | 3× MCP23017 input expanders + all switch click automations |
| `packages/scripts.yaml` | `off_all_lights`, `off_all_fans`, and WLED placeholder scripts |

### I2C address map

| Device | Address | Role |
|---|---|---|
| mcp23xxx_hub1_IN | 0x20 | 16 inputs |
| mcp23xxx_hub1_OUT | 0x21 | 16 outputs |
| mcp23xxx_hub2_IN | 0x22 | 16 inputs |
| mcp23xxx_hub2_OUT | 0x23 | 16 outputs |
| mcp23xxx_hub3_IN | 0x24 | 16 inputs |
| mcp23xxx_hub3_OUT | 0x25 | 16 outputs |
| pca9685_hub1 | 0x40 | 16-ch PWM |
| pca9685_hub2 | 0x41 | 16-ch PWM |

### Naming conventions

- Binary outputs: raw GPIO output id is `hubN_outM_gpio`; the binary light wrapping it is `hubN_outM` (all `restore_mode: ALWAYS_OFF`)
- PWM outputs: `PWMX_Y_HubN` where X = circuit group, Y = channel within group, N = PCA9685 instance; all capped at `max_power: 75%` (some hub2 channels at 95%)
- Named lights (cwww/rgbww/monochromatic on PCA9685): `serwer_led`, `jadalnia_led`, `biala_lazienka_wanna_led`, `kuchnia_lezka_led`, `spa_ledy`, `pokoj_dla_gosci_led`, `sypialnia_led`
- Inputs: `hubN_inM`; fans are specific binary outputs noted in comments (hub1_out4, hub2_out5, hub2_out8, hub3_out2)

### Input click gestures

All input switches use `on_multi_click` with 350ms as the single-click vs. multi-click boundary:
- **single** (≤350ms ON, then ≥350ms OFF) → primary light toggle
- **double** (two short pulses) → secondary action
- **triple** (three short pulses) → often `off_all_lights` or WLED control
- **long** (≥350ms hold) → often `off_all_fans` or `off_all_lights + off_all_fans`

### WLED integration

WLED-controlled strips (korytarz kinkiety, komin, salon kinkiety, schody, wc, salon wentylator) are currently **placeholder scripts** that only log. The TODO in `scripts.yaml` notes these should be replaced with actual WLED control via Home Assistant/MQTT.

### `packages/main-hub.yaml`

This file is an identical copy of the root `main-hub.yaml`. It appears to be a duplicate — the canonical entry point for `esphome` commands is the root `main-hub.yaml`.