# Home Assistant Integration Examples

Multiple ways to integrate your ESP32 Bluetooth Relay Controller with Home Assistant.

## Method 1: Bluetooth Serial (Recommended for Bluetooth-only)

### Prerequisites
- Home Assistant with Bluetooth adapter
- ESP32 within Bluetooth range
- `bluetooth_serial` integration

### Configuration

#### Step 1: Find ESP32 MAC Address

```bash
# On Linux/Raspberry Pi
hcitool scan
```

Look for: `ESP32-Relay-8CH` and note its MAC address (e.g., `30:AE:A4:XX:XX:XX`)

#### Step 2: Add to configuration.yaml

```yaml
# Bluetooth Serial Configuration
bluetooth_serial:
  - address: "30:AE:A4:XX:XX:XX"  # Replace with your ESP32 MAC
    name: "ESP32 Relay Controller"
    
# Switch Configuration
switch:
  # Relay 1
  - platform: template
    switches:
      relay_1:
        friendly_name: "Relay 1"
        value_template: "{{ is_state('input_boolean.relay_1_state', 'on') }}"
        turn_on:
          - service: bluetooth_serial.send
            data:
              address: "30:AE:A4:XX:XX:XX"
              message: "ON1\n"
          - service: input_boolean.turn_on
            target:
              entity_id: input_boolean.relay_1_state
        turn_off:
          - service: bluetooth_serial.send
            data:
              address: "30:AE:A4:XX:XX:XX"
              message: "OFF1\n"
          - service: input_boolean.turn_off
            target:
              entity_id: input_boolean.relay_1_state
              
  # Relay 2
  - platform: template
    switches:
      relay_2:
        friendly_name: "Relay 2"
        value_template: "{{ is_state('input_boolean.relay_2_state', 'on') }}"
        turn_on:
          - service: bluetooth_serial.send
            data:
              address: "30:AE:A4:XX:XX:XX"
              message: "ON2\n"
          - service: input_boolean.turn_on
            target:
              entity_id: input_boolean.relay_2_state
        turn_off:
          - service: bluetooth_serial.send
            data:
              address: "30:AE:A4:XX:XX:XX"
              message: "OFF2\n"
          - service: input_boolean.turn_off
            target:
              entity_id: input_boolean.relay_2_state

  # Repeat for Relay 3-8...
  # (See complete configuration below)

# Input Booleans for State Tracking
input_boolean:
  relay_1_state:
    name: Relay 1 State
    icon: mdi:toggle-switch
  relay_2_state:
    name: Relay 2 State
    icon: mdi:toggle-switch
  # ... relay_3_state through relay_8_state

# Scripts for Bulk Operations
script:
  all_relays_on:
    alias: "All Relays On"
    sequence:
      - service: bluetooth_serial.send
        data:
          address: "30:AE:A4:XX:XX:XX"
          message: "ALL_ON\n"
      - service: input_boolean.turn_on
        target:
          entity_id:
            - input_boolean.relay_1_state
            - input_boolean.relay_2_state
            - input_boolean.relay_3_state
            - input_boolean.relay_4_state
            - input_boolean.relay_5_state
            - input_boolean.relay_6_state
            - input_boolean.relay_7_state
            - input_boolean.relay_8_state
            
  all_relays_off:
    alias: "All Relays Off"
    sequence:
      - service: bluetooth_serial.send
        data:
          address: "30:AE:A4:XX:XX:XX"
          message: "ALL_OFF\n"
      - service: input_boolean.turn_off
        target:
          entity_id:
            - input_boolean.relay_1_state
            - input_boolean.relay_2_state
            - input_boolean.relay_3_state
            - input_boolean.relay_4_state
            - input_boolean.relay_5_state
            - input_boolean.relay_6_state
            - input_boolean.relay_7_state
            - input_boolean.relay_8_state
```

### Complete Switch Configuration (All 8 Relays)

Save this as `packages/esp32_relay.yaml`:

```yaml
# ESP32 Bluetooth Relay Package
# Place in config/packages/esp32_relay.yaml

# Bluetooth Serial Connection
bluetooth_serial:
  - address: "30:AE:A4:XX:XX:XX"  # CHANGE THIS
    name: "ESP32 Relay Controller"

# Input Booleans for State Tracking
input_boolean:
  relay_1_state:
    name: Relay 1 State
    icon: mdi:light-switch
  relay_2_state:
    name: Relay 2 State
    icon: mdi:light-switch
  relay_3_state:
    name: Relay 3 State
    icon: mdi:light-switch
  relay_4_state:
    name: Relay 4 State
    icon: mdi:light-switch
  relay_5_state:
    name: Relay 5 State
    icon: mdi:light-switch
  relay_6_state:
    name: Relay 6 State
    icon: mdi:light-switch
  relay_7_state:
    name: Relay 7 State
    icon: mdi:light-switch
  relay_8_state:
    name: Relay 8 State
    icon: mdi:light-switch

# Template Switches
switch:
  - platform: template
    switches:
      esp32_relay_1:
        friendly_name: "Living Room Light"
        value_template: "{{ is_state('input_boolean.relay_1_state', 'on') }}"
        turn_on:
          - service: bluetooth_serial.send
            data:
              address: "30:AE:A4:XX:XX:XX"
              message: "ON1\n"
          - service: input_boolean.turn_on
            target:
              entity_id: input_boolean.relay_1_state
        turn_off:
          - service: bluetooth_serial.send
            data:
              address: "30:AE:A4:XX:XX:XX"
              message: "OFF1\n"
          - service: input_boolean.turn_off
            target:
              entity_id: input_boolean.relay_1_state
        icon_template: >-
          {% if is_state('input_boolean.relay_1_state', 'on') %}
            mdi:lightbulb-on
          {% else %}
            mdi:lightbulb-off
          {% endif %}
          
      # Relays 2-8 (customize friendly_name as needed)
      esp32_relay_2:
        friendly_name: "Bedroom Light"
        # ... (same pattern as relay_1)
      esp32_relay_3:
        friendly_name: "Kitchen Light"
        # ... 
      esp32_relay_4:
        friendly_name: "Bathroom Fan"
        # ...
      esp32_relay_5:
        friendly_name: "Garden Lights"
        # ...
      esp32_relay_6:
        friendly_name: "Garage Door"
        # ...
      esp32_relay_7:
        friendly_name: "Workshop Power"
        # ...
      esp32_relay_8:
        friendly_name: "Security Lights"
        # ...

# Scripts for Convenience
script:
  esp32_all_on:
    alias: "All ESP32 Relays On"
    icon: mdi:power-plug
    sequence:
      - service: bluetooth_serial.send
        data:
          address: "30:AE:A4:XX:XX:XX"
          message: "ALL_ON\n"
      - delay: "00:00:01"
      - service: input_boolean.turn_on
        target:
          entity_id:
            - input_boolean.relay_1_state
            - input_boolean.relay_2_state
            - input_boolean.relay_3_state
            - input_boolean.relay_4_state
            - input_boolean.relay_5_state
            - input_boolean.relay_6_state
            - input_boolean.relay_7_state
            - input_boolean.relay_8_state
            
  esp32_all_off:
    alias: "All ESP32 Relays Off"
    icon: mdi:power-plug-off
    sequence:
      - service: bluetooth_serial.send
        data:
          address: "30:AE:A4:XX:XX:XX"
          message: "ALL_OFF\n"
      - delay: "00:00:01"
      - service: input_boolean.turn_off
        target:
          entity_id:
            - input_boolean.relay_1_state
            - input_boolean.relay_2_state
            - input_boolean.relay_3_state
            - input_boolean.relay_4_state
            - input_boolean.relay_5_state
            - input_boolean.relay_6_state
            - input_boolean.relay_7_state
            - input_boolean.relay_8_state
            
  esp32_refresh_status:
    alias: "Refresh ESP32 Status"
    icon: mdi:refresh
    sequence:
      - service: bluetooth_serial.send
        data:
          address: "30:AE:A4:XX:XX:XX"
          message: "STATUS\n"
```

---

## Method 2: ESPHome (Recommended for WiFi Integration)

For better Home Assistant integration, you can use ESPHome firmware instead.

### ESP32 ESPHome Configuration

Create `esp32-relay.yaml`:

```yaml
esphome:
  name: esp32-relay-controller
  platform: ESP32
  board: esp32dev

wifi:
  ssid: "YourSSID"
  password: "YourPassword"
  
  # Enable fallback hotspot
  ap:
    ssid: "ESP32-Relay Fallback"
    password: "fallbackpass"

# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
    key: "YOUR_ENCRYPTION_KEY"

ota:
  password: "YOUR_OTA_PASSWORD"

# Web server (optional)
web_server:
  port: 80

# 8 Relay Switches
switch:
  - platform: gpio
    pin: 13
    name: "Relay 1"
    id: relay_1
    icon: "mdi:electric-switch"
    restore_mode: RESTORE_DEFAULT_OFF
    
  - platform: gpio
    pin: 12
    name: "Relay 2"
    id: relay_2
    icon: "mdi:electric-switch"
    restore_mode: RESTORE_DEFAULT_OFF
    
  - platform: gpio
    pin: 14
    name: "Relay 3"
    id: relay_3
    icon: "mdi:electric-switch"
    restore_mode: RESTORE_DEFAULT_OFF
    
  - platform: gpio
    pin: 27
    name: "Relay 4"
    id: relay_4
    icon: "mdi:electric-switch"
    restore_mode: RESTORE_DEFAULT_OFF
    
  - platform: gpio
    pin: 26
    name: "Relay 5"
    id: relay_5
    icon: "mdi:electric-switch"
    restore_mode: RESTORE_DEFAULT_OFF
    
  - platform: gpio
    pin: 25
    name: "Relay 6"
    id: relay_6
    icon: "mdi:electric-switch"
    restore_mode: RESTORE_DEFAULT_OFF
    
  - platform: gpio
    pin: 33
    name: "Relay 7"
    id: relay_7
    icon: "mdi:electric-switch"
    restore_mode: RESTORE_DEFAULT_OFF
    
  - platform: gpio
    pin: 32
    name: "Relay 8"
    id: relay_8
    icon: "mdi:electric-switch"
    restore_mode: RESTORE_DEFAULT_OFF

# Template switches for "All On/Off"
  - platform: template
    name: "All Relays"
    icon: "mdi:toggle-switch-multiple"
    turn_on_action:
      - switch.turn_on: relay_1
      - switch.turn_on: relay_2
      - switch.turn_on: relay_3
      - switch.turn_on: relay_4
      - switch.turn_on: relay_5
      - switch.turn_on: relay_6
      - switch.turn_on: relay_7
      - switch.turn_on: relay_8
    turn_off_action:
      - switch.turn_off: relay_1
      - switch.turn_off: relay_2
      - switch.turn_off: relay_3
      - switch.turn_off: relay_4
      - switch.turn_off: relay_5
      - switch.turn_off: relay_6
      - switch.turn_off: relay_7
      - switch.turn_off: relay_8

# Status LED
status_led:
  pin:
    number: GPIO2
    inverted: false
```

### Installation

```bash
# Install ESPHome
pip install esphome

# Compile firmware
esphome compile esp32-relay.yaml

# Upload (first time via USB)
esphome upload esp32-relay.yaml

# Future updates can be done wirelessly (OTA)
```

---

## Method 3: Lovelace Dashboard Card

### Custom Entity Card

```yaml
type: entities
title: ESP32 Relay Controller
show_header_toggle: false
entities:
  - entity: switch.esp32_relay_1
    name: Living Room Light
    icon: mdi:lightbulb
  - entity: switch.esp32_relay_2
    name: Bedroom Light
    icon: mdi:lightbulb
  - entity: switch.esp32_relay_3
    name: Kitchen Light
    icon: mdi:lightbulb
  - entity: switch.esp32_relay_4
    name: Bathroom Fan
    icon: mdi:fan
  - entity: switch.esp32_relay_5
    name: Garden Lights
    icon: mdi:outdoor-lamp
  - entity: switch.esp32_relay_6
    name: Garage Door
    icon: mdi:garage
  - entity: switch.esp32_relay_7
    name: Workshop Power
    icon: mdi:power-socket
  - entity: switch.esp32_relay_8
    name: Security Lights
    icon: mdi:security
  - type: divider
  - entity: script.esp32_all_on
    name: Turn All On
  - entity: script.esp32_all_off
    name: Turn All Off
  - entity: script.esp32_refresh_status
    name: Refresh Status
```

### Button Card (requires custom:button-card)

```yaml
type: vertical-stack
cards:
  - type: custom:button-card
    entity: script.esp32_all_on
    name: All Relays ON
    icon: mdi:power-on
    color: green
    tap_action:
      action: call-service
      service: script.turn_on
      service_data:
        entity_id: script.esp32_all_on
        
  - type: horizontal-stack
    cards:
      - type: custom:button-card
        entity: switch.esp32_relay_1
        name: Relay 1
        
      - type: custom:button-card
        entity: switch.esp32_relay_2
        name: Relay 2
        
      - type: custom:button-card
        entity: switch.esp32_relay_3
        name: Relay 3
        
      - type: custom:button-card
        entity: switch.esp32_relay_4
        name: Relay 4
        
  - type: horizontal-stack
    cards:
      - type: custom:button-card
        entity: switch.esp32_relay_5
        name: Relay 5
        
      - type: custom:button-card
        entity: switch.esp32_relay_6
        name: Relay 6
        
      - type: custom:button-card
        entity: switch.esp32_relay_7
        name: Relay 7
        
      - type: custom:button-card
        entity: switch.esp32_relay_8
        name: Relay 8
        
  - type: custom:button-card
    entity: script.esp32_all_off
    name: All Relays OFF
    icon: mdi:power-off
    color: red
    tap_action:
      action: call-service
      service: script.turn_on
      service_data:
        entity_id: script.esp32_all_off
```

---

## Automations

### Turn on lights at sunset

```yaml
automation:
  - alias: "Garden Lights On at Sunset"
    trigger:
      - platform: sun
        event: sunset
        offset: "-00:30:00"
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.esp32_relay_5
```

### Turn off workshop after 2 hours

```yaml
automation:
  - alias: "Workshop Auto-Off"
    trigger:
      - platform: state
        entity_id: switch.esp32_relay_7
        to: 'on'
        for:
          hours: 2
    action:
      - service: switch.turn_off
        target:
          entity_id: switch.esp32_relay_7
      - service: notify.mobile_app
        data:
          message: "Workshop power automatically turned off after 2 hours"
```

---

## Troubleshooting

### Bluetooth connection drops
- Reduce distance between ESP32 and HA server
- Check for Bluetooth interference
- Restart Bluetooth service: `sudo systemctl restart bluetooth`

### State not updating
- Input booleans are for local state tracking only
- ESP32 doesn't report state changes back automatically
- Use `STATUS` command periodically via automation

### ESPHome compilation errors
- Ensure correct board type in YAML
- Check GPIO pin availability
- Verify ESPHome version compatibility

---

**Version:** 1.0  
**Last Updated:** December 2025