TinyTuya

Sobre

TinyTuya é um módulo Python (com CLI) para ler o estado e controlar dispositivos Tuya (tomadas, interruptores, lâmpadas, cortinas etc.), de forma local (LAN) ou via Tuya IoT Cloud. Substitui o pacote pytuya e suporta os protocolos Tuya 3.1 a 3.5.

• Repositório: https://github.com/jasonacox/tinytuya

Funcionamento

• Local: fala direto com o dispositivo na LAN usando Device ID, IP, Local_Key e versão do protocolo. Descoberta via UDP (6666, 6667, 7000) e comunicação via TCP 6668.
• Nuvem: usa a API Tuya IoT Cloud (API ID, Secret e região) pela classe Cloud.
• Wizard (python -m tinytuya wizard): obtém as Local_Key de todos os dispositivos pela nuvem e gera devices.json, tuya-raw.json e snapshot.json. Exige projeto na plataforma Tuya, conta do app Smart Life vinculada e o serviço IoT Core (trial gratuito, renovável).
• Scan (python -m tinytuya scan): lista IP, ID e versão dos dispositivos encontrados na rede.

Principais Recursos

• Classes Device, OutletDevice, BulbDevice e CoverDevice.
• Cloud para consultar/enviar comandos e baixar logs.
• Monitor (experimental) para acompanhar vários dispositivos com callbacks e reconexão.
• Mapeamento de Data Points (DPS) e módulos da comunidade (tinytuya.Contrib).
• Suporte a sub-dispositivos de gateways (cid, node_id, parent, subdev_query()).

import tinytuya
 
d = tinytuya.OutletDevice("DEVICE_ID", "IP_ADDRESS", "LOCAL_KEY")
d.set_version(3.4)
print(d.status())
d.turn_on()

Ligação com Zigbee

O TinyTuya é centrado em Wi-Fi/LAN. A documentação não declara suporte direto a Zigbee (Zigbee só aparece como link para a doc do Zigbee2MQTT, para descobrir Data Points). A relação é indireta:

1. Gateway Zigbee Tuya (caminho via TinyTuya)

• O gateway/hub Zigbee Tuya é, ele mesmo, um dispositivo Tuya na rede (Wi-Fi/Ethernet); os sensores e interruptores Zigbee são sub-dispositivos dele.
• O construtor de Device aceita cid/node_id (ID do sub-dispositivo) e parent (objeto do gateway), e subdev_query() consulta o estado dos filhos (só para gateways).
• Fluxo esperado: conectar ao gateway (IP + Local_Key) e endereçar cada filho pelo cid. Na nuvem, os filhos também aparecem como dispositivos normais da conta.
• Os Data Points de cada sub-dispositivo precisam ser descobertos (estado/comandos são DPS numéricos); o mapeamento do Zigbee2MQTT ajuda a entendê-los.

2. Zigbee sem nuvem Tuya (alternativas ao TinyTuya)

Abordagem	Quando usar
Zigbee2MQTT / ZHA (Home Assistant) + dongle coordenador	Controlar dispositivos Zigbee diretamente, sem gateway Tuya nem nuvem
TinyTuya + gateway Tuya	Já tem gateway Tuya e quer automatizar em Python/local
ESP32-C6 / C5 (rádio 802.15.4)	Construir seu próprio dispositivo/coordenador Zigbee ou Thread

• Dispositivos Zigbee não-Tuya (ex.: Philips Hue) não são atendidos pelo TinyTuya; usam a API da bridge ou Zigbee2MQTT/ZHA.

Notas relacionadas

• Interruptor Zigbee
• Protocolo Thread - Redes
• ESP32-C6
• Home Assistant com Claude API e MCP no Raspberry Pi 5

Casos de Uso

• Automatizar tomadas, lâmpadas e cortinas Tuya sem depender da nuvem no dia a dia.
• Integrar dispositivos Tuya a scripts, MQTT, Home Assistant ou workflows.
• Monitorar vários dispositivos com Monitor.

Público-alvo

Desenvolvedores e entusiastas de automação residencial que usam dispositivos Tuya/Smart Life e querem controle local em Python.

Limitações

• Precisa da nuvem Tuya (wizard) ao menos uma vez para obter as Local_Key.
• Sem suporte documentado a Zigbee/BLE direto; sub-dispositivos dependem de um gateway.
• A página do repositório não traz exemplo completo de sub-dispositivo nem explica como obter cid/node_id; esta nota foi baseada no texto disponível (parcialmente truncado). Valide no devices.json e na seção de gateways do README antes de implementar.
• Monitor é experimental.

Referências

• TinyTuya (GitHub)
• Zigbee2MQTT - Tuya DPs