FAQ

Questions that came up while building this.

Pulled from the actual troubleshooting sections in Setup, Security, and the project skills — not invented for this page.

The bulb shows “Device Unreachable” — what do I do?

The bulb lost power or dropped off Wi-Fi — cheap Wi-Fi bulbs do this occasionally, including the one this project was built against, observed multiple times across every build session. Power-cycle it and retry. This is normal bulb/router behavior, not a dashboard bug.

Commands return 200 OK but the bulb doesn't actually change

Almost always the wrong protocol version in config.json. Try 3.3 first, then 3.1/3.4/3.5 — whichever tinytuya scan reported during setup.

The Tuya IoT Platform QR scan does nothing

A known Tuya console bug — almost always a data-center mismatch between the Cloud Project's region and the app account's region, or scanning while logged in as a shared “family member” account. Skip it entirely and use the cloud-assisted tuya-device-sharing-sdk login instead — see Setup.

My bulb's IP changed and the dashboard lost it

Routers reassign DHCP leases. Use Diagnostics → Rescan Network, or turn on network auto-discovery's scheduled scanning (see the API reference's discovery section), which detects IP changes for already-configured bulbs automatically. Setting a DHCP reservation for the bulb's MAC address avoids this entirely.

The Audio Reactive tab shows no input devices

PortAudio couldn't enumerate a device. Confirm sounddevice installed correctly in the backend's own venv (pip show sounddevice), and that you're not running inside Docker — audio devices generally aren't passed through to containers. See Audio-Reactive Lighting.

I enabled the PIN gate and now I'm locked out

The dashboard's own root page always stays reachable even with the gate on — if you can't even see the PIN prompt, that's a different, more serious issue worth reporting. If you're seeing the prompt but locked out after wrong attempts, wait out the 5-minute lockout, or restart the backend process (lockout state is in-memory, not persisted). See Remote Access & Security.

Can I add a second bulb?

Yes — the architecture already supports it. config.json is a list of devices, and groups/audio orchestration already work against however many bulbs are configured. Get the new bulb's credentials the same way as the first (the cloud-assisted login lists every bulb on the account once you're logged in), add an entry to config.json, restart. No code changes needed.

Does any of this touch the cloud?

Not for day-to-day use. Bulb control talks directly to the bulb over your LAN. Network discovery is a local UDP broadcast — nothing leaves your network. The one-time setup step (getting the local key) does use Tuya's cloud-assisted login, since that key is never broadcast locally by design.

Can I try this without owning a real Tuya bulb?

Not currently — there's no simulated/demo device mode. Everything here was built and tested against one real physical bulb.

Didn't find your question? Open an issue.