TapHome

Sonoff SNZB-01

Packet Parser → MQTT
Submitted by
Last updated: 04. 2026
Sonoff SNZB-01

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:

VariableDescriptionHow to obtainExample
SonoffSNZB01Zigbee2MQTT friendly name or IEEE address of the SNZB-01Zigbee2MQTT web UI → Devices → find SNZB-01 → copy friendly name or IEEE address0x00124b001eab21e5

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

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 actionMQTT payloadTapHome value
Single press (release + 0.6 s wait)single1
Double pressdouble3
Long press (hold 2 seconds)long2

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
  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

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 USB-C rechargeable battery.

Available devices

Sonoff SNZB-01 Module
Custom Variables
SonoffSNZB01 (string) = 0x00124b001eab21e5Zigbee2MQTT 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

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

enum
Service Attributes
BatteryRemaining battery percentage (CR2450 coin cell, 0–100 %)
LinkQualityZigbee signal quality indicator — 0 (worst) to 255 (best)
BatteryVoltageBattery voltage in millivolts

Wireless Button

Read button state
Bp := 0;
Write button state
# 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
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
IF(ISNAN(battery),"-",battery+"%");
LinkQuality
IF(ISNAN(link),"-",link+"lqi");
BatteryVoltage
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.

Sources