# CLAUDE.md

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

## Project Overview

ESPHome firmware configurations and build automation for BoneIO IoT control devices (switches, lights, dimmers, covers, inputs) running on ESP32/ESP32-S3 microcontrollers with Ethernet connectivity.

## Build

Firmware is compiled via Docker using the ESPHome image. To compile a single config:

```bash
docker run --rm -p 6053:6052 -v "$(pwd)":/config -it ghcr.io/esphome/esphome compile <filename>.yaml
```

Output lands at `.esphome/build/<device-name>/.pioenvs/<device-name>/firmware.factory.bin`.

To compile and distribute all production configs (controlled by `include_files`/`exclude_files` lists in the script):

```bash
python create_firmware.py
```

This copies binaries to `../website2/public/fwesp/firmware/` and `../esphome_uploader/firmware/`, and generates ESP Web Tools JSON manifests.

There is no linting or test framework — validation happens during ESPHome compilation.

## Architecture

### Config Layering

Root-level YAML files (e.g., `boneio-24x16_switches_v0_7.yaml`) are complete device configs. They pull shared functionality via the `packages:` key, referencing the GitHub repo `boneIO-eu/esphome` at tag `packages-v2.0.0`.

```yaml
packages:
  internals_packages:
    url: https://github.com/boneIO-eu/esphome
    ref: packages-v2.0.0
    files: [
        'packages/devices/buzzer.yaml',
        'packages/devices_v0_7/display.yaml',
        ...
      ]
```

When editing packages locally, note that root configs fetch packages from GitHub — local `packages/` directory changes are for local development and must be pushed to the remote ref to take effect in production builds.

### Package Directory Structure

- `packages/devices/` — hardware-agnostic drivers (buzzer, serial number from MAC)
- `packages/devices_v{VERSION}/` — version-specific peripherals: display, I2C buses, INA219 power monitor, LM75B temp sensor, PCF/MCP GPIO expanders
- `packages/boards/` — board-specific output pin mappings (24x16, 32x10, mosfet48, dimmer variants, cover outputs)
- `packages/configuration/` — dimmer-specific development configs

### Hardware Variants

| Naming pattern | Chip | Notes |
|---|---|---|
| `*_v0_5-v0_6`, `*_v0_7`, `*_v0_9` | ESP32 (nodemcu-32s) | Ethernet via LAN8720 |
| `*_gen2*` | ESP32-S3 | Second-generation hardware |
| `development/` | mixed | WIP configs, not for production |
| `discontinued/` | mixed | Deprecated, do not modify |

### I2C & GPIO Expanders

All boards use two I2C buses. Inputs are read via PCF8574/PCF8575 expanders (inverted logic — active low). Outputs use MCP23017 expanders on the output bus. The `packages/devices_vX/pcf*.yaml` and `packages/boards/*_output.yaml` files define the expander addresses and pin mappings.

### Key Substitution Variables

Every root config defines these at the top:
- `name` — ESPHome device name (used as MQTT prefix, DNS hostname suffix)
- `friendly_name` — Human-readable label in Home Assistant
- `serial_prefix` — Prefix for serial number entity (always `'esp'`)

### Modbus

Modbus (UART on GPIO14/GPIO15) is available on switch/light boards but commented out by default. Uncomment the `uart:`, `modbus:`, and `modbus_controller:` blocks to enable.