BoneIO-ESP/CLAUDE.md

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:

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):

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.

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.