68 lines
3.4 KiB
Markdown
68 lines
3.4 KiB
Markdown
# 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`.
|