Using Sonoff with Home Assistant

Three approaches: eWeLink cloud (fastest), local LAN control (no internet), and ESPHome (power users). Includes examples and troubleshooting.

10–25 min (method dependent)
Works with Sonoff Basic, Mini, POW, S26, and many more
Secure setup tips included

Sonoff devices are affordable Wi-Fi smart switches and plugs. This guide shows three reliable ways to control them from Home Assistant (HA):

  • Method A — eWeLink Cloud: quickest to try; needs internet for control.
  • Method B — Local LAN: control over your home network; no cloud latency.
  • Method C — ESPHome: flash custom firmware for the most control and telemetry.
Tip: If you just want it working today, start with Method A. Later, move to Method B or C for local control and faster automations.
Contents
  1. What you’ll need
  2. Method A — eWeLink Cloud (fastest)
  3. Method B — Sonoff LAN (local)
  4. Method C — ESPHome (power users)
  5. Troubleshooting & FAQs
  6. Next steps

What you’ll need

  • Home Assistant (any install) on the same network as your Sonoff devices.
  • A working 2.4 GHz Wi-Fi network (most Sonoff products don’t support 5 GHz).
  • One or more Sonoff devices (Basic, Mini, POW, S26, etc.).
  • For Method C: a computer to flash firmware, and a USB-to-TTL adapter (for some models).

Method A — eWeLink Cloud (fastest)

Great for a quick demo or if you don’t want to modify anything. Requires internet.

  1. Pair Sonoff with eWeLink (the official app) and ensure you can toggle the device in the app.
  2. In Home Assistant, go to Settings → Devices & Services and click Add Integration. Search for eWeLink Smart Home (by CoolKit).
  3. Log in with the same eWeLink account. Your devices should appear in HA.
Note: Cloud control adds a small delay and depends on the eWeLink service. For faster, internet-free control, use Method B or C.

Method B — Local control via Sonoff LAN

This method keeps your automations local (no cloud). We’ll use the community Sonoff LAN custom integration.

Step 1 — Install HACS (if you don’t already use it)
  1. In HA, go to Settings → Add-ons → Add-on Store and install the Terminal & SSH add-on (optional but handy).
  2. Follow the official HACS install at hacs.xyz/docs/setup/download. After a restart you’ll see HACS in the sidebar.
Step 2 — Add Sonoff LAN
  1. Open HACS → Integrations, click Explore & Download and search for Sonoff LAN (by AlexxIT). Install and restart Home Assistant.
  2. Go to Settings → Devices & Services → Add Integration, search for Sonoff LAN, and enter your eWeLink credentials. The integration uses local protocol where possible.
Tip: Leave your devices in the eWeLink app for easy provisioning, but control them locally in HA.
Example: use a Sonoff switch in an automation
alias: Turn on geyser at 5am (weekdays)
trigger:
  - platform: time
    at: "05:00:00"
condition:
  - condition: time
    weekday:
      - mon
      - tue
      - wed
      - thu
      - fri
action:
  - service: switch.turn_on
    target:
      entity_id: switch.sonoff_geyser
mode: single

Method C — Flash ESPHome (power users)

ESPHome replaces the stock firmware. You gain rock-solid local control, telemetry, and full customization. On many models you can flash OTA (web-installer); others need a USB-to-TTL serial flash.

Step 1 — Create a new ESPHome device
  1. In HA, go to ESPHome and click New Device.
  2. Name it (e.g. sonoff_geyser) and select a supported board (often ESP8266 for older Sonoff or ESP32 for newer).
  3. Configure Wi-Fi credentials when prompted.
Step 2 — Use a minimal config (example for a relay + status LED)
esphome:
  name: sonoff_geyser

esp8266:
  board: esp01_1m

# Your Wi-Fi (2.4GHz)
wifi:
  ssid: "YOUR_WIFI"
  password: "YOUR_PASSWORD"
  ap:
    ssid: "sonoff-fallback"
    password: "fallback123"

logger:
api:
ota:

# GPIOs vary by model — check ESPHome device pages for your exact Sonoff model
switch:
  - platform: gpio
    name: "Geyser Relay"
    pin: GPIO12
    id: relay_1

status_led:
  pin:
    number: GPIO13
    inverted: true

After compiling and flashing, ESPHome will auto-discover in HA. Add it from Settings → Devices & Services.

Safety: Many Sonoff devices switch mains voltage. If you’re not sure about wiring, use a qualified electrician. Always isolate power before working on devices.

Troubleshooting & FAQs

Device not discovered in HA
  • Confirm 2.4 GHz Wi-Fi is enabled; some APs have band-steering issues.
  • Power-cycle the device and your router.
  • For LAN/ESPHome, ensure HA and device are on the same subnet/VLAN.
Slow control or delayed automations
  • Cloud method adds latency; prefer LAN or ESPHome for instant response.
  • Use a static DHCP lease so HA always finds the device quickly.
Which method should I choose?
  • Just starting: Method A (cloud) to test.
  • Daily driver: Method B (Sonoff LAN) for local, fast control.
  • Advanced: Method C (ESPHome) for maximum features & reliability.

Next steps

  • Create energy-saving schedules (e.g., pool pump or geyser) based on time-of-use tariffs.
  • Combine with presence or solar production sensors to automate intelligently.
  • Add a manual override button in your dashboard for quick control.
← Back to Guides

Build a smarter, more efficient home

Find compatible relays, sensors, and energy monitors on GreenGear.

Browse automation gear