79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
# 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.
|