service_zigbee/HOWTO.md

# Reading a SONOFF SNZB-02P on a Raspberry Pi 5

The simplest setup is:

```text
SONOFF sensor -> Zigbee USB dongle -> Zigbee2MQTT -> MQTT -> terminal/application
```

You do not need to open the sensor until Zigbee2MQTT is ready.

## 1. Connect and identify the dongle

Attach the dongle's antenna before powering it. Connect it to the Raspberry Pi,
preferably through a short USB extension cable to reduce USB 3 radio
interference.

Run:

```bash
lsusb
ls -l /dev/serial/by-id/
```

You should see a persistent device path similar to:

```text
/dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_...
```

Use this `/dev/serial/by-id/...` path instead of `/dev/ttyUSB0` or
`/dev/ttyACM0`, because those shorter names can change after a reboot.

Check the label on the dongle to determine its adapter type:

| Dongle model | Zigbee2MQTT adapter type |
| --- | --- |
| `ZBDongle-P` | `zstack` |
| `ZBDongle-E` | `ember` |

The two dongles have similar names but contain different radio chips.

References:

- [Zigbee2MQTT adapter configuration](https://www.zigbee2mqtt.io/guide/configuration/adapter-settings.html)
- [ZBDongle-P documentation](https://www.zigbee2mqtt.io/guide/adapters/zstack.html)
- [ZBDongle-E documentation](https://www.zigbee2mqtt.io/guide/adapters/emberznet.html)

## 2. Install the Mosquitto MQTT broker

On Raspberry Pi OS, run:

```bash
sudo apt update
sudo apt install -y mosquitto mosquitto-clients
sudo systemctl enable --now mosquitto
systemctl status mosquitto --no-pager
```

For an initial setup confined to the Pi and a trusted LAN, the local broker is
sufficient. Configure authentication before exposing MQTT outside your trusted
network.

Reference: [Mosquitto downloads](https://mosquitto.org/download/)

## 3. Run Zigbee2MQTT with Docker

Zigbee2MQTT recommends Docker because it avoids most Node.js and dependency
setup problems. Its image supports the Raspberry Pi's ARM architecture.

If Docker and Docker Compose are already installed, create a working directory:

```bash
mkdir -p "$HOME/zigbee2mqtt/data"
cd "$HOME/zigbee2mqtt"
```

Create a file named `compose.yaml` containing:

```yaml
services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: ghcr.io/koenkk/zigbee2mqtt:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    devices:
      - /dev/serial/by-id/REPLACE_WITH_YOUR_DONGLE:/dev/ttyACM0
    environment:
      - TZ=Europe/Amsterdam
```

Replace `REPLACE_WITH_YOUR_DONGLE` with the exact filename returned by:

```bash
ls /dev/serial/by-id/
```

Start Zigbee2MQTT and follow its logs:

```bash
docker compose up -d
docker compose logs -f zigbee2mqtt
```

From another computer, open:

```text
http://RASPBERRY_PI_IP:8080
```

For example:

```text
http://192.168.1.50:8080
```

The first-run onboarding page should appear. Configure these values:

```text
MQTT server: mqtt://172.17.0.1
Serial port: /dev/ttyACM0

Adapter:
  ZBDongle-P -> zstack
  ZBDongle-E -> ember
```

If `172.17.0.1` does not reach Mosquitto, use the Raspberry Pi's LAN IP
instead. Zigbee2MQTT may detect the adapter automatically.

References:

- [Official Zigbee2MQTT Docker installation](https://www.zigbee2mqtt.io/guide/installation/02_docker.html)
- [Zigbee2MQTT onboarding](https://www.zigbee2mqtt.io/guide/getting-started/)

## 4. Pair the SNZB-02P sensor

In the Zigbee2MQTT web interface:

1. Click **Permit join**.
2. Open the SNZB-02P.
3. Remove the battery insulation tab.
4. Hold its button for about five seconds, until the LED flashes.
5. Keep the sensor close to the dongle during pairing.
6. Wait for Zigbee2MQTT to report that the device was successfully interviewed.
7. Rename it to something simple, such as `living_room_sensor`.
8. Turn **Permit join** off afterward.

The device page should now show temperature, humidity, and battery level. The
SNZB-02P uses a CR2477 battery.

Reference: [SNZB-02P device support](https://www.zigbee2mqtt.io/devices/SNZB-02P.html)

## 5. Read the temperature

Listen for sensor updates on the Raspberry Pi:

```bash
mosquitto_sub -h localhost \
  -t 'zigbee2mqtt/living_room_sensor' \
  -v
```

A message will look similar to:

```json
{
  "battery": 100,
  "humidity": 48.2,
  "linkquality": 132,
  "temperature": 21.6
}
```

To print only the temperature, install `jq` if necessary:

```bash
sudo apt install -y jq
```

Then run:

```bash
mosquitto_sub -h localhost \
  -t 'zigbee2mqtt/living_room_sensor' |
jq --unbuffered '.temperature'
```

Battery-powered sensors normally report periodically or when their readings
change, rather than continuously. The SNZB-02P publishes `temperature` in °C
and `humidity` as a percentage.

Reference: [Zigbee2MQTT MQTT topics](https://www.zigbee2mqtt.io/guide/usage/mqtt_topics_and_messages.html)