CLAUDE.md

Project Overview

This repository contains ESPHome configuration files for various ESP32-based home automation devices integrated with Home Assistant.

Repository Structure

*.yaml - ESPHome device configuration files
Each YAML file represents a single ESP32 device with its specific configuration
Configurations use secrets for sensitive data (WiFi credentials, OTA passwords)

Device Inventory

ades-office-control-panel.yaml - Office control panel with LVGL display interface
ades-office-resistive-control-panel.yaml - Alternative office panel with resistive touchscreen
ns-panel-ground-floor.yaml - Sonoff NS Panel for ground floor controls
oekoboiler-interface.yaml - Interface for Oekoboiler (eco-boiler) monitoring/control
old-phone-doorbell.yaml - Repurposed old phone as doorbell system
powermeter.yaml - Power meter monitoring device

Technology Stack

ESPHome - ESP32/ESP8266 firmware framework
ESP32 - Microcontroller platform (esp32dev board)
Home Assistant - Primary home automation platform for integration
LVGL - Light and Versatile Graphics Library (used in control panels)
OTA Updates - Over-the-air firmware updates enabled

Common Patterns

Device Structure

Each device configuration typically includes:

substitutions: - Device-specific variables (name, friendly_name)
esphome: - Core ESPHome configuration
esp32: - Hardware platform settings
wifi: - Network connectivity (uses secrets)
ota: - Over-the-air update configuration (password-protected)
logger: - Logging configuration
api: - Home Assistant API integration (likely present)
Component-specific configs (sensors, displays, switches, etc.)

Secrets Management

Sensitive data is stored in a secrets file (not in repository):

!secret wifi_ssid
!secret wifi_password
!secret ota_password
Additional device-specific secrets

Communication Protocols

SPI - Display communication (TFT screens)
I2C - Sensor communication
WiFi - Network connectivity and Home Assistant integration

Development Workflow

Currently, configurations are transmitted "manually" (as noted in README), suggesting:

Manual upload to devices via ESPHome dashboard or CLI
No automated CI/CD pipeline yet
Direct device flashing workflow

When Working on This Project

Never commit secrets - Always use !secret references
Test locally first - ESPHome configurations should be validated before deployment
Backup configurations - These files represent physical device configurations
Check git history - Recent commits show auto-sync functionality was being developed
Device-specific testing - Changes to one YAML only affect that device
Home Assistant integration - Changes may require Home Assistant entity updates

Recent Activity

Git history shows auto-sync functionality in development:

test.yaml was being used for sync testing (now archived/deleted)
Multiple sync test devices were created and removed
Suggests move toward automated synchronization workflow

Useful Commands

# Validate a configuration
esphome config device-name.yaml

# Compile firmware
esphome compile device-name.yaml

# Upload to device
esphome upload device-name.yaml

# View logs
esphome logs device-name.yaml

Notes for AI Assistance

Focus on ESPHome best practices and YAML syntax
Consider Home Assistant integration implications
Respect existing device pin configurations (hardware-specific)
Maintain consistent naming conventions across devices
Be cautious with GPIO pin assignments (hardware limitations)
LVGL configurations are complex - reference ESPHome documentation

3.7 KiB Raw Blame History