The TS0041 is a one-button, battery-powered Tuya Zigbee scene switch. It reports single, double and hold actions; it does not switch a wired load itself. A supported unit can join Zigbee2MQTT and drive Home Assistant automations without a Smart Life account.
Two checks prevent a lot of confusion after pairing. Battery reporting varies between units that share the TS0041 name, so an empty percentage does not by itself prove the join failed. Home Assistant also discovers each MQTT device-trigger action only after the button has generated it once. Check live presses before treating a missing entity or trigger as a hardware fault.
What the TS0041 actually is
Zigbee2MQTT’s TS0041 page lists Smart9 S9TSZGB, Lonsonho TS0041 and Benexmart ZM-sui1 white labels. The released definition also includes fingerprinted variants such as Nous LZ4. The storefront name is therefore a useful clue, but the reported model, manufacturer string and device definition are better evidence of which unit you have.
TS0041A has a separate definition, including a voltage expose not listed for the generic TS0041. Check the actual interview result rather than assuming that similarly named buttons have identical fields.
The supported TS0041 has a built-in converter; an external file is not needed for the normal documented path. The same applies to the documented two-button TS0042 and three-button TS0043. Other Tuya families, including TS0601, need their own exact-model and manufacturer check; the model prefix alone does not tell you whether support is built in.
Direct Zigbee pairing does not need the per-device Tuya LAN key used by compatible Wi-Fi products. The Tuya Zigbee and local-key guide explains that distinction. If yours is a Wi-Fi switch instead, the LocalTuya versus Tuya-Local comparison is the relevant route.
Pairing into Zigbee2MQTT
- Check the cell type and polarity in your unit’s manual. Remove any battery insulation tab, then enable permit joining in Zigbee2MQTT.
- Use the joining gesture for that exact product. For example, the Nous LZ4 manual specifies holding its reset button for five seconds until the blue LED blinks. Other TS0041 hardware can use the main button or a separate pairing button; the shared model name does not establish one universal sequence.
- Wait for the interview to complete and inspect the model, manufacturer string and supported definition. Assign a friendly name you can recognize.
- Close permit joining. Try single, double and hold and watch fresh action reports in the frontend or MQTT. Test again in the final location before attaching the button permanently.
If you want to watch MQTT directly, replace both placeholders below with your broker address and the exact friendly-name topic, including any changed base topic. Use your broker’s normal authentication and TLS settings where required. The example does not configure those for you.
mosquitto_sub -h BROKER_IP -t 'zigbee2mqtt/BUTTON_FRIENDLY_NAME' -v
Observe a newly generated press, rather than treating an old cached or retained message as a successful test. If no live action arrives, investigate the join, cell, range and logs before debugging the Home Assistant automation.
What it exposes: battery and action, nothing to switch
The generic TS0041 definition exposes battery and action; messages can also include Zigbee2MQTT’s standard linkquality. Battery is a reported percentage estimate, not a direct measurement of usable capacity. Neither battery nor action supports a documented /get or /set on this model.
This is an illustrative single-press message, not a measurement from a tested unit. Your payload can include additional diagnostics or omit a battery value.
zigbee2mqtt/Entry switch
{
"battery": 91,
"action": "single"
}
The documented actions are single, double and hold. They describe presses, rather than a persistent on/off state of the button. To toggle a light or run a scene, an automation needs to consume that event and command the target.
The TS0041 values have no button prefix: use single, not 1_single. The released converter explicitly treats TS0041 and TS0041A as single-button devices even when their endpoint layout varies. TS0042 and TS0043 actions use prefixes such as 1_single and 2_hold, so check copied blueprints and YAML against the actual payload.
Battery: the correct cell and missing reports
Use the cell specified for your particular white-label product. CR2032 is documented for the Nous LZ4, a TS0041 variant in the released definition; that does not make the Tuya model string a universal battery specification for every enclosure or board sold under it.
The TS0041 device page says battery percentage can take up to 24 hours to arrive. Allow that initial reporting window while checking that button actions work. It is not a promise that every unit will report within a day or proof that every missing value is harmless.
Historical issue #8500, on Zigbee2MQTT 1.21.0-4, compared _TZ3000_pzui3skt, which reported battery on presses, with _TZ3000_fkp5zyho, which did not. The discussion found different hardware and a missing genPowerCfg cluster on the latter. This is a useful variant example, not a complete current good/bad manufacturer list.
Issue #6180 had a different outcome: the reporter on 1.17.1 obtained a battery reading after a configuration change, and the maintainer added a fix in February 2021. It does not support saying that battery omissions can never be fixed centrally. Conversely, that old reporting configuration is not a general recipe to paste into a current converter: the released TS0041 code records its later removal because it caused repeated dropouts and poor battery life on affected devices.
If actions arrive but the battery field stays empty, record the manufacturer, firmware, clusters and current software version. Check the matching support reports before resetting a working button. A percentage can be stale, and an unloaded voltage reading alone cannot establish remaining life under radio load.
For a button that does not join or produces no live presses, check insulation, polarity and battery contact, then try a fresh cell of the specified type and repeat the documented pairing procedure near the coordinator. A thinner CR2025 is not a documented substitute for a unit specified for CR2032. Follow the manufacturer’s cell specification rather than changing type on the strength of a pairing anecdote.
Automating single, double and hold presses
For Zigbee2MQTT’s recommended Home Assistant path, enable its Home Assistant discovery and configure Home Assistant’s MQTT integration on the same broker. Single-press, double-press and hold once each so their device triggers can be discovered, then select the button and action in the automation editor.
The following is a Home Assistant configuration.yaml example. Replace the device ID and light entity with real values; the device ID is Home Assistant’s registry ID, not the Zigbee IEEE address or the MQTT friendly name. If you use an existing automation: section, merge the list entry into it. In automations.yaml, which is commonly included as a list, omit the outer automation: line.
automation:
- alias: "Entry switch - single press"
triggers:
- trigger: device
domain: mqtt
device_id: REPLACE_WITH_YOUR_DEVICE_ID
type: action
subtype: single
actions:
- action: light.toggle
target:
entity_id: light.entryway
Save and load the automation through Home Assistant’s normal configuration workflow, then press the button and inspect its trace. Add double and hold using the actual discovered subtypes. This tests the button-to-MQTT path and the automation-to-target path separately.
Each action must have occurred at least once to be discovered. This behavior is documented in the Home Assistant integration guide and illustrated by issue #29667. If live MQTT actions work but triggers still do not appear, check discovery and the MQTT integration before re-pairing.
Home Assistant MQTT device triggers, legacy action sensors and experimental event entities are separate ways to consume the same button activity. The legacy action sensor is deprecated and requires homeassistant.legacy_action_sensor: true; it is not the default entity you can assume will exist. A missing action sensor can therefore be a configuration choice rather than a fault.
The event-entity blueprint thread uses the experimental route. To enable those entities, merge experimental_event_entities: true under the existing homeassistant: section of Zigbee2MQTT’s configuration, retaining enabled: true. That adds event entities; it does not require replacing MQTT device triggers or make an old sensor-based blueprint compatible.
An event entity’s state is the time of the latest event, with the press type in its attributes. A blueprint written for that mechanism needs a different trigger from one expecting a text action sensor. Check its requirements and your installed version, and prefer documented device triggers if you do not need the experimental behavior. The TS0042 guide covers related action-discovery troubleshooting.
Where it fits against TS0042 and TS0043
| TS0041 | TS0042 | TS0043 | |
|---|---|---|---|
| Physical buttons | 1 | 2 | 3 |
| Listed action values | 3: single, double, hold | 6: 1_single through 2_hold | 9: 1_single through 3_hold |
| Zigbee2MQTT support | Built-in converter | Built-in converter | Built-in converter |
| Possible use | One entryway light, scene or chime trigger | Two readily identifiable physical choices | Three physical choices for several scenes |
The TS0042 and TS0043 definitions establish those action lists. Pick the number of physical controls people need, rather than treating more gestures as automatically easier to use. One button may be enough for a chime or entryway light; two or three can make separate functions clearer without remembering double-press mappings.
FAQ
What battery should I buy? Follow the exact product’s label and manual. CR2032 is documented for the Nous LZ4 variant. Do not assume every TS0041 enclosure takes the same cell or substitute CR2025 based on a pairing anecdote.
Can it work without Smart Life? A supported TS0041 can pair directly to a Zigbee2MQTT coordinator, without a Tuya account, app step or Tuya LAN key. Your automation’s target and any notifications have their own dependencies.
Why is battery percentage missing? The initial report can take up to a day, while historical variants also had absent clusters or configuration issues. Confirm live actions and the exact manufacturer before diagnosing a failed pairing or assuming an unfixable device.
Which gestures are available? The generic definition lists single, double and hold with no button prefix. They are events, not an on/off state or a writable command to the button.
What should I do if it will not pair? Check the correct cell, insulation tab, polarity and contacts; enable permit joining and follow the actual product’s reset gesture near the coordinator. Inspect interview errors and the reported model/manufacturer. If the join works but an automation does not, check live MQTT actions and discovery before resetting again.
Sources and checks for your unit
This guide uses the Zigbee2MQTT device pages, released TS0041 definition, manufacturer instructions for the named variant and the linked primary issue reports. There was no new pairing or bench test for this article. The historical battery cases show why both model and manufacturer matter; they are not a current reliability ranking of every white label.
Direct button reports and local Home Assistant actions do not need a Tuya cloud service. A remote broker, cloud-controlled appliance, voice service or notification can still introduce a separate dependency. Verify the whole automation you intend to use, rather than inferring that it is offline merely because its trigger is Zigbee.
For your unit, check the exact cell and join instructions, live single/double/hold actions, battery freshness and the Home Assistant trigger mechanism. Diagnose the working button path separately from a missing percentage or deprecated entity.