diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a3ca5ee --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,78 @@ +# 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 .yaml +``` + +Output lands at `.esphome/build//.pioenvs//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. diff --git a/packages/devices_v0_7/display.yaml b/packages/devices_v0_7/display.yaml index a2d7a0a..a9944b3 100644 --- a/packages/devices_v0_7/display.yaml +++ b/packages/devices_v0_7/display.yaml @@ -108,6 +108,26 @@ display: it.printf(4, 61, id(size_10), TextAlign::BASELINE_LEFT ,"Temperature:"); it.printf(124, 61, id(size_10), TextAlign::BASELINE_RIGHT ,"%.2f°C", id(boneIO_temp).state); # additional pages should be defined between the first and last page + - id: second_page + lambda: |- + it.rectangle(0, 0, 126, 15); + it.printf(64, 11, id(size_10), TextAlign::BASELINE_CENTER, "Network"); + it.printf(4, 25, id(size_10), TextAlign::BASELINE_LEFT, "Host:"); + it.printf(124, 25, id(size_10), TextAlign::BASELINE_RIGHT, "%s", App.get_name().c_str()); + it.printf(4, 37, id(size_10), TextAlign::BASELINE_LEFT, "MAC:"); + it.printf(124, 37, id(size_10), TextAlign::BASELINE_RIGHT, "%s", get_mac_address().c_str()); + it.printf(4, 49, id(size_10), TextAlign::BASELINE_LEFT, "ETH:"); + it.printf(124, 49, id(size_10), TextAlign::BASELINE_RIGHT, "%s", id(eth).is_connected() ? "Connected" : "No link"); + - id: third_page + lambda: |- + it.rectangle(0, 0, 126, 15); + it.printf(64, 11, id(size_10), TextAlign::BASELINE_CENTER, "System"); + it.printf(4, 25, id(size_10), TextAlign::BASELINE_LEFT, "Version:"); + it.printf(124, 25, id(size_10), TextAlign::BASELINE_RIGHT, "%s", ESPHOME_VERSION); + it.printf(4, 37, id(size_10), TextAlign::BASELINE_LEFT, "Free heap:"); + it.printf(124, 37, id(size_10), TextAlign::BASELINE_RIGHT, "%u B", ESP.getFreeHeap()); + it.printf(4, 49, id(size_10), TextAlign::BASELINE_LEFT, "CPU freq:"); + it.printf(124, 49, id(size_10), TextAlign::BASELINE_RIGHT, "%u MHz", ESP.getCpuFreqMHz()); - id: last_page lambda: |- it.rectangle(0, 0, 126, 15);