# Olimex ESP32-C6-EVB Home Assistant Integration Setup Guide

## Overview

This Home Assistant integration automatically manages the Olimex ESP32-C6-EVB board configuration through the UI.

## Features

- **Binary Sensors** - Monitor 4 digital inputs (DIN1-DIN4)
- **Template Switches** - Control 4 relays (REL1-REL4)
- **Auto-discovery** - Configurable via config flow UI (no YAML required)
- **Connection validation** - Verifies board is online before saving config

## Installation

### 1. Deploy Arduino Firmware

First, ensure your board is running the updated Arduino firmware with all 4 relays and inputs configured:

- Deploy: `/srv/homeassist/esp32_arduino/esp32_arduino.ino`
- Board: Olimex ESP32-C6-EVB
- Firmware includes:
  - Static IP: `192.168.0.181`
  - 4 Relays (GPIO 10, 11, 22, 23)
  - 4 Inputs (GPIO 1, 2, 3, 15) with pull-ups

### 2. Setup Integration via Home Assistant UI

1. Go to **Settings** → **Devices & Services**
2. Click **Create Integration** (+ button)
3. Search for **"Olimex"**
4. Click **Olimex ESP32-C6-EVB**
5. Enter configuration:
   - **Device IP Address**: `192.168.0.181` (default)
   - **Port**: `80` (default)
   - **Scan Interval**: `5` seconds (default)
6. Click **Submit**

The integration will:
- ✅ Verify connection to the board
- ✅ Create 4 binary sensors for inputs
- ✅ Set up the data coordinator for relay polling

### 3. Create Template Switches (Manual for now)

For now, you still need to add this to your `configuration.yaml`:

```yaml
template:
  - switch:
      - name: "Relay 1"
        unique_id: "olimex_relay_1"
        state: "{{ state_attr('sensor.relay_1_status', 'state') | default('off') }}"
        turn_on:
          service: rest_command.relay_1_on
        turn_off:
          service: rest_command.relay_1_off

      - name: "Relay 2"
        unique_id: "olimex_relay_2"
        state: "{{ state_attr('sensor.relay_2_status', 'state') | default('off') }}"
        turn_on:
          service: rest_command.relay_2_on
        turn_off:
          service: rest_command.relay_2_off

      - name: "Relay 3"
        unique_id: "olimex_relay_3"
        state: "{{ state_attr('sensor.relay_3_status', 'state') | default('off') }}"
        turn_on:
          service: rest_command.relay_3_on
        turn_off:
          service: rest_command.relay_3_off

      - name: "Relay 4"
        unique_id: "olimex_relay_4"
        state: "{{ state_attr('sensor.relay_4_status', 'state') | default('off') }}"
        turn_on:
          service: rest_command.relay_4_on
        turn_off:
          service: rest_command.relay_4_off

sensor:
  - platform: rest
    name: "Relay 1 Status"
    unique_id: "sensor_relay_1_status"
    resource: "http://192.168.0.181/relay/status?relay=1"
    value_template: "{{ value_json.state }}"
    scan_interval: 5

  - platform: rest
    name: "Relay 2 Status"
    unique_id: "sensor_relay_2_status"
    resource: "http://192.168.0.181/relay/status?relay=2"
    value_template: "{{ value_json.state }}"
    scan_interval: 5

  - platform: rest
    name: "Relay 3 Status"
    unique_id: "sensor_relay_3_status"
    resource: "http://192.168.0.181/relay/status?relay=3"
    value_template: "{{ value_json.state }}"
    scan_interval: 5

  - platform: rest
    name: "Relay 4 Status"
    unique_id: "sensor_relay_4_status"
    resource: "http://192.168.0.181/relay/status?relay=4"
    value_template: "{{ value_json.state }}"
    scan_interval: 5

rest_command:
  relay_1_on:
    url: "http://192.168.0.181/relay/on?relay=1"
    method: POST
  relay_1_off:
    url: "http://192.168.0.181/relay/off?relay=1"
    method: POST
  relay_2_on:
    url: "http://192.168.0.181/relay/on?relay=2"
    method: POST
  relay_2_off:
    url: "http://192.168.0.181/relay/off?relay=2"
    method: POST
  relay_3_on:
    url: "http://192.168.0.181/relay/on?relay=3"
    method: POST
  relay_3_off:
    url: "http://192.168.0.181/relay/off?relay=3"
    method: POST
  relay_4_on:
    url: "http://192.168.0.181/relay/on?relay=4"
    method: POST
  relay_4_off:
    url: "http://192.168.0.181/relay/off?relay=4"
    method: POST
```

Then restart Home Assistant.

## API Endpoints

The board provides these REST API endpoints:

### Relay Control
- `POST /relay/on?relay=1-4` - Turn relay on
- `POST /relay/off?relay=1-4` - Turn relay off
- `GET /relay/status?relay=1-4` - Get relay state (returns `{"state": true/false}`)

### Input Reading
- `GET /input/status?input=1-4` - Read input state (returns `{"state": true/false}`)

### Device Status
- `GET /api/status` - Get overall device status

## Entities Created

### Binary Sensors (Inputs)
- `binary_sensor.input_1` - Digital Input 1 (GPIO 1)
- `binary_sensor.input_2` - Digital Input 2 (GPIO 2)
- `binary_sensor.input_3` - Digital Input 3 (GPIO 3)
- `binary_sensor.input_4` - Digital Input 4 (GPIO 15)

### Switches (Relays) - via template
- `switch.relay_1` - Relay 1 (GPIO 10)
- `switch.relay_2` - Relay 2 (GPIO 11)
- `switch.relay_3` - Relay 3 (GPIO 22)
- `switch.relay_4` - Relay 4 (GPIO 23)

### Sensors (Status)
- `sensor.relay_1_status` - Relay 1 state polling
- `sensor.relay_2_status` - Relay 2 state polling
- `sensor.relay_3_status` - Relay 3 state polling
- `sensor.relay_4_status` - Relay 4 state polling

## Troubleshooting

### Integration won't add
- Check board IP is correct (default: `192.168.0.181`)
- Verify board is online and connected to WiFi
- Check Home Assistant logs: `Settings > System > Logs`

### Inputs not showing
- Verify Arduino firmware is deployed
- Check GPIO pin configuration matches board
- Inputs show as binary_sensor entities after integration setup

### Relays not working
- Ensure relay REST sensors are created in configuration.yaml
- Verify REST commands point to correct IP/port
- Check board serial output for API activity

### Slow response time
- Increase scan interval (default is 5 seconds)
- Can be changed in integration options

## Future Enhancements

- [ ] Auto-create relay switches without YAML
- [ ] Add sensor polling via coordinator
- [ ] Support multiple boards
- [ ] Device discovery (mDNS when available)
- [ ] Web UI for board settings