jessikitty/esp32-bluetooth-relay
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Home Assistant integration examples and configurations

Browse Source
This commit is contained in:
jessikitty
2025-12-15 16:13:09 +11:00
parent 8c33eac5cb
commit 2b9b071a91
1 changed files with 592 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

592
docs/HOME_ASSISTANT.md Normal file
View File

@@ -0,0 +1,592 @@
# 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