diff --git a/docs/HOME_ASSISTANT.md b/docs/HOME_ASSISTANT.md new file mode 100644 index 0000000..0d6f399 --- /dev/null +++ b/docs/HOME_ASSISTANT.md @@ -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