English | Русский
An ESPHome external component that controls Tuya Wi-Fi plugs over the local network — no Tuya cloud, no Home Assistant in the control path.
A Tuya plug speaks a local TCP protocol on your network. Normally you let the Tuya cloud or a Home Assistant integration talk to it. This component lets an ESP32 do it directly: the ESP32 becomes the plug's controller, so the logic that owns the plug — a thermostat, a safety cut-off, an alarm — lives on the microcontroller and keeps working whether or not anything else is online.
The original use is a snail terrarium: an ESP32 reads temperatures and drives two Tuya plugs (heating mats and an IR heater). The plugs must never be left to the cloud, so the board owns them outright and Home Assistant only watches.
- The Tuya cloud puts your heating behind someone else's servers and an internet link.
- The
tuyaESPHome component talks to a Tuya MCU over a serial UART inside a flashed device — it does not reach a finished plug over Wi-Fi. - Home Assistant + a local Tuya integration works, but then Home Assistant is in the control path. If it is down, nothing turns the heater off.
A plug you can reach from your own ESP32, with no third party in the loop, closes that gap.
- Tuya local protocols 3.3, 3.4 and 3.5 — AES-ECB with CRC (3.3), session-key negotiation with HMAC-SHA256 (3.4), and AES-GCM framing (3.5).
switchplatform — turn a DP on and off. State is published only when the plug confirms it, never optimistically, so what you see is what the hardware is doing.sensorplatform — any numeric DP (current, power, voltage on a metering plug). Scale with the standard ESPHomefilters:.binary_sensorplatform — whether the plug is reachable, so you can alarm on losing control of the heater.- Non-blocking. All socket I/O runs in a dedicated FreeRTOS task with connect/receive timeouts, a command queue and automatic reconnect;
loop()is never blocked. - Works with the ESPHome
thermostat— the switch is a validheat_action. - Byte-exact protocol, cross-checked against tinytuya by a host test on every change.
- An ESP32 (developed on an ESP32-S3-DevKitC-1).
- ESPHome 2026.9 or newer. The ESP-IDF framework is the primary target; the Arduino framework is expected to work too.
- The plug's
device_idandlocal_key(see below).
Add the component straight from GitHub:
external_components:
- source:
type: git
url: https://github.com/orloffas/esphome-tuya-lan
components: [tuya_lan]Pin a release for reproducible builds by adding ref: v0.1.0 under source.
Declare one tuya_lan: hub per plug, then add platform entities that point at it with tuya_lan_id.
tuya_lan:
- id: mats
host: !secret mats_host
device_id: !secret mats_id
local_key: !secret mats_key
version: "3.5"
switch:
- platform: tuya_lan
name: "Mats power"
tuya_lan_id: mats
datapoint: 1
sensor:
- platform: tuya_lan
name: "Mats power draw"
tuya_lan_id: mats
datapoint: 19
unit_of_measurement: W
device_class: power
filters:
- multiply: 0.1 # raw DP is deciwatts
binary_sensor:
- platform: tuya_lan
name: "Mats online"
tuya_lan_id: mats| Option | Required | Default | Description |
|---|---|---|---|
host |
yes | — | IP address or hostname of the plug |
device_id |
yes | — | Tuya device id |
local_key |
yes | — | Tuya local key, exactly 16 characters |
version |
no | "3.3" |
Protocol version: "3.3", "3.4" or "3.5" |
port |
no | 6668 |
Tuya local TCP port |
poll_interval |
no | 15s |
How often the plug is polled for its state |
switch/sensorrequiretuya_lan_idanddatapoint(the DP number). All standard ESPHome options apply (filters,device_class,unit_of_measurement, …).binary_sensorrequires onlytuya_lan_id; it reports LAN reachability (device_class: connectivity).
A full two-plug example is in example/snails-plugs.yaml.
Naming tip for non-Latin configs. ESPHome derives an entity's object id by transliterating its
nameto ASCII. An all-Cyrillicnamecollapses to an empty id and collides with others (Both convert to ASCII ID). Give such entities anamewith some Latin characters, or an explicitid:.
The hub keeps re-asserting its last command until the plug confirms it, and does
so again after a reconnect. If another controller (for example Home Assistant)
should take a plug back, call the tuya_lan.release action so the board stops
re-asserting — otherwise a stale desired state could flip a plug the other
controller just changed. The switch keeps mirroring the plug's own reports.
# release one DP
- tuya_lan.release:
id: mats
datapoint: 1
# or release every DP of a hub
- tuya_lan.release: matsIn a lambda, id(mats).release_all() / id(mats).release_dp(1) do the same, and
id(mats).has_pending_writes() is true while a desired state is not yet confirmed.
These come from Tuya, not from the plug itself. The usual route is the tinytuya wizard (a free Tuya IoT developer account, then python -m tinytuya wizard). The DP numbers for a metering plug — current, power, voltage — are the ones its device model uses; 18, 19 and 20 are common, and the tuya-local device files are a good reference.
Keep these secret. Anyone with the local_key who can reach the plug can switch it. Put them in secrets.yaml (git-ignored) and reference them with !secret.
On connect, 3.4 and 3.5 devices negotiate a per-session key from a client and a device nonce (HMAC-SHA256, then an AES step). After that the component polls the plug on poll_interval, sends commands from a queue, and sends a heartbeat so the plug keeps the connection. Each decoded data-point update is handed to the main loop, which publishes it on the matching entity. For 3.5, every GCM nonce comes from the ESP32 hardware RNG.
The protocol codec is verified against tinytuya in CI, and the component has been run against these plugs on real hardware: it reads and decodes their status correctly, with current/power/voltage matching a reference client to the tenth, and stays stable over long read-only runs. Switching the plugs from the board has not yet been exercised live (that write path is host-tested but is the next on-device step), so hold that part as not-yet-field-proven.
| Plug | Protocol | Switch DP | Notes |
|---|---|---|---|
Metering smart plug (smartplugv2_energy) |
3.5 | 1 | current (DP 18), power (DP 19), voltage (DP 20) |
Smart plug with child lock (smartplugv2_childlock) |
3.3 | 1 | also reports energy (DP 18/19/20) |
The Tuya local protocol trusts a shared key. Protocol 3.3 authenticates frames
with a CRC only, so anyone on-path on your LAN can in principle replay or forge a
status frame and mislead the reported switch state; 3.4 and 3.5 bind each session
to a negotiated key, which blocks cross-session replay, though neither checks a
per-message sequence number within a session. Keep the plugs on a trusted network
and keep the local_key secret. This is a property of the protocol, not of this
implementation.
- ESP32 only — it relies on mbedtls and a FreeRTOS task.
- Boolean and integer data points are supported; string, enum and bitmap DPs are ignored for now.
- The Arduino framework is expected to work but has only been built on ESP-IDF so far.
The protocol is implemented from scratch against tinytuya (MIT) as the reference. Thanks to that project and to the people who documented the Tuya local protocol.
MIT. An unofficial Russian translation is in LICENSE.ru.md; only the English original is legally binding.
English | Русский
Внешний компонент ESPHome, который управляет Wi-Fi-розетками Tuya по локальной сети — без облака Tuya и без Home Assistant в цепочке управления.
Розетка Tuya говорит по локальному TCP-протоколу в вашей сети. Обычно с ней говорит облако Tuya или интеграция Home Assistant. Этот компонент даёт говорить с ней напрямую с ESP32: плата становится хозяином розетки, и логика, которая ей владеет, — термостат, аварийная отсечка, тревога — живёт на микроконтроллере и работает независимо от того, доступно ли что-то ещё.
Исходная задача — террариум улиток: ESP32 измеряет температуры и управляет двумя розетками Tuya (маты подогрева и ИК-обогреватель). Отдавать нагрев облаку нельзя, поэтому плата владеет розетками полностью, а Home Assistant только наблюдает.
- Облако Tuya уводит нагрев за чужие серверы и интернет-канал.
- Компонент
tuyaв ESPHome говорит с MCU Tuya по UART внутри прошиваемого устройства — до готовой розетки по Wi-Fi он не дотягивается. - Home Assistant с локальной интеграцией Tuya работает, но тогда HA стоит в цепочке управления. Если он лёг, нагрев никто не выключит.
Розетка, до которой ESP32 дотягивается сам, без посредников, закрывает этот разрыв.
- Локальные протоколы Tuya 3.3, 3.4 и 3.5 — AES-ECB с CRC (3.3), согласование сессионного ключа с HMAC-SHA256 (3.4) и кадры AES-GCM (3.5).
- Платформа
switch— включает и выключает DP. Состояние публикуется только после подтверждения розеткой, не оптимистично: на экране то, что делает железо. - Платформа
sensor— любой числовой DP (ток, мощность, напряжение у розетки с ваттметром). Масштаб задаётся штатнымиfilters:ESPHome. - Платформа
binary_sensor— на связи ли розетка, чтобы поднимать тревогу при потере управления нагревом. - Не блокирует. Весь обмен по сокету идёт в отдельной задаче FreeRTOS с таймаутами на подключение и приём, очередью команд и автопереподключением;
loop()не блокируется. - Работает с
thermostatESPHome — выключатель годится какheat_action. - Протокол точен до байта — на каждое изменение сверяется host-тестом с tinytuya.
- ESP32 (разработка на ESP32-S3-DevKitC-1).
- ESPHome 2026.9 или новее. Основная цель — фреймворк ESP-IDF; Arduino тоже должен работать.
device_idиlocal_keyрозетки (см. ниже).
Подключите компонент прямо с GitHub:
external_components:
- source:
type: git
url: https://github.com/orloffas/esphome-tuya-lan
components: [tuya_lan]Для воспроизводимых сборок зафиксируйте релиз, добавив ref: v0.1.0 под source.
Опишите по одному хабу tuya_lan: на розетку, затем добавьте сущности платформ, указывающие на него через tuya_lan_id.
tuya_lan:
- id: mats
host: !secret mats_host
device_id: !secret mats_id
local_key: !secret mats_key
version: "3.5"
switch:
- platform: tuya_lan
id: mats_power
name: "Маты, питание"
tuya_lan_id: mats
datapoint: 1
sensor:
- platform: tuya_lan
id: mats_power_draw
name: "Маты, мощность"
tuya_lan_id: mats
datapoint: 19
unit_of_measurement: W
device_class: power
filters:
- multiply: 0.1 # сырой DP — в дециваттах
binary_sensor:
- platform: tuya_lan
id: mats_online
name: "Маты на связи"
tuya_lan_id: mats| Параметр | Обязателен | По умолчанию | Описание |
|---|---|---|---|
host |
да | — | IP-адрес или имя хоста розетки |
device_id |
да | — | идентификатор устройства Tuya |
local_key |
да | — | локальный ключ Tuya, ровно 16 символов |
version |
нет | "3.3" |
версия протокола: "3.3", "3.4" или "3.5" |
port |
нет | 6668 |
локальный TCP-порт Tuya |
poll_interval |
нет | 15s |
как часто опрашивать состояние розетки |
switchиsensorтребуютtuya_lan_idиdatapoint(номер DP). Работают все штатные параметры ESPHome (filters,device_class,unit_of_measurement, …).binary_sensorтребует толькоtuya_lan_id; показывает доступность по сети (device_class: connectivity).
Полный пример на две розетки — в example/snails-plugs.yaml.
Про имена в нелатинских конфигах. ESPHome строит object id сущности, транслитерируя
nameв ASCII. Имя целиком из кириллицы схлопывается в пустой id и конфликтует с другими (Both convert to ASCII ID). Давайте таким сущностямnameхотя бы с латиницей или явныйid:.
Хаб переигрывает последнюю команду, пока розетка её не подтвердит, и повторяет это
после реконнекта. Если управление розеткой должен забрать другой контроллер
(например, Home Assistant), вызовите действие tuya_lan.release — тогда плата
перестанет досылать команду, иначе «тень» прежнего намерения может снова
переключить розетку, которую только что изменил другой контроллер. Выключатель
по-прежнему зеркалит отчёты самой розетки.
# отпустить один DP
- tuya_lan.release:
id: mats
datapoint: 1
# или отпустить все DP хаба
- tuya_lan.release: matsВ лямбде то же самое — id(mats).release_all() / id(mats).release_dp(1), а
id(mats).has_pending_writes() истинно, пока желаемое состояние не подтверждено.
Их выдаёт Tuya, а не сама розетка. Обычный путь — мастер tinytuya (бесплатный аккаунт разработчика Tuya IoT, затем python -m tinytuya wizard). Номера DP для розетки с ваттметром — ток, мощность, напряжение — те, что использует её модель; часто это 18, 19 и 20, а хороший справочник — файлы устройств tuya-local.
Держите эти значения в секрете. Кто знает local_key и достаёт розетку по сети — тот ею и управляет. Храните их в secrets.yaml (он в .gitignore) и подставляйте через !secret.
При подключении устройства 3.4 и 3.5 согласуют сессионный ключ из клиентского и серверного nonce (HMAC-SHA256, затем шаг AES). Дальше компонент опрашивает розетку по poll_interval, шлёт команды из очереди и heartbeat, чтобы розетка держала соединение. Каждое разобранное изменение DP передаётся в главный цикл, который публикует его на нужной сущности. Для 3.5 все GCM-nonce берутся из аппаратного генератора случайных чисел ESP32.
Кодек протокола сверяется с tinytuya в CI, и компонент прогнан с этими розетками на реальном железе: он корректно читает и декодирует их статус — ток, мощность и напряжение совпадают с эталонным клиентом до десятой, — и держится стабильно на долгих прогонах в режиме только чтения. Переключение розеток самой платой вживую ещё не гоняли (этот путь записи покрыт host-тестом, но это следующий шаг на железе), так что эту часть считайте пока не подтверждённой в поле.
| Розетка | Протокол | DP выключателя | Примечания |
|---|---|---|---|
Розетка с ваттметром (smartplugv2_energy) |
3.5 | 1 | ток (DP 18), мощность (DP 19), напряжение (DP 20) |
Розетка с защитой от детей (smartplugv2_childlock) |
3.3 | 1 | тоже отдаёт ваттметр (DP 18/19/20) |
Локальный протокол Tuya построен на общем ключе. Протокол 3.3 подтверждает кадры
только CRC, поэтому тот, кто сидит на пути в вашей локальной сети, в принципе может
переиграть или подделать кадр статуса и исказить показанное состояние выключателя;
3.4 и 3.5 привязывают каждую сессию к согласованному ключу, что перекрывает реплей
между сессиями, но порядковый номер внутри сессии ни один из них не проверяет.
Держите розетки в доверенной сети, а local_key — в секрете. Это свойство самого
протокола, а не этой реализации.
- Только ESP32 — нужны mbedtls и задача FreeRTOS.
- Поддержаны булевы и целочисленные DP; строковые, enum и битовые DP пока игнорируются.
- Фреймворк Arduino должен работать, но собиралось пока только на ESP-IDF.
Протокол написан с нуля, эталоном служит tinytuya (MIT). Спасибо этому проекту и всем, кто описал локальный протокол Tuya.
MIT. Неофициальный перевод на русский — в LICENSE.ru.md; юридическую силу имеет только английский оригинал.