Wi-Fi local (tuya-local) helpers and Tuya Zigbee helpers (hand-written reference)
Written 2026-11-17 for the documentation coverage work (P3359, queue item 5), continuing MODULES_SMART_TEMPORAL_AND_LOCAL. Each entry says in our own words what the module is for, how it is bounded and where it is wired. "Importers" counts the other files under lib/, drivers/ and app.js that require() it on master at the time of writing; 0 means nothing loads it today (kept for reference, never removed without a check). Modules reached only through a folder index.js count that index as an importer.
Wi-Fi local: pairing, credentials and accounts (lib/tuya-local/)
lib/tuya-local/ManualEntryNormalizer.js(P2931) - cleans what a user types in the manual LAN pairing/repair form.normalizeIptrims, drops a:portsuffix, accepts IPv4 only and rejects 0.0.0.0, broadcast and loopback addresses (returns an empty string).normalizeVersionmaps labels such as "v3.3" throughTuyaProtocolVersions; an unknown label becomesautoso the documented protocol chain is probed. Importers: 1 (TuyaLocalDriver).lib/tuya-local/TuyaAuthCatalog.js(P2409) - single source for the Tuya/Smart Life cloud data centres (endpoint, display name, aliases), app schemas and device-list APIs, plus the region fallback order and schema fallback chain. Used at pairing only; runtime control stays on the LAN. Importers: 4 (TuyaUserLogin,TuyaSmartLifeAuth,TuyaCloudAPI, ...).lib/tuya-local/TuyaUserLogin.js(P2471) - builds the login identity for the Smart Life / Tuya Smart easy login: e-mail or phone account, country code guessed from the region when missing, list of regions and app schemas to try, and the request body of the authorized login. Guards against a phone account sent as e-mail and a wrong regional endpoint. Importers: 1 (TuyaCloudAPI).lib/tuya-local/normalizeTuyaUsername.js(P2476) - decides whether a username is an e-mail or a phone number and keeps digits only for phones, so phone-only accounts are not rejected by a form that assumed e-mail. Importers: 1 (TuyaUserLogin).lib/tuya-local/TuyaKeyTypes.js(P2408) - describes and normalises every credential shape seen on Homey: the 16-byte LANlocal_key(ASCII or 32-hex paste), itsdevice_keyalias, the clouduuid(pairing only, never an AES key), a parentgateway_keyfor sub-devices, and the well-known UDP discovery key. Also builds the LAN protocol fallback chain (3.1 to 3.5) and guesses the protocol from a discovery packet. Importers: 0.lib/tuya-local/TuyaWhiteLabelCatalog.js- conservative list of Wi-Fi brands that ship Tuya modules under their own app, with the way to obtain the local key for each (sharing_qr,iot_link,move_to_smartlife,manual) andkeyRetrievalAdvice()text for the pairing UI. The brands speak the same LAN protocol once device id and key are known. Importers: 0.lib/tuya-local/tuya-local-wizard.js- classTuyaLocalWizard: fetches the device list and local keys from the Tuya Cloud OpenAPI with an Access ID/Secret and a region, in the spirit of thetinytuya wizardcommand, behind a circuit breaker. Importers: 0 (newer pairing goes throughTuyaCloudAPI/TuyaSmartLifeAuth).lib/tuya-local/TuyaTcpForceScan.js(P2411) - finds devices that stay silent on UDP (often protocol 3.5 or a filtered network) by trying a TCP connect on port 6668 across the local /24, with a short timeout (280 ms), bounded concurrency (28) and at most 254 hosts per interface. Only run on demand during pairing (force scan / max discover / cloud-LAN matching), never as a background sweep, to protect memory. Importers: 1 (TuyaPairingOrchestrator).lib/tuya-local/TuyaCloudMQTT.js(v5.12.7) - optional real-time updates for cloud-linked devices over the Tuya MQTT channel: start/stop, reconnect with delay, AES-GCM payload decoding, a 256 KiB payload cap, listener add/remove, and a shared network breaker (4 failures, 2 min reset) that also backs off under memory pressure. Importers: 1 (TuyaWiFiHybridManager).
Wi-Fi local: forum lessons and driver wiring
lib/tuya-local/MultiSocketInference.js(P2950) - a power strip paired as a single plug only drove DP1. From the merged DP map seen while probing,inferSockets/subSocketPlanlist outlets on boolean DP1-DP6, an optional USB/master switch on DP7 and ignore countdown DPs 9-15; anything ambiguous keeps the single-plug behaviour. Idea from forum topic 154077 post 526 (credited in the file). Importers: 2.lib/tuya-local/WifiLanLessons.js(P2953) - small advisory helpers from the Tuya Local Homey thread (topic 154077, credited in the file): re-read state about 1.5 s after a mode change because many thermostats change their setpoint silently; explain the "state readable but commands ignored" case (sub-device behind a hub or wrong device id); take the cover command words from the cloud DP range when known; and a recorder of what happens at connection start for support bundles. Importers: 3 (TuyaLocalDevice,WifiDriverWiring,wifi_thermostat).lib/tuya-local/WifiDriverWiring.js(P2954) - connects the two modules above to the drivers, optional and never throwing: extraonoff.socket*/onoff.usbcapabilities forwifi_plug,wifi_switchandwifi_generic(DP1 stays ononoff), a command acknowledgement tracker, and cover command sets read from the cloud range. Importers: 2 (TuyaLocalDevice,wifi_cover).lib/tuya-local/SupportBundle.js(P2950) - JSON diagnostic export of a LAN device that users can share publicly: keys, tokens, passwords and uid are replaced by[redacted], IP addresses are masked, nesting depth is bounded. Importers: 1 (LocalDeviceInsights).
Tuya Zigbee helpers (lib/tuya/)
lib/tuya/Ef00MultiGangProfiles.js(P2485) - profiles for TS0601 multi-gang wall switches whose families differ in gang count (3 or 4) and in backlight/indicator DPs (coloured backlight, simple, v2 layouts), with converters for power-on state, indicator mode and backlight colour. Resolved by manufacturer only after the driver compose has already matched the exact couple, so no product id is invented. Importers: 2 (wall_switch_4_gang_tuya,switch_3gang).lib/tuya/TuyaMultiGangManager.js- full multi-gang switch DP handling following Tuya's public gateway documentation: per-gang on/off (DP1-4), countdowns (DP7-10), power-on state (DP14 and per-gang DP29-32), LED indicator (DP15), backlight (DP16) and inching (DP19). Exported throughlib/tuya/index.js. Importers: 1.lib/tuya/FaultBitmapDecoder.js(v9.0.40) - turns fault bit fields of circuit breakers, water meters, thermostats and air-quality devices into readable names (for breakers the 17-fault list known from Zigbee2MQTT and ZHA), withdecodeFaults,hasFaultand a DP transform. Importers: 0.lib/tuya/HobeianZg301zHeal.js(P2632) - heal for the HOBEIAN ZG-301Z wall module whose light switched off about 5 s after ON: clears a leftover on-time countdown, forces the switch type back to the stored state, drops phantom power capabilities and calms mesh traffic. Applied only when the manufacturer matches. Importers: 2 (switch_1gangdriver and device).lib/tuya/ThermostatMeteringDps.js(P3067) - power, voltage, current and energy DPs of three thermostats/TRVs, keyed on the exact manufacturer name with the divisor per DP (facts from zigbee-herdsman-converters, credited in the file). Capabilities are added on the first real report, never at pairing; the wall thermostat consumes DP101 here so it does not arm the fan-coil path. Importers: 2 (device_radiator_valve,wall_thermostat).lib/tuya/TongouAcFrequency.js(P2580) -_TZE284_6ocnqlhnreports mains frequency on DP32 either in centihertz (4999) or already in hertz (50); the value is normalised into the 45-65 Hz band instead of a blind divide by 100, otherwise null. Importers: 1 (din_rail_meter).lib/tuya/TuyaMotorDirection.js(P2580) - some covers report motor direction as a string ("forward", "back", "reversed", ...) instead of 0/1; both forms are mapped toforward/backso open and close are not inverted. Importers: 1 (curtain_motor).lib/tuya/TimeSyncPolicy.js- per-device opt-out of Tuya time sync for devices that misbehave when the time is pushed: settingtuya_time_syncoff makes every time-sync path skip sending; a missing setting keeps the old behaviour (allowed). Importers: 11 (UnifiedSensorBase,BaseTuyaDPDevice,GlobalTimeSyncEngine, ...).lib/tuya/TuyaGatewayEmulator.js(v5.5.29) - acts like a Tuya gateway for devices with a clock or display: answers time requests, pushes time on device announce and on a periodic broadcast, with several send paths (Tuya manager, ZCL time, raw command) tried in order. Importers: 1 (sensor_motion_radar).lib/tuya/TuyaAdapter.js- sends a Tuya (0xEF00) frame through whichever send method the cluster object offers, so code works across SDK/library versions; fails with a clear error when no cluster is given. Importers: 2 (LowLevelBridge,lib/tuya/index.js).lib/tuya/TuyaDPDataLogger.js(v5.2.11, v5.2.83) - records every incoming Tuya DP and ZCL attribute report per device (last values and times) for diagnostics and auto-discovery. Importers: 1 (BaseUnifiedDevice).lib/tuya/TuyaDPFlowCardManager.js(v5.5.603) - generic Flow dispatcher for TS0601 devices: maps DP reports to triggers and conditions, and actions to DP writes, with enum name tables (temperature unit, device mode, thermostat mode, fan speed, battery state); cards are looked up safely so a missing card does not throw. Importers: 1 (BaseTuyaDPDevice).lib/tuya/TuyaSensorDatabase.js(v9.0.0) - central table of sensor DP layouts and quirks grouped by family (for example the ZY-M100 radar layout: presence, sensitivity, near/far range, distance), withgetSensorConfig()lookup. Importers: 1 (TuyaUniversalMapper).lib/tuya/TuyaSpecificDevice.js- base class (on top ofAutoAdaptiveDevice) for Tuya DP devices: detects whether the 0xEF00 cluster answers, otherwise stays on standard clusters, sets up the DP engine and offerssendDataPoint/getDataPoint. Importers: 2 (SelfHealingDevice,lib/tuya/index.js).lib/tuya/LocalTuyaInspired.js(v5.5.682) - constant tables (DP types, entity families and their usual DP ranges, energy DPs with divisors) modelled on LocalTuya and TinyTuya conventions. Importers: 2 (LocalTuyaEntityHandler,lib/tuya/index.js).lib/tuya/LocalWiFiTuyaBridge.js(v2.0.0) - local-first facade for Wi-Fi devices: UDP discovery, per-device sessions throughTuyaLocalClient(protocol auto-detect, heartbeat, backoff) and an explicit transport decision log (LAN always preferred, cloud only when LAN is impossible and the policy allows it). Exported throughlib/tuya/index.js. Importers: 1.lib/tuya/IntelligenceHealth.js(v9.0.40) - on-demand reachability check of a few reference sites (project repo, device database, Homey developer docs) behind a circuit breaker that only counts real network errors and returns false while open. Importers: 0.