ESP-Home-Git-Synchroniser/README.md

# 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).