initial commit

README.md

@@ -0,0 +1,223 @@
+# ESPHome Webhook Service
+
+A Docker-based webhook service for automating ESPHome device compilation and deployment with file watching capabilities.
+
+## Features
+
+- **Webhook Endpoints**: Trigger ESPHome operations via HTTP POST requests
+- **File Watching**: Automatically detect YAML changes and trigger compilation/upload
+- **REST API**: List devices, check health, and manage operations
+- **Docker Compose**: Easy deployment with ESPHome dashboard
+- **Debouncing**: Prevent duplicate operations from rapid file changes
+- **Thread-Safe**: Concurrent operation handling with locks
+
+## Quick Start
+
+### 1. Start the Services
+
+```bash
+cd esphome-webhook-service
+docker-compose up -d
+```
+
+This starts two services:
+- **ESPHome Dashboard**: `http://localhost:6052` (host network mode)
+- **Webhook Service**: `http://localhost:5000`
+
+### 2. Access the Services
+
+- ESPHome Dashboard: http://localhost:6052
+- Webhook API: http://localhost:5000/health
+
+### 3. Stop the Services
+
+```bash
+docker-compose down
+```
+
+## Environment Variables
+
+Configure the webhook service behavior in `docker-compose.yml`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ESPHOME_CONFIG_DIR` | `/config` | Directory containing device configs |
+| `AUTO_COMPILE` | `true` | Auto-compile on YAML file changes |
+| `AUTO_UPLOAD` | `false` | Auto-upload on YAML file changes (⚠️ use with caution) |
+| `DEBOUNCE_SECONDS` | `5` | Delay before triggering operations after file change |
+
+## API Endpoints
+
+### Health Check
+
+```bash
+curl http://localhost:5000/health
+```
+
+### List Devices
+
+```bash
+curl http://localhost:5000/devices
+```
+
+### Validate Configuration
+
+```bash
+curl -X POST http://localhost:5000/webhook/validate/ades-office-control-panel
+```
+
+### Compile Device
+
+```bash
+curl -X POST http://localhost:5000/webhook/compile/ades-office-control-panel
+```
+
+### Upload Device (OTA)
+
+```bash
+curl -X POST http://localhost:5000/webhook/upload/ades-office-control-panel
+```
+
+### Compile and Upload
+
+```bash
+curl -X POST http://localhost:5000/webhook/run/ades-office-control-panel
+```
+
+## File Watching
+
+The service automatically watches all YAML files in the config directory. When a `main.yaml` file is modified:
+
+1. **Auto-Compile Enabled**: Automatically compiles the device configuration
+2. **Auto-Upload Enabled**: Automatically uploads firmware to the device (OTA)
+
+**⚠️ WARNING**: Only enable `AUTO_UPLOAD=true` if you're confident in your changes and have physical access to devices in case of failures.
+
+## Integration Examples
+
+### GitHub Actions Webhook
+
+Trigger compilation after pushing changes:
+
+```yaml
+name: ESPHome Compile
+
+on:
+  push:
+    paths:
+      - '**/*.yaml'
+
+jobs:
+  compile:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Webhook
+        run: |
+          curl -X POST http://your-server:5000/webhook/compile/ades-office-control-panel
+```
+
+### Home Assistant Automation
+
+Create an automation to compile devices:
+
+```yaml
+automation:
+  - alias: "Compile ESPHome Device"
+    trigger:
+      platform: webhook
+      webhook_id: esphome_compile
+    action:
+      service: rest_command.compile_device
+      data:
+        device: "{{ trigger.data.device }}"
+
+rest_command:
+  compile_device:
+    url: "http://localhost:5000/webhook/compile/{{ device }}"
+    method: POST
+```
+
+## Directory Structure
+
+```
+esphome-webhook-service/
+├── app.py                  # Webhook service with file watching
+├── Dockerfile              # Container image definition
+├── requirements.txt        # Python dependencies
+├── docker-compose.yml      # Service orchestration
+├── README.md              # This file
+└── config/                 # Device configurations (mounted as /config)
+    ├── ades-office-control-panel/
+    │   └── main.yaml
+    ├── Old_Phone_Doorbell/
+    │   └── main.yaml
+    └── Oekoboiler/
+        └── main.yaml
+```
+
+## Troubleshooting
+
+### Service Won't Start
+
+Check logs:
+```bash
+docker-compose logs webhook
+docker-compose logs esphome
+```
+
+### Webhook Returns 404
+
+Ensure the device name matches the directory name:
+```bash
+curl http://localhost:5000/devices
+```
+
+### OTA Upload Fails
+
+1. Verify device is on the same network
+2. Check ESPHome logs: `docker-compose logs esphome`
+3. Ensure OTA password is correct in secrets.yaml
+4. Try using host network mode for webhook service (uncomment in docker-compose.yml)
+
+### File Watcher Not Triggering
+
+1. Check that `AUTO_COMPILE` is set to `true`
+2. Verify the file path is correct
+3. Check webhook logs for file change events
+4. Ensure Docker has permission to watch the mounted volume
+
+## Development
+
+### Run Locally (Without Docker)
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+pip install esphome
+
+# Set environment variables
+export ESPHOME_CONFIG_DIR=/path/to/esphome2/config
+export AUTO_COMPILE=true
+export AUTO_UPLOAD=false
+
+# Run the service
+python app.py
+```
+
+### Build Custom Image
+
+```bash
+docker build -t esphome-webhook:custom .
+```
+
+## Security Considerations
+
+- The webhook service has no authentication by default
+- Only expose port 5000 on trusted networks
+- Use a reverse proxy (nginx, Traefik) with authentication for external access
+- Keep `AUTO_UPLOAD=false` unless absolutely necessary
+- Review changes before enabling auto-upload
+
+## License
+
+Same as parent repository (see LICENSE file).