new file: CLAUDE.md

modified: packages/devices_v0_7/display.yaml
2026-04-08 23:08:16 +02:00
parent 6d97433607
commit 0df5b784d5
2 changed files with 98 additions and 0 deletions
--- a/CLAUDE.md
+++ 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 <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.
--- 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);