SonoffLAN: a Home Assistant component whose own docs contradict each other on sensors

The cloud block and the mode advice disagree about the same sensors

A caution block near the top states that starting in 2026 the power, current and voltage sensors will no longer be updated over the cloud connection, and gives the reason: those updates placed a heavy load on the eWeLink cloud and were blocked by it. Further down, the mode section advises using `auto` and says that some POW and TH devices cannot update their sensors without a cloud connection. Those two statements cannot both describe the same data path in 2026. If the cloud is refusing power, current and voltage updates, then the fallback the page offers for those sensors is the path that no longer delivers them. The same tension runs through the feature list, which still advertises support for TH and Pow device sensors without qualifying where the values come from. Nothing on the page states which sensor entities still update over LAN and which are now permanently stale, so the honest reading is that any history built from them will simply stop growing.

Local mode needs cloud credentials, and DIY mode needs none

The credential requirements invert between the two local paths, and the page is explicit about why. `local` mode cannot work without eWeLink credentials, because the LAN protocol needs each device's encryption key, and those keys come from the cloud. `auto` and `local` can both work with no Internet connection: on a cloud failure the component falls back on the previously saved device list and carries on in local mode, and `auto` keeps retrying the cloud in the background. Devices in DIY mode can be used without credentials at all, because their protocol is unencrypted. That is the security shape of this component in one paragraph. The path with the best privacy properties for your account is the one the page tells you not to use, since it recommends `auto` and warns that the local protocol is not always stable, with devices sometimes disappearing or failing to answer. An unencrypted LAN protocol is also an unencrypted LAN protocol, on a network anyone on the same segment can watch.

The device cache with encryption keys is written into the config directory

Each time the integration starts it loads your device list from the cloud and saves it locally, and the location given is `/config/.storage/sonoff/`. What that list contains is stated in the feature list: names and encryption keys. So the account's device inventory, including the per-device keys the LAN protocol needs, is persisted on the Home Assistant host as a side effect of running the integration. Anyone with filesystem access to that host, or with a backup of the config directory, now holds the material needed to talk to those devices directly. The page does not describe the file format, any encryption of the cache at rest, or a retention policy for it. It does tell you to share diagnostics when opening an issue, through the Download diagnostics action on the integration or on a single device, which is worth weighing against the fact that this cache exists in the first place.

The debug page link is printed into the Home Assistant log

The debug page is enabled from the gear icon in the integration options, and once enabled a link to it appears in a Home Assistant notification and in the Home Assistant log. The page shows integration logs only and removes some private data, and you can filter the log and set an auto refresh interval in seconds. The shape of the URL is the interesting part:

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

The path segment is a random identifier, and the page states that it is always random and updated every time Home Assistant restarts. That is a reasonable design, and it still means the access token lives in the log file, which is a place with broader readership than the user interface: it is attached to diagnostics downloads, it is pasted into issue threads, and it survives in log archives. A leaked link is only valid until the next restart, but between restarts it is the thing standing between a stranger on your network and your integration's logs.

auto prefers the LAN and falls back to the cloud, which it can no longer fully query

The mode setting has three values and the default is the sensible one. In `auto` the component holds both a local and a cloud connection and uses the local one whenever the device answers over LAN, dropping to the cloud otherwise. `local` and `cloud` force a single path, and getting the local path to work depends on multicast traffic, mDNS or zeroconf, actually flowing between Home Assistant and the devices; there is a section on the common LAN-only problems for exactly that. The fallback is graceful but has an expiry condition nobody controls. The saved device list is refreshed from the cloud at startup, and if the cloud is unreachable the component reuses the previous list. That is how `local` keeps working offline, and it is also why a device added to your eWeLink account while the integration was offline will not appear until a successful startup. Homes behave the same way: by default only the currently active home in the eWeLink app is loaded, with the option to select one or several.

Device identifiers are ten characters that you type by hand

The YAML configuration is keyed by device identifier, and the page states the shape of that identifier up front: it is always a ten symbol string taken from the entity id or from the eWeLink app. That is what the `1000xxxxxx` and `1000yyyyyy` placeholders in every example are standing in for. The most-used switch is cosmetic: `default_class: light` converts every switch into a light entity, since the default is `switch`, and individual devices can be overridden to `light`, `fan` or `binary_sensor` with a name:

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

Other keys follow the same pattern, with sections for custom devices, custom sensors, force update, and a documented option for preventing database size growth, which matters for an integration that logs device state into Home Assistant's recorder.

Two protocols were reverse engineered by other people, and the page cites them

The local control this component depends on is not an API the vendor published. The credits name two pairs of contributors, one pair for researching the local Sonoff protocol and another for the local Sonoff camera protocol, plus a separate component review. That is the honest shape of the project: the LAN path is a reimplementation, and the acknowledgement section is where you learn that. The device-specific sections that follow lean on it, covering Sonoff Pow, Sonoff TH, the RF Bridge 433 for both receiving and sending commands, and the GK-200MP2-B camera, along with a section for raw commands and a separate one for retrieving a device key by hand when the automatic path fails. The tree holds a `DEVICES.md` as the list of known devices, `hacs.json` for HACS metadata, and a `tests/` directory alongside the `custom_components/` source.

Issue reports are expected to arrive with diagnostics already attached

The support process is a five step checklist that runs before an issue is posted. Check the number of online devices on the Home Assistant System Health page. Check warnings and errors on the Logs page. Check debug logs on the component's own debug page, which has to be enabled in the integration options first. Check both open and closed issues, since the search link is pre-filtered to include closed ones. Then share diagnostics, either for all devices through the integration's three dot menu or for a single device through the device page. That ordering tells you what the maintainer considers diagnostic: not the symptom, but the count of devices that are online, the warnings, and a filtered component log. It also means the debug page is not a convenience feature but part of the support contract, which is a good reason to think about who can read the log before turning it on.

Editorial conclusion

This component fits someone who owns Sonoff hardware on stock firmware and wants it in Home Assistant without reflashing anything, and who will leave the mode on auto. Four things to check before you rely on it. The cloud stopped carrying power, current and voltage readings in 2026 because they were loading it, so any dashboard built on those sensors needs a plan that does not assume the cloud. Local mode needs your eWeLink credentials anyway, because the LAN protocol is encrypted with keys the cloud hands out, and DIY mode needs none because that protocol is unencrypted. The device cache including those encryption keys is written into the Home Assistant storage directory. And the debug page link is printed into the Home Assistant log with a fresh random identifier on every restart, so treat log access as debug page access.

Frequently asked questions

Official sources

1. AlexxIT/SonoffLAN on GitHub
2. Issues
3. License: MIT
4. README
5. Releases