Building a LAN-Only Tuya-to-Apple Home Bridge: What Three Smart Bulbs Taught Me About Local Protocols, State Authority and Resilient IoT Design

This technical white paper documents the design and implementation of a lightweight, LAN-only bridge connecting legacy Tuya lighting devices to Apple Home through @homebridge/hap-nodejs, without relying on Home Assistant, Homebridge as the runtime engine, Matterbridge, or cloud control in the normal command path. The work focuses on three real Tuya v3.3 bulbs with overlapping but non-identical datapoint surfaces. Their behavior is used to examine persistent state versus live control, desired versus observed state, smooth transitions, command timing, local caching, missing acknowledgments, device-specific controller behavior, failure isolation, identity, and runtime address resolution. The project shows that reliable local IoT integration depends less on simply speaking a protocol than on defining state authority, timing, identity, capability exposure, and failure boundaries correctly. The resulting architecture is intentionally narrow: a minimal local bridge, separated from device identity and secret management, designed to remain observable, resilient, and easy to reason about.