Connecting with Home Assistant

Complete guide for integrating Wala Works devices with Home Assistant using the ESPHome ecosystem. This method provides the deepest integration with automatic device discovery and native Home Assistant entities.

Why ESPHome + Home Assistant?

MotorWala and RelayWala are built on ESPHome firmware, which integrates seamlessly with Home Assistant:

  • Native Integration: Devices appear as native Home Assistant entities
  • Real-time Updates: Instant state synchronization via Home Assistant API
  • Zero Configuration: Automatic discovery - just add the device
  • Full Control: All features accessible in Home Assistant UI
  • Visual Editor: Configure and update devices through ESPHome dashboard
  • OTA Updates: Update firmware over WiFi without cables

Prerequisites

What You Need

  1. Home Assistant - Running version 2023.1 or later

    • Installed on Raspberry Pi, NUC, or other hardware
    • Accessible on your local network
    • Installation guide

  2. ESPHome Add-on - Installed in Home Assistant

    • Available through Home Assistant Supervisor
    • Free and official add-on

  3. Wala Works Device - MotorWala or RelayWala

    • Already powered and physically wired
    • See Hardware Setup if not completed

  4. Network Access

    • Home Assistant and devices on same network
    • Or proper routing between VLANs

Installation Methods

There are two ways to connect devices to Home Assistant:

Method 1: Pre-flashed Devices (Recommended)

Best for: Devices purchased from Wala Works shop - they come pre-flashed and ready to use.

Steps:

  1. Power on device
  2. Connect to WiFi (via setup portal)
  3. Add to Home Assistant
  4. Start using immediately

Time required: 5-10 minutes

Method 2: Custom ESPHome Configuration

Best for: DIY builds or customizing device behavior.

Steps:

  1. Install ESPHome add-on
  2. Create/edit device configuration
  3. Flash device via USB or OTA
  4. Add to Home Assistant

Time required: 20-30 minutes (first time)

Method 1: Pre-flashed Devices

Step 1: Connect Device to WiFi

All Wala Works devices come pre-flashed with ESPHome firmware and will create a WiFi access point on first boot.

Initial Setup

  1. Power on your MotorWala or RelayWala device

  2. Watch the LED:

    • Rapid blinking (2-3 times/sec) = Setup mode
    • Slow blinking (once per second) = Connecting
    • Solid on = Connected

  3. Connect to device WiFi:

    • Network name: MotorWala-XXXX or RelayWala-XXXX
    • Password: setup12345 (default fallback AP)

  4. Configure network:

    • Browser should auto-open to http://192.168.4.1
    • If not, manually navigate to that address
    • Select your home WiFi network
    • Enter password
    • Click "Connect"

  5. Wait for connection:

    • Device will attempt to connect (10-30 seconds)
    • LED will change to slow blink, then solid
    • Device will reboot and join your network

Find Device IP Address

Option 1: Router Admin Panel

  • Log into your router
  • Check DHCP leases
  • Look for device name (e.g., "motorwala", "relaywala")

Option 2: Home Assistant Network Scan

  • Settings → System → Network
  • Scan for devices
  • Look for ESP32/ESP8266 devices

Option 3: mDNS Discovery

ping motorwala.local
# or
ping relaywala.local

Step 2: Install ESPHome Add-on

Install the official ESPHome add-on in Home Assistant:

  1. Open Add-on Store:

    • Navigate to: Settings → Add-ons → Add-on Store
    • Click "+ Add-on Store" in bottom right

  2. Search for ESPHome:

    • Type "ESPHome" in search box
    • Select "ESPHome" (official add-on)

  3. Install:

    • Click "Install"
    • Wait for installation (2-5 minutes)
    • Do not close browser during installation

  4. Configure ESPHome Add-on:

    network_mode: host
    • Leave other settings at defaults

  5. Start ESPHome:

    • Click "Start"
    • Enable "Start on boot"
    • Enable "Show in sidebar" for easy access

  6. Access ESPHome Dashboard:

    • Click "Open Web UI"
    • Or navigate to: http://homeassistant.local:6052

Step 3: Adopt Device in ESPHome

  1. Open ESPHome Dashboard:

    • Click "ESPHome" in Home Assistant sidebar
    • Or visit: Settings → Add-ons → ESPHome → "Open Web UI"

  2. Device Auto-Discovery:

    • ESPHome will automatically discover new devices on network
    • Look for banner: "New device discovered: motorwala.local"
    • Or device card with "Discovered" badge

  3. Adopt Device:

    • Click "Adopt" on discovered device
    • Or click "+ New Device" → "Continue" if not auto-discovered

  4. Device Configuration:

    ┌──────────────────────────────────┐
│  Adopt Device                    │
├──────────────────────────────────┤
│                                  │
│  Device Name:                    │
│  [Living Room Blinds          ]  │
│                                  │
│  Location (optional):            │
│  [Living Room                 ]  │
│                                  │
│  [ Skip ]  [ Adopt ]             │
└──────────────────────────────────┘

  5. Friendly Name:

    • Enter descriptive name (e.g., "Living Room Blinds")
    • This name will appear in Home Assistant
    • Click "Adopt"

  6. API Encryption Key:

    • ESPHome will generate encryption key automatically
    • Key is used for secure communication
    • Stored in device configuration

Step 4: Add to Home Assistant

Devices adopted in ESPHome automatically appear in Home Assistant:

  1. Automatic Discovery:

    • Navigate to: Settings → Devices & Services
    • Look for "Discovered" notification
    • Device name will appear (e.g., "Living Room Blinds")

  2. Add Integration:

    • Click "Configure" on discovered device
    • Or manually add: "+ Add Integration" → search "ESPHome"

  3. Connect:

    Host: motorwala.local (or IP address)
Port: 6053
    • Click "Submit"

  4. Encryption Key:

    • Enter API encryption key
    • Found in ESPHome dashboard → device configuration
    • Or auto-filled if adopted through ESPHome

  5. Finish Setup:

    • Device added successfully!
    • All entities now available in Home Assistant

Step 5: Verify Device Entities

Check that device entities are working:

MotorWala Entities

Navigate to device page: Settings → Devices & Services → ESPHome → [Your Device]

Entities you should see:

  • cover.living_room_blinds - Motor control (open/close/stop)
  • sensor.motor_position - Current position (0-100%)
  • sensor.motor_current - Motor current draw
  • binary_sensor.upper_limit - Upper limit switch
  • binary_sensor.lower_limit - Lower limit switch
  • button.calibrate - Run calibration routine
  • switch.motor_enable - Enable/disable motor

Test Control:

# Try opening via Developer Tools
service: cover.open_cover
target:
  entity_id: cover.living_room_blinds

RelayWala Entities

Entities you should see:

  • switch.relay_1 - Relay 1 control
  • switch.relay_2 - Relay 2 control
  • switch.relay_3 - Relay 3 control
  • switch.relay_4 - Relay 4 control
  • binary_sensor.emergency_stop - Emergency stop button
  • sensor.relay_1_status - Relay 1 state
  • sensor.uptime - Device uptime

Test Control:

# Try toggling via Developer Tools
service: switch.toggle
target:
  entity_id: switch.relay_1

Method 2: Custom ESPHome Configuration

For DIY builds or custom configurations.

Step 1: Prepare Configuration Files

Download the reference configurations from the Wala Works GitHub repository or create them manually.

MotorWala Configuration

Create motorwala.yaml in ESPHome dashboard:

esphome:
  name: living-room-blinds
  friendly_name: Living Room Blinds
  platform: ESP32
  board: esp32dev

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Fallback access point
  ap:
    ssid: "MotorWala Fallback"
    password: !secret ap_password

# Enable Home Assistant API
api:
  encryption:
    key: !secret api_encryption_key

ota:
  password: !secret ota_password

logger:
  level: INFO

# Motor driver outputs (L298N)
output:
  - platform: ledc
    pin: GPIO25
    id: motor_a_forward
    frequency: 1000 Hz

  - platform: ledc
    pin: GPIO26
    id: motor_a_backward
    frequency: 1000 Hz

# Cover entity for Home Assistant
cover:
  - platform: time_based
    name: "Motor Cover"
    id: motor_cover
    open_action:
      - output.set_level:
          id: motor_a_forward
          level: 100%
      - output.set_level:
          id: motor_a_backward
          level: 0%
    close_action:
      - output.set_level:
          id: motor_a_forward
          level: 0%
      - output.set_level:
          id: motor_a_backward
          level: 100%
    stop_action:
      - output.set_level:
          id: motor_a_forward
          level: 0%
      - output.set_level:
          id: motor_a_backward
          level: 0%
    open_duration: 30s
    close_duration: 30s

# Position limit switches
binary_sensor:
  - platform: gpio
    pin:
      number: GPIO32
      mode: INPUT_PULLUP
      inverted: true
    name: "Upper Limit"
    on_press:
      - cover.stop: motor_cover

  - platform: gpio
    pin:
      number: GPIO33
      mode: INPUT_PULLUP
      inverted: true
    name: "Lower Limit"
    on_press:
      - cover.stop: motor_cover

# Overcurrent protection
sensor:
  - platform: adc
    pin: GPIO34
    name: "Motor Current"
    update_interval: 100ms
    filters:
      - multiply: 3.3
    on_value_range:
      - above: 2.5
        then:
          - cover.stop: motor_cover
          - logger.log:
              format: "Overcurrent detected: %.2f A"
              args: ['x']
              level: WARN

RelayWala Configuration

Create relaywala.yaml:

esphome:
  name: living-room-relays
  friendly_name: Living Room Relays
  platform: ESP8266
  board: nodemcuv2

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Static IP for reliability
  manual_ip:
    static_ip: !secret static_ip
    gateway: !secret gateway
    subnet: 255.255.255.0
    dns1: !secret dns1

  ap:
    ssid: "RelayWala Fallback"
    password: !secret ap_password

api:
  encryption:
    key: !secret api_encryption_key

ota:
  password: !secret ota_password

logger:

# 4 relay switches
switch:
  - platform: gpio
    pin: GPIO16
    name: "Relay 1"
    id: relay_1
    restore_mode: RESTORE_DEFAULT_OFF
    icon: "mdi:lightbulb"

  - platform: gpio
    pin: GPIO14
    name: "Relay 2"
    id: relay_2
    restore_mode: RESTORE_DEFAULT_OFF
    icon: "mdi:fan"

  - platform: gpio
    pin: GPIO12
    name: "Relay 3"
    id: relay_3
    restore_mode: RESTORE_DEFAULT_OFF
    icon: "mdi:garage"
    on_turn_on:
      - delay: 1s
      - switch.turn_off: relay_3

  - platform: gpio
    pin: GPIO13
    name: "Relay 4"
    id: relay_4
    restore_mode: RESTORE_DEFAULT_OFF
    icon: "mdi:water-pump"
    on_turn_on:
      - delay: 300s
      - switch.turn_off: relay_4

# Emergency stop button
binary_sensor:
  - platform: gpio
    pin:
      number: GPIO5
      mode: INPUT_PULLUP
      inverted: true
    name: "Emergency Stop"
    on_press:
      then:
        - switch.turn_off: relay_1
        - switch.turn_off: relay_2
        - switch.turn_off: relay_3
        - switch.turn_off: relay_4

Secrets File

Create secrets.yaml:

# WiFi credentials
wifi_ssid: "YourNetworkName"
wifi_password: "YourWiFiPassword"

# Fallback AP
ap_password: "setup12345"

# API encryption (generate with: esphome random-key)
api_encryption_key: "YOUR_32_BYTE_BASE64_KEY_HERE="

# OTA password
ota_password: "yourSecureOTAPassword"

# Static IP (for RelayWala)
static_ip: "192.168.1.150"
gateway: "192.168.1.1"
dns1: "8.8.8.8"

Generate encryption key:

# In ESPHome add-on terminal
esphome random-key

Step 2: Flash Device

Option A: USB Flashing (First Time)

  1. Connect device via USB:

    • Use USB cable to connect ESP32/ESP8266 to computer
    • Or to Raspberry Pi running Home Assistant

  2. Install ESPHome Flasher (if not using Home Assistant):

    • Download from: https://github.com/esphome/esphome-flasher
    • Or use command line: pip install esphome

  3. Flash via ESPHome Dashboard:

    • Click device in ESPHome dashboard
    • Click "Install"
    • Select "Plug into this computer"
    • Choose serial port
    • Wait for flashing (2-5 minutes)

  4. Or flash via command line:

    esphome run motorwala.yaml

  5. Disconnect USB after successful flash

Option B: OTA Flashing (Subsequent Updates)

Once device is on network:

  1. Edit configuration in ESPHome dashboard
  2. Click "Install"
  3. Select "Wirelessly"
  4. Device updates over WiFi (1-2 minutes)

Step 3: Add to Home Assistant

Follow same process as Method 1, Step 4:

  • Devices auto-discovered in Home Assistant
  • Add ESPHome integration
  • Entities immediately available

Configuration and Customization

Rename Entities

Change entity names in Home Assistant:

  1. Navigate to entity: Settings → Devices & Services → ESPHome → [Device] → [Entity]
  2. Click entity name
  3. Settings gear icon
  4. Change "Name" and "Entity ID"
  5. Click "Update"

Example:

  • From: cover.living_room_blinds
  • To: cover.bedroom_curtains

Customize Entity Icons

# configuration.yaml
homeassistant:
  customize:
    cover.living_room_blinds:
      icon: mdi:blinds-horizontal
    switch.relay_1:
      icon: mdi:ceiling-light
    switch.relay_2:
      icon: mdi:fan

Group Related Entities

# configuration.yaml
group:
  living_room_automation:
    name: Living Room Automation
    entities:
      - cover.living_room_blinds
      - switch.living_room_light
      - switch.living_room_fan

Set Device Area

Assign devices to rooms/areas:

  1. Settings → Devices & Services → ESPHome → [Device]
  2. Click "No area assigned"
  3. Select or create area (e.g., "Living Room")
  4. All entities inherit area

Create Device Dashboard

Add controls to Home Assistant dashboard:

# Example Lovelace card
type: entities
title: Living Room
entities:
  - entity: cover.living_room_blinds
    name: Window Blinds
  - entity: switch.relay_1
    name: Ceiling Light
  - entity: switch.relay_2
    name: Ceiling Fan

Automations and Scenes

Example Automations

Close Blinds at Sunset

automation:
  - alias: "Close blinds at sunset"
    description: "Automatically close living room blinds when sun sets"
    trigger:
      - platform: sun
        event: sunset
        offset: "-00:30:00"  # 30 minutes before sunset
    action:
      - service: cover.close_cover
        target:
          entity_id: cover.living_room_blinds

Open Blinds in Morning

automation:
  - alias: "Open blinds in morning"
    description: "Open blinds at sunrise on weekdays"
    trigger:
      - platform: sun
        event: sunrise
        offset: "00:15:00"  # 15 minutes after sunrise
    condition:
      - condition: time
        weekday:
          - mon
          - tue
          - wed
          - thu
          - fri
    action:
      - service: cover.open_cover
        target:
          entity_id: cover.living_room_blinds

Turn Off All Relays at Night

automation:
  - alias: "Turn off all relays at bedtime"
    description: "Safety automation to turn off all relays at night"
    trigger:
      - platform: time
        at: "23:00:00"
    action:
      - service: switch.turn_off
        target:
          entity_id:
            - switch.relay_1
            - switch.relay_2
            - switch.relay_3
            - switch.relay_4

Emergency Stop Alert

automation:
  - alias: "Emergency stop pressed"
    description: "Send notification when emergency stop is pressed"
    trigger:
      - platform: state
        entity_id: binary_sensor.emergency_stop
        to: "on"
    action:
      - service: notify.mobile_app
        data:
          title: "Emergency Stop Activated"
          message: "Emergency stop button was pressed in living room"
          data:
            priority: high

Example Scenes

Morning Scene

scene:
  - name: Morning
    entities:
      cover.living_room_blinds:
        state: open
      switch.relay_1:  # Living room light
        state: off
      switch.relay_2:  # Kitchen light
        state: on

Evening Scene

scene:
  - name: Evening
    entities:
      cover.living_room_blinds:
        state: closed
      switch.relay_1:
        state: on
      switch.relay_2:
        state: on

Advanced Features

Voice Control

Google Assistant Integration

  1. Setup Google Assistant in Home Assistant:

    • Settings → Devices & Services → Add Integration → Google Assistant
    • Follow setup wizard

  2. Expose entities:

    # configuration.yaml
google_assistant:
  project_id: your-project-id
  service_account: !include SERVICE_ACCOUNT.json
  exposed_domains:
    - cover
    - switch

  3. Voice commands:

    • "Hey Google, open the living room blinds"
    • "Hey Google, turn on the living room light"
    • "Hey Google, set blinds to 50 percent"

Amazon Alexa Integration

  1. Setup Alexa in Home Assistant:

    • Requires Home Assistant Cloud or manual skill setup
    • Settings → Home Assistant Cloud → Alexa

  2. Discover devices:

    • Open Alexa app
    • Devices → Add Device → Other
    • "Discover devices"

  3. Voice commands:

    • "Alexa, open the living room blinds"
    • "Alexa, turn on relay 1"

Remote Access

Enable secure remote access to control devices from anywhere:

  1. Home Assistant Cloud (easiest):

    • Settings → Home Assistant Cloud
    • Subscribe ($65/year)
    • Instant remote access + voice assistants

  2. Nabu Casa Tunnel (free alternative):

    • Settings → Add-ons → Install "Duck DNS" add-on
    • Configure dynamic DNS
    • Setup SSL certificates
    • Port forward router (443)

Monitoring and Notifications

Motor Current Monitoring

Create alert for unusual current draw:

automation:
  - alias: "Motor overcurrent alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.motor_current
        above: 2.0
        for:
          seconds: 5
    action:
      - service: notify.notify
        data:
          title: "Motor Alert"
          message: "Motor current is high: {{ states('sensor.motor_current') }}A"

Device Offline Alerts

automation:
  - alias: "Device offline alert"
    trigger:
      - platform: state
        entity_id: binary_sensor.living_room_blinds_status
        to: "unavailable"
        for:
          minutes: 5
    action:
      - service: notify.notify
        data:
          message: "Living room blinds device is offline"

Debugging and Logs

View Device Logs

  1. ESPHome Dashboard:

    • Click device
    • Click "Logs"
    • Real-time log streaming

  2. Home Assistant Logs:

    • Settings → System → Logs
    • Filter by "esphome"

Enable Debug Logging

Add to device configuration:

logger:
  level: DEBUG
  logs:
    sensor: DEBUG
    binary_sensor: DEBUG
    cover: DEBUG

Firmware Updates

OTA Updates via ESPHome

Update device firmware wirelessly:

  1. Edit configuration in ESPHome dashboard
  2. Save changes
  3. Click "Install" → "Wirelessly"
  4. Device updates in 1-2 minutes
  5. Automatically reconnects to Home Assistant

Update ESPHome Add-on

Keep ESPHome add-on updated:

  1. Settings → Add-ons → ESPHome
  2. Click "Update" if available
  3. Restart add-on after update

Backup Before Updating

Always backup configuration:

  1. ESPHome configs:

    • ESPHome dashboard → Download all configs
    • Or backup /config/esphome/ folder

  2. Home Assistant:

    • Settings → System → Backups
    • Create full backup before major changes

Troubleshooting

Device Not Discovered

Symptoms: ESPHome doesn't find device on network

Solutions:

  1. Verify device connected to WiFi (LED solid, not blinking)
  2. Check device and Home Assistant on same network/VLAN
  3. Try manually adding:
    • ESPHome dashboard → "+ Add Device" → use IP address
  4. Restart ESPHome add-on
  5. Check mDNS working: ping motorwala.local

API Connection Failed

Symptoms: Home Assistant can't connect to device API

Solutions:

  1. Check encryption key matches in both:
    • ESPHome configuration (api_encryption_key)
    • Home Assistant integration settings
  2. Verify port 6053 not blocked by firewall
  3. Try IP address instead of hostname
  4. Reboot device via ESPHome dashboard
  5. Check logs for authentication errors

Entities Not Showing

Symptoms: Device connected but entities missing in Home Assistant

Solutions:

  1. Refresh entity list:
    • Settings → Devices & Services → ESPHome → Device → "⋮" → "Reload"
  2. Check entity disabled:
    • Device page → "X entities not shown"
    • Enable entities if disabled
  3. Restart Home Assistant Core:
    • Developer Tools → Restart → "Quick reload"
  4. Check ESPHome logs for compile errors

Motor Not Moving

Symptoms: Cover entity shows in Home Assistant but motor doesn't move

Solutions:

  1. Verify hardware wired correctly (see Hardware Setup)
  2. Check power supply adequate (12-24V, 2A+)
  3. Test motor manually (connect directly to power)
  4. View live logs in ESPHome dashboard
  5. Check for overcurrent protection triggering
  6. Verify limit switches not stuck in activated state

Relays Not Switching

Symptoms: Switch entity toggles in Home Assistant but relay doesn't click

Solutions:

  1. Check relay board power (12V supply)
  2. Verify GPIO pins correct in configuration
  3. Test relay board with multimeter
  4. Check status LED on relay board
  5. Ensure relay board compatible (active-high vs active-low)
  6. Review logs for error messages

WiFi Connection Drops

Symptoms: Device frequently goes offline

Solutions:

  1. Check signal strength: 
    sensor:
  - platform: wifi_signal
    name: "WiFi Signal"
    update_interval: 60s
  2. Use static IP instead of DHCP
  3. Disable power saving: 
    wifi:
  power_save_mode: none
  4. Add reboot action on disconnect: 
    wifi:
  on_disconnect:
    - delay: 5min
    - lambda: |-
        ESP.restart();
  5. Move device closer to WiFi access point
  6. Use WiFi extender or mesh network

OTA Update Fails

Symptoms: Can't update firmware wirelessly

Solutions:

  1. Verify OTA password correct in secrets.yaml
  2. Check device has stable WiFi connection
  3. Ensure enough free memory (check logs)
  4. Try USB flashing if OTA repeatedly fails
  5. Break up large config changes into smaller updates
  6. Temporarily increase OTA timeout: 
    ota:
  safe_mode: true

Best Practices

Security

  1. Change default passwords in secrets.yaml:

    • Use strong, unique passwords
    • Store secrets.yaml securely
    • Never commit secrets to git

  2. Enable API encryption:

    • Always use api.encryption.key
    • Generate new key for each device
    • Store keys in password manager

  3. Use static IPs for critical devices:

    • Makes firewall rules easier
    • More reliable than mDNS
    • Set via DHCP reservation or device config

  4. Isolate IoT devices:

    • Use separate VLAN for automation devices
    • Firewall rules to limit access
    • Only allow Home Assistant to communicate

Maintenance

  1. Regular backups:

    • Weekly Home Assistant backups
    • Store off-site (cloud storage)
    • Test restore procedure

  2. Update firmware:

    • Check for ESPHome updates monthly
    • Read release notes before updating
    • Update one device first, test, then roll out

  3. Monitor device health:

    • Add uptime sensors
    • Check WiFi signal strength
    • Alert on device offline > 5 minutes

  4. Document configuration:

    • Comment YAML files
    • Keep wiring diagrams
    • Note customizations made

Performance

  1. Optimize polling:

    • Don't poll sensors too frequently
    • Use update_interval appropriately
    • Fast changing: 100-500ms
    • Slow changing: 30-60s

  2. Reduce logging:

    • Production: logger: level: INFO
    • Only use DEBUG when troubleshooting
    • Excessive logging impacts performance

  3. Network optimization:

    • Use 2.4GHz WiFi (better range)
    • 5GHz only for high-bandwidth needs
    • Good WiFi coverage essential

Next Steps

Now that your devices are integrated with Home Assistant:

Questions? Visit the FAQ or contact support

Previous

—

Next

—