Control Sonoff Devices from Home Assistant

Home Assistant custom component for control Sonoff devices with eWeLink (original) firmware over LAN and/or Cloud.

[!CAUTION] Starting in 2026 - power, current, and voltage sensors will no longer be updated via the cloud connection. These updates placed a heavy load on the eWeLink cloud. As a result, they were blocked by the cloud.

<details> <summary><b>Table of Contents</b></summary>

Installation
Configuration
Posting new issues
Configuration UI
- Mode
- Debug page
- Homes
Configuration YAML
Sonoff Pow
Sonoff TH
Sonoff RF Bridge 433
Sonoff GK-200MP2-B Camera
Common problems in only LAN mode
Raw commands
Getting devicekey manually
Useful Links

</details>

A list of known devices can be found here - DEVICES.

Features

support new eWeLink API
support multiple eWeLink accounts and homes
can manage both local and cloud control at the same time!

Pros

work with original eWeLink / Sonoff firmware, no need to flash devices
work over Local Network and/or Cloud Server
work with devices without DIY-mode
work with devices in DIY-mode
support single and multi-channel devices
support TH and Pow device sensors
support Sonoff RF Bridge 433 for receive and send commands
instant device state update with local Multicast or cloud Websocket connection
load devices list from eWeLink Servers (with names and encryption keys) and save it locally
(optional) change device type from switch to light

Component review from DrZzs

Thanks to @beveradb and @mattsaxon for researching the local Sonoff protocol. Thanks to @michthom and @EpicLPer for researching the local Sonoff Camera protocol.

Installation

Via HACS or manually copy sonoff folder from latest release to custom_components folder in your config folder.

Configuration

Add integration via Home Assistant UI. You can setup multiple integrations with different ewelink accounts.

Posting new issues

Before posting new issue:

Check the number of online devices on the System Health page
Check warning and errors on the Logs page
Check debug logs on the Debug page (must be enabled in integration options)
Check open and closed issues
Share integration diagnostics:
- All devices: Settings > Integrations > Sonoff > 3 dots > Download diagnostics
- One device: Settings > Devices > Device > Download diagnostics

Configuration UI

Settings > Integrations > Sonoff > Configure (gear)

Mode

In auto mode component using both local and cloud connections to your devcies. If device could be reached via LAN - the local connection will be used. Otherwise the cloud connection will be used.

local mode or cloud mode will use only this type of connection.

Sometimes it can be difficult to get a local connection to work. You need a local network with working Multicast (mDNS/zeroconf) traffic between the Hass and your devices. Read about common problems.

Each time the integration starts, a list of user devices is loaded from cloud and saved locally (/config/.storage/sonoff/).

auto mode and local mode can work without Internet connection. If the integration fails to connect to the cloud - the component will use the previously saved list of devices and continue to work only in local mode. auto mode will continue trying to connect to the cloud.

local mode can't work without ewelink credentials because it needs devices encryption keys.

Devices in DIY mode can be used without ewelink credentials because their protocol unencrypted.

It is highly recommended that you use mode: auto and do not use mode: local or DIY mode. Because the local protocol is not always stable and you will get a bad experience. Devices may sometimes disappear from the network or fail to respond to local requests. Also some POW and TH devices cannot update their sensors without a cloud connection.

Debug page

Enable debug page in integration configuration (gear) via UI. Reload integrations page. Open: Integraion > Menu (top right dots) > Known issues.

Debug page shows only integration logs and removes some private data. You can filter log and enable auto refresh (in seconds).

http://192.168.1.123:8123/api/sonoff/c8503fee-88fb-4a18-84d9-abb782bf0aa7?q=1000xxxxxx&r=2

Homes

By default component loads cloud devices only for current active Home in ewelink application. If there is only one Home in the account, it shouldn't be a problem. Otherwise you can select one or multiple Homes to load devices from.

Configuration YAML

These settings are made via YAML.

Important. DeviceID is always 10 symbols string from entity_id or eWeLink app.

Custom device_class

You can convert all switches into light by default:

sonoff:
  default_class: light  # (optional), default switch

You can convert specific switches into light, fan or binary_sensor:

sonoff:
  devices:
    1000xxxxxx:
      device_class: light
      name: Sonoff Basic
    1000yyyyyy:
      device_class: fan
      name: Sonoff Mini

You can convert multi-channel devices (e.g. Sonoff T1 2C):

sonoff:
  devices:
    1000xxxxxx:
      device_class: [light, fan]
      name: Sonoff T1 2C
    1000yyyyyy:
      device_class: [switch, light]
      name: MiniTiger 2CH

You can convert multi-channel device (e.g. Sonoff T1 3C) into single light with brightness control:

sonoff:
  devices:
    1000xxxxxx:
      device_class:
        - light: [1, 2, 3]
      name: Sonoff T1 3C

You can control multiple light zones with single multi-channel device (e.g. Sonoff 4CH):

sonoff:
  devices:
    1000xxxxxx:
      device_class:
        - switch: 1  # entity 1 (channel 1)
        - light: [2, 3]  # entity 2 (channels 2 and 3)
        - fan: 4  # entity 3 (channel 4)
      name: Sonoff 4CH

You can change device_class for Binary Sensor:

sonoff:
  devices:
    1000xxxxxx:
      device_class: window

You can change device_class for Cover:

sonoff:
  devices:
    1000xxxxxx:
      device_class: shutter

You can set the uiid when running in DIY mode to enable the device features. More info here.

sonoff:
  devices:
    1000xxxxxx:
      extra: { uiid: 136 }  # Sonoff B05-BL

Custom devices

sonoff:
  devices:
    1000xxxxxx:
      name: Device name from YAML  # optional rewrite device name
      host: 192.168.1.123  # optional force device IP-address
      devicekey: xxx  # optional encription key (downloaded automatically from the cloud)

Custom sensors

If you want some additional device attributes as sensors:

sonoff:
  sensors: [staMac, bssid, host]

Force update

You can request actual device state and all its sensors manually at any time using homeassistant.update_entity service. Use it with any device entity except sensors. Use it with only one entity from each device.

As example, you can create an automation for forced temperature updates for Sonoff TH:

trigger:
  - platform: time_pattern
    minutes: '3'
action:
  - service: homeassistant.update_entity
    target:
      entity_id: switch.sonoff_1000xxxxxx

Preventing DB size growth

Pow devices may send a lot of data every second. You can reduce the amount of processed data.

For multi-channel devices use power_1, current_2, etc.

sonoff:
  devices:
    1000xxxxxx:
      reporting:
        power: [30, 3600, 1]  # min seconds, max seconds, min delta value
        current: [5, 3600, 0.1]
        voltage: [60, 360

SonoffLAN

Install / Use

README