102 lines
3.7 KiB
Markdown
102 lines
3.7 KiB
Markdown
# 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
|