ESP32-Hub/CLAUDE.md

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

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.