---
title: "Sonoff SNZB-01"
description: "Sonoff SNZB-01 paired to Zigbee2MQTT: TapHome detects single, double and long press over MQTT and shows battery, voltage and link quality."
url: "https://taphome.com/en/compatibility/zigbee2mqtt-sonoffsnzb01/"
language: en
lastmod: 2026-10-08
generator: hugo
ai:
  topics: ["mqtt","sensor","zigbee","zigbee2mqtt","battery-powered","wireless-button"]
  questions: ["How to integrate Sonoff SNZB-01 with TapHome via Zigbee2MQTT?","What button actions does the Sonoff SNZB-01 TapHome template detect?","How to configure the Zigbee2MQTT friendly name for SNZB-01 in TapHome?","Why is my Sonoff SNZB-01 not reporting button presses in TapHome?","Does the SNZB-01 template report battery level and link quality?"]
---

# Sonoff SNZB-01

Communication: Packet Parser → MQTT

- [Sonoff SNZB-01 Product Page](https://sonoff.tech/product/gateway-and-sensors/snzb-01/)

> Network address
> 
> With the MQTT broker built into TapHome, enter `127.0.0.1` as the broker address in TapHome. In the device, enter the IP address of the TapHome Core and give the Core an IP reservation in the router.
> 
> [Network Preparation](https://taphome.com/en/docs/setup/network-preparation/)

## Integration guide

The Sonoff SNZB-01 is a compact Zigbee 3.0 wireless button powered by a CR2450 coin cell battery. It communicates with TapHome indirectly — the button pairs with a Zigbee2MQTT coordinator (e.g., Sonoff ZBDongle-P/E or CC2652-based stick), which bridges Zigbee messages to MQTT topics. TapHome subscribes to these MQTT topics via a PacketParser MQTT module.

The template detects three button actions (single press, double press, long press) and monitors battery percentage, battery voltage, and Zigbee link quality.

## Configuration

### Zigbee2MQTT setup

Before importing the TapHome template, the SNZB-01 must be paired with a Zigbee2MQTT coordinator:

1. Open the Zigbee2MQTT web UI and enable pairing mode (**Permit join**)
2. On the SNZB-01, remove the back cover and long press the reset button for 5 seconds until the LED flashes three times
3. The device appears in the Zigbee2MQTT device list with an IEEE address (e.g., `0x00124b001eab21e5`) or a friendly name

### Module variable

After importing the template in TapHome, set the `SonoffSNZB01` custom variable to identify the device on the MQTT broker:

| Variable | Description | How to obtain | Example |
|----------|-------------|---------------|---------|
| `SonoffSNZB01` | Zigbee2MQTT friendly name or IEEE address of the SNZB-01 | Zigbee2MQTT web UI → Devices → find SNZB-01 → copy friendly name or IEEE address | `0x00124b001eab21e5` |

The variable is used as the MQTT topic prefix — the listener script subscribes to `zigbee2mqtt/{SonoffSNZB01}` and `zigbee2mqtt/{SonoffSNZB01}/action`.

> [!TIP]
> Using the friendly name (e.g., `living_room_button`) instead of the IEEE address makes the configuration more readable. The friendly name can be changed in the Zigbee2MQTT web UI under device settings.

## Device capabilities

### Button press detection

The template maps the SNZB-01 as a Push Button device in TapHome. Button press events arrive on the `zigbee2mqtt/{id}/action` topic and are mapped to numeric values:

| Physical action | MQTT payload | TapHome value |
|----------------|-------------|---------------|
| Single press (release + 0.6 s wait) | `single` | 1 |
| Double press | `double` | 3 |
| Long press (hold 2 seconds) | `long` | 2 |

After reading the button state, the value resets to 0 — button actions are event-based and cannot be read back.

### Battery and signal monitoring

Each button instance exposes three service attributes:

- **Battery** — remaining battery percentage (0–100 %) from the JSON state topic. The SNZB-01 uses a CR2450 coin cell with typical lifespan of 1–2 years.
- **BatteryVoltage** — battery voltage in millivolts from the JSON state topic.
- **LinkQuality** — Zigbee signal quality indicator (0–255 lqi) from the JSON state topic. Higher values indicate better signal.

All attributes display `"-"` until the first message is received from the device.

### Additional capabilities

The Zigbee2MQTT bridge also exposes a proactive state request topic (`zigbee2mqtt/{id}/get`) that can request battery and voltage values on demand, and an availability topic for online/offline detection. These capabilities can be added in a future template update.

## Troubleshooting

### Button presses not detected

1. Verify the SNZB-01 is paired with the Zigbee2MQTT coordinator — it should appear in the device list with a green status
2. Check that the `SonoffSNZB01` custom variable matches the device's friendly name or IEEE address exactly (case-sensitive)
3. Use an MQTT client (e.g., MQTT Explorer) to subscribe to `zigbee2mqtt/#` and press the button — a message should appear on the `/action` topic
4. If no MQTT messages appear, the device may have lost its Zigbee connection — re-pair by long pressing the reset button for 5 seconds

### Stale battery or link quality values

1. Battery and signal data update only when the device wakes up (on button press or periodic reporting)
2. If values show `"-"`, no message has been received yet — press the button to trigger an update
3. Ensure the Zigbee coordinator has good reception — the SNZB-01 range depends on the Zigbee mesh network

> [!WARNING]
> The Sonoff SNZB-01 is discontinued and replaced by the SNZB-01P. The TapHome template remains valid for existing SNZB-01 devices, but new purchases should consider the SNZB-01P which offers improved range and a larger CR2477 coin-cell battery.

## Available devices 1

These devices appear in TapHome after import.

Sonoff SNZB-01 Module

Custom Variables

`SonoffSNZB01` (string) = 0x00124b001eab21e5 Zigbee2MQTT friendly name or IEEE address of the SNZB-01 device — used as MQTT topic prefix

Open Zigbee2MQTT web UI → Devices → find SNZB-01 → copy the Friendly name (or use the IEEE address, e.g. 0x00124b001eab21e5)

Wireless Button Push Button Read and write

Button press detection — single (1), double (3), long (2); resets to 0 after read

enum

Service Attributes

|                |                                                           |
|----------------|-----------------------------------------------------------|
| Battery        | Remaining battery percentage (CR2450 coin cell, 0–100 %)  |
| LinkQuality    | Zigbee signal quality indicator — 0 (worst) to 255 (best) |
| BatteryVoltage | Battery voltage in millivolts                             |

Read button state

```taphome
Bp := 0;
```

Write button state

```taphome
# Simple HTTP Request:
# VAR response := SENDHTTPREQUEST("/example/set/value=" + Bp);
# IF response.IsSuccess = false
#  ADDERROR(response.StatusCode);
# END
#
# Set Http request method, body and headers
# VAR response := SENDHTTPREQUEST("/example/setValue", "GET", "value=" + Bp, "header1:value1", "header2:value2", ...);\r
# Or VAR request := HTTPREQUEST("/example/setValue");
# request.Method := "PUT";
# VAR response := SENDHTTPREQUEST(request);
#r
#
# Send TCP, UDP data:
# VAR data1 := "{\"name\":\"John\", \"age\":" + Bp + "}";
# SENDDATA(data1);
# VAR data2 := TOBYTES("{\"name\":\"John\", \"age\":" + Bp + "}", "iso-8859-1");
# SENDDATA(data2);
# You can process received TCP or UDP data in the Listener script
#
#
# Upload data to FTP:
# FTPUPLOAD("filePath", "somedata=" + Bp, "write"); # use "append" mode to append data to existing file
```

Listener

```taphome
Bp := 0;

IF (COMPARE(RECEIVEDMSG.TOPIC, "zigbee2mqtt/"+ SonoffSNZB01 +"/action", CompareOptions.IgnoreCase) = 0)
	var payloadString := TOSTRING(RECEIVEDMSG.PAYLOAD);
	
    IF (COMPARE(payloadString, "single", CompareOptions.IgnoreCase) = 0)
          Bp := 1;
        ELSEIF (COMPARE(payloadString, "long", CompareOptions.IgnoreCase) = 0)
          Bp := 2;
        ELSEIF (COMPARE(payloadString, "double", CompareOptions.IgnoreCase) = 0)
          Bp := 3;
        ELSE
          Bp := 0;
    END  
END;   

IF (COMPARE(RECEIVEDMSG.TOPIC, "zigbee2mqtt/"+ SonoffSNZB01, CompareOptions.IgnoreCase) = 0)
    battery := PARSEJSON(RECEIVEDMSG.PAYLOAD,"battery", true);
    voltage := PARSEJSON(RECEIVEDMSG.PAYLOAD,"voltage", true);
    link := PARSEJSON(RECEIVEDMSG.PAYLOAD,"linkquality", true);
    
END
```

Service Attributes

Battery

```taphome
IF(ISNAN(battery),"-",battery+"%");
```

LinkQuality

```taphome
IF(ISNAN(link),"-",link+"lqi");
```

BatteryVoltage

```taphome
IF(ISNAN(voltage),"-",voltage+"mV");
```

**Connection:** Packet Parser → MQTT

Possible improvements (2)

- Proactive State Request — Publish {"battery":""} or {"voltage":""} to request values on demand. Could wake sleeping device.
- Availability Status — Online/offline availability topic. Could detect unreachable devices.

## Import parameters

Enter these values when you import the XML.

| Asked in the app       | Default       |
|------------------------|---------------|
| Mqtt Broker IP address | `192.168.0.1` |
| Mqtt Broker port       | `1883`        |

## Sources

- Zigbee2MQTT — SNZB-01 device page
  
  [www.zigbee2mqtt.io](https://www.zigbee2mqtt.io/devices/SNZB-01.html) 2026-03-30
- Zigbee2MQTT GitHub — SNZB-01 device definition
  
  [github.com](https://github.com/Koenkk/zigbee2mqtt.io/blob/master/docs/devices/SNZB-01.md) 2026-03-30

## Related Documentation

- [MQTT Integration](https://taphome.com/en/compatibility/mqtt-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/en/docs/integration/packet-parser/)
- [Packet parser functions](https://taphome.com/en/docs/script/packet-parser/)
- [Parsing functions](https://taphome.com/en/docs/script/parsing-functions/)
- [MQTT Broker](https://taphome.com/en/docs/integration/packet-parser/mqtt-broker/)
- [Listener scripts](https://taphome.com/en/docs/script/listener-scripts/)