Universal Tuya docsHomeSupported devicesRequest a deviceFAQChangelogArchitectureKnowledge baseCreditsSourcesContributing

Architecture

A short tour of the moving parts. Each section links to the code and to the knowledge-base note that explains the design in more detail.

Overview

ButtonEventRouter

Code: lib/buttons/ · Note: button event router

Goal: one physical press = one Flow trigger, whatever path the press arrives on. Each path (on/off command, scene recall, level step, Tuya private commands, data points, multistate input) has a normaliser that returns which button and which press type. A per-device router removes copies that arrive on another path within a short window; the window adapts to the latency it observes and stays bounded. It also learns which presses the device sends natively, so software emulation of double/long presses is used only when needed.

ZCL layer

Code: lib/zigbee/cluster/ · Note: ZCL cluster layer

A registry merges duplicate cluster definitions instead of letting the last one win, adds missing standard commands, and provides bound clusters that capture incoming commands (on/off, scenes, colour, covers, groups, alarms). Bindings come from the real interview and are redone on wake-up at a bounded rate; when reporting cannot be configured, a bounded polling fallback takes over. OTA requests are only observed (read-only).

Time sync

Code: lib/tuya/ (TimeSync files)

Tuya MCU devices request the time with a dedicated command; the app answers in the format the device family expects (several epoch variants exist) and re-sends on wake-up for sleepy devices, with retries when a write fails.

Wi-Fi local

Code: lib/wifi/ · Note: Wi-Fi local protocols

Wi-Fi drivers talk to Tuya devices on the LAN (protocol 3.1–3.5) with a local-first policy and the cloud only as a fallback. Product schemas (data point maps) are generated from public catalogues and credited. A pairing helper can import a device list exported by tinytuya.

Cross-research

Code: scripts/research/cross-research.js · Note: cross-research

Every incoming request (issue, forum post, diagnostic report, CI report) goes through one pass that extracts ids only when they appear verbatim, then checks them against the public references. The verdict is: place (confirmed couple, goes into one specific driver), lead (ranked candidates), or needs info.

Provisional tier

Code: scripts/research/lib/provisional.js · Data: data/leads/provisional-couples.json

A couple seen in real evidence but not yet confirmed by a reference is kept in a provisional list instead of being added to a driver. A daily job looks for a new source: a confirmed couple is promoted to its driver with the source credited; a conflicting one is demoted and flagged.

How this documentation is built

The site and the root README are generated by docs/tools/ from app.json, the changelog, docs/site-src/ and the knowledge base. The Deploy Device Finder to GitHub Pages workflow rebuilds it on every change to the drivers or to the docs, and checks every internal link.