593 lines
14 KiB
Markdown
593 lines
14 KiB
Markdown
# 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
|