# 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

1. **ades-office-control-panel.yaml** - Office control panel with LVGL display interface
2. **ades-office-resistive-control-panel.yaml** - Alternative office panel with resistive touchscreen
3. **ns-panel-ground-floor.yaml** - Sonoff NS Panel for ground floor controls
4. **oekoboiler-interface.yaml** - Interface for Oekoboiler (eco-boiler) monitoring/control
5. **old-phone-doorbell.yaml** - Repurposed old phone as doorbell system
6. **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

1. **Never commit secrets** - Always use `!secret` references
2. **Test locally first** - ESPHome configurations should be validated before deployment
3. **Backup configurations** - These files represent physical device configurations
4. **Check git history** - Recent commits show auto-sync functionality was being developed
5. **Device-specific testing** - Changes to one YAML only affect that device
6. **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

```bash
# 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