# tuya-zigbee-switch replaces the firmware in cheap Zigbee switches

> This project builds custom firmware for Tuya Zigbee switches, modules and sockets on Telink and Silicon Labs chipsets, so a device that ignores two buttons at once can be pushed as a Zigbee remote with binding, long press actions and outgoing binds. It covers 160+ devices, ships a stub simulator for testing, and still lists scenes, multi-press and touchlink as unfinished.

**romasku/tuya-zigbee-switch** — Feature-rich custom firmware for Telink/Silabs Zigbee switches, modules, sockets

- Repository: https://github.com/romasku/tuya-zigbee-switch
- Stars: 694 · Forks: 184
- Language: JavaScript
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/romasku-tuya-zigbee-switch

## Firmware for the cheap switches everyone regrets buying

The repository is a feature-rich custom firmware for Telink and Silicon Labs Zigbee switches, modules and sockets, and the README already tells you the device count, 160 or more supported devices, with the list in `docs/supported_devices.md` and instructions for porting a new device in `docs/contribute/porting.md`.

The subject is the cheap end of the smart home market. A Tuya branded switch, module or socket that a supplier sold on the basis of a mobile app, sold with a factory firmware that does a limited job. The project replaces that firmware with one built for Zigbee use rather than for a vendor's cloud.

The primary language of the repository is JavaScript, which is worth noting for a firmware project, since the Zigbee application logic is what the community spends its time in, and the build tooling around it is the part written in scripts and Makefiles. The top level shows a `src/` directory, a `Makefile` with `board.mk` and `tools.mk`, `make_scripts/`, `helper_scripts/`, `tests/`, a `device_db.yaml` with its `device_db.schema.json`, a `VERSION` file, an `NVM_MIGRATIONS_VERSION` file, an `uncrustify.cfg` for formatting, and directories named `zha/`, `zigbee2mqtt/` and `homed/` that mirror the platforms the firmware has to work with.

The licence is one GitHub cannot categorise, with the terms in the `LICENSE` file at the root, and the repository is not archived with the last push on 2026-10-11 and no GitHub releases published.

## It started with a relay that would not listen

The README explains the motivation as a frustrating bug in the factory firmware, and it is specific enough to be testable.

When you pressed one button, the device shortly ignored input from the others. As a result, simultaneously pressing two buttons toggled a single relay. So a two gang switch had one relay for two buttons, and the second press did nothing.

The second half of the motivation is what turns this from a bug fix into a project. Users consider it the missing piece of a reliable smart home, because it allows using a light switch as a Zigbee remote. Most cheap switches on the market don't allow binding to other devices out of the box, so a switch that cannot bind is a switch that is only ever a switch.

That reframes the whole project. The alternative to this firmware is not a better switch, it is a different device that does one job, a battery powered remote, paired with a coordinator that does the binding. The project's claim is that a wall switch is a better remote than a coin cell, because it is where the hand already is, and the firmware is what makes that possible.

## What the implemented feature list actually covers

The features section is a list of relay and binding behaviours, and it is the most useful part of the README for deciding whether the project is for you.

On timing, there is a super fast reaction time with a choice of action moment, press or release, and a configurable long press for push switches with both the action and the duration set. On topology, there is a detached mode that unlinks the switch from its own relay, outgoing binds so the switch can remotely control Zigbee lights including state and brightness, and custom switch action modes that keep the switch position, the relay state and the bound devices in sync. All button types are supported, toggle, momentary normally open and momentary normally closed, and there are both Router and EndDevice modes for no-Neutral devices.

On the device behaviour, power-on behaviour is configurable, to on, off, previous or toggle. Multiple reset options are offered, with a configurable multi-press count and the on-board button. And the project supports wireless switches, meaning battery powered remotes, along with curtain modules.

The update story is the part that reduces risk. Wireless flashing and updating are supported, with an OTA from the original firmware and further OTA updates after that, so in many cases the first installation does not need a soldering iron, and neither does the second.

## The work in progress list is the honest feature matrix

The README keeps a separate list of what is not finished yet, and for a hardware project that list is more informative than the finished one.

FW-level multi-press, that is double or triple click detection, has a pull request linked for progress. Countdown timers, given as `on_with_timed_off`, are listed as not done. Inching, a pulse on the relay output, is listed. Scenes, both sending and receiving, are listed. Power monitoring has its own progress pull request. Touchlink is listed. And two items are about integration rather than the device itself: integrating converters with Z2M, and integrating updates with Z2M.

Read that list next to the feature list above and the shape of the project becomes clear. The device side, how the buttons behave, what the relay does, how the switch binds to other devices, is largely done. The ecosystem side, tying the firmware into a coordinator that can convert devices, push updates and offer scene control, is still being built.

For a buyer with a single switch and a plain on and off light, none of the missing items matter. For someone building a house with many switches, scenes and converters are the difference between a collection of devices and a system, and the README is clear that those are the parts still moving.

## Two ways in: OTA for Telink, wires for everything else

The installation section splits by what is possible rather than by preference.

If your device is already on the supported devices list, the firmware can be installed wirelessly on Z2M or ZHA, and the README adds the important qualifier, only Telink devices, with the procedure in `docs/updating.md`. It can also be installed by wire, with the documents under `docs/flashing/`. And if your device is not on the list, the README points you to the porting guide instead.

That qualifier is the practical constraint of the whole project. Wireless updating needs a mechanism the coordinator can use to push a new image, and the README documents that path for Telink only, which means a Silicon Labs device needs the wired route at least for the first install.

The documentation tree is organised around the same split. `docs/faq.md` is marked as the troubleshooting entry point, `docs/known_issues.md` holds known issues, `docs/changelog_fw.md` is the firmware changelog, `docs/contribute/` covers contributing and porting, and `docs/usage/` holds the operational documentation including `endpoints.md` and `change_device_type.md`.

There is also a chat channel, a Discord server, which the README suggests for discussing, troubleshooting and following updates, and the acknowledgements credit `doctor64/tuyaZigbee` for firmware for other Tuya Zigbee devices and a Hello Zigbee World series of guides for the Zigbee programming background.

## The build system delegates by vendor and ships a simulator

The top level Makefile delegates to target specific Makefiles, and its help target is a good map of the project. The first lines:

```
	@echo "Tuya Zigbee Switch"
	@echo "============================================="
	@echo ""
	@echo "Quick Start:"
	@echo "  make stub/build    - Build stub device for testing/simulation"
	@echo "  make stub/run      - Run stub device interactively"
	@echo "  make tests          - Run automated tests (builds stub first)"
	@echo ""
	@echo "Telink Development:"
	@echo "  make telink/tools/all - Download and install Telink tools"
	@echo "  make telink/build     - Build firmware for Telink TC32"
	@echo "  make telink/help      - Show Telink build system help"
```

Three things fall out of that. Each chipset has its own toolchain, downloaded and installed by the build, with the Telink path targeting the TC32 and the Silicon Labs path targeting the EFR32MG21. Each vendor has its own first time setup, such as trusting the SDK signature for Silicon Labs and generating project files from the `.slcp` description.

And there is a stub device, a host-native simulation binary with a REPL interface, which the test target then runs against:

```
	@echo "Testing:"
	@echo "  make tests          - Run full pytest suite against stub device"
	@echo ""
	@echo "Bootloader:"
	@echo "  make silabs/bootloader_build   - Build bootloader"
	@echo "  make silabs/bootloader_install - Flash bootloader"
	@echo ""
	@echo "Tools:"
	@echo "  make tools/help                    - Show all available tools commands"
	@echo "  make tools/clean_z2m_index         - Clear all Zigbee2MQTT OTA index files"
```

A simulator for firmware is unusual and it is the most valuable engineering decision in the repository. It means the Python test suite can exercise the device logic without any hardware on the desk, and the Python side of the project is small and ordinary:

```
Jinja2==3.1.6
MarkupSafe==3.0.2
PyYAML==6.0.2
pytest==8.4.2
pyserial==3.5
click==8.1.3
```

Jinja2 for templating the firmware sources, PyYAML for the device database, pyserial for talking to the hardware, pytest for the tests and click for the command line tools.

## What replacing a factory firmware asks of you

This is a project that asks you to accept some risk in exchange for a capability the hardware did not have. Flashing custom firmware onto mains connected devices is not a casual operation, and the README does not offer a warranty of any kind, so the decision about whether a given switch is worth it belongs to the person who owns the wiring.

There are also two quieter limits. The first is coverage. 160 or more devices is a wide list, and a list this wide is rarely uniform, so the supported devices document is the file to read before you buy or before you start, and the porting guide is the fallback for a model that is not on it.

The second is that the missing features are not peripheral. Scenes, countdown timers, inching, firmware level multi-press and touchlink are all listed as work in progress, and if your design depends on any of them you should wait.

The alternative approach is to leave the factory firmware alone. Most Zigbee coordinators can already bind a switch to a light, and a battery powered remote can be bound in seconds without touching firmware at all, and a mains powered switch you can wire to a relay module is a different product. The difference in approach is where the change happens. Coordinator side binding leaves the device's own button handling untouched, so the multi button bug stays, but nothing is flashed. Firmware side changes the device, so the bug goes away, the switch becomes a usable remote, and you own the maintenance of that firmware on every device you flash.

## Conclusion

Adopt tuya-zigbee-switch when your Zigbee devices are cheap Tuya units on Telink or Silicon Labs silicon, when the factory firmware's multi button behaviour is the actual problem, and when you are willing to flash mains connected hardware and to check the supported devices list before you start. Do not adopt it for a device outside that list, for a feature still marked as work in progress such as scenes, touchlink or countdown timers, or when you only need a remote, since a battery powered Zigbee remote bound to your lights avoids the firmware change entirely. Verify first that your exact model is in the supported devices list, that the install route matches your chipset, since wireless updating is documented for Telink devices only, and that the custom licence in the repository's LICENSE file covers the use you have in mind.

## FAQ

### What devices does the tuya-zigbee-switch firmware support?

The README says 160 or more supported devices for Telink and Silicon Labs Zigbee switches, modules and sockets, with the list in docs/supported_devices.md. If a model is not on the list, the README points to the porting guide at docs/contribute/porting.md.

### How do I install the tuya-zigbee-switch firmware?

If the device is on the supported list you can update wirelessly on Z2M or ZHA, but the README notes that wireless updating is for Telink devices only, with the steps in docs/updating.md. There is also a wired route documented under docs/flashing/.

### Which features are not finished in tuya-zigbee-switch?

The work in progress list covers FW-level multi-press, countdown timers with on_with_timed_off, inching, scenes, power monitoring, touchlink, integrating converters with Z2M and integrating updates with Z2M. Several of those items have linked progress pull requests.

### Can I test the tuya-zigbee-switch firmware without hardware?

Yes. The Makefile offers `make stub/build` to build a host-native simulation binary and `make stub/run` to run the stub device with a REPL interface, and `make tests` runs the full pytest suite against that stub device.

## Sources

- [Issues](https://github.com/romasku/tuya-zigbee-switch/issues)
- [README](https://github.com/romasku/tuya-zigbee-switch/blob/main/README.md)
- [romasku/tuya-zigbee-switch on GitHub](https://github.com/romasku/tuya-zigbee-switch)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/romasku-tuya-zigbee-switch