Raspberry Pi Home Assistant Utility Node with MQTT and Zigbee2MQTT

Expected Outcome

A working Raspberry Pi Home Assistant utility node capable of managing Zigbee devices and communicating via MQTT, with a dependable update process.

Assumptions

• Raspberry Pi 3 or newer
• MicroSD card (16GB or larger)
• Power supply for Raspberry Pi
• USB Zigbee adapter (e.g., CC2531)
• Computer for initial setup
• Basic knowledge of Linux command line

Bill of Materials

• Raspberry Pi OS installed on MicroSD card
• Home Assistant installation
• Mosquitto MQTT broker
• Zigbee2MQTT software
• Git for version control

Build Steps

1. Prepare Raspberry Pi

   Set up your Raspberry Pi with Raspberry Pi OS and ensure it is connected to the internet.

   Changes system state: review before running

   sudo apt update
   sudo apt upgrade -y
   sudo apt install git -y

2. Install Home Assistant

   Install Home Assistant on your Raspberry Pi.

   Changes system state: review before running

   sudo apt install python3 python3-venv python3-pip -y
   mkdir ~/homeassistant
   cd ~/homeassistant
   python3 -m venv venv
   source venv/bin/activate
   pip install homeassistant
   hass

3. Set up Mosquitto MQTT Broker

   Install and configure Mosquitto as your MQTT broker.

   Changes system state: review before running

   sudo apt install mosquitto mosquitto-clients -y
   sudo systemctl enable mosquitto
   sudo systemctl start mosquitto

4. Install Zigbee2MQTT

   Clone the Zigbee2MQTT repository and install its dependencies.

   Safe to run: read-only

   git clone https://github.com/Koenkk/zigbee2mqtt.git
   cd zigbee2mqtt
   npm install

5. Configure Zigbee2MQTT

   Edit the Zigbee2MQTT configuration file to connect to the MQTT broker.

   Example pattern only. Adjust for your environment before running.

   nano configuration.yaml

6. Start Zigbee2MQTT

   Run Zigbee2MQTT to start managing your Zigbee devices.

   Safe to run: read-only

   npm start

7. Implement Safe Update Workflows

   Set up a version control system and backup strategy to ensure safe updates.

   Changes system state: review before running

   git init
   git add .
   git commit -m 'Initial commit'
   sudo apt install rsync -y
   rsync -av --exclude='venv/' ~/homeassistant/ ~/backup/homeassistant/

Validation

• Access Home Assistant via http://<your_pi_ip>:8123
• Check MQTT broker status with 'mosquitto_sub -h localhost -t test/topic'
• Verify Zigbee2MQTT is running and devices are connected

Troubleshooting

• Check service logs before changing the design.
• Confirm ports, paths, credentials, DNS names, and container names match the guide assumptions.

Cleanup or Rollback

• Stop test services you no longer need and keep a copy of working configuration before deleting volumes or data directories.

Next Improvements

• Add Zigbee devices to your network
• Explore Home Assistant integrations for additional functionalities
• Set up remote access for Home Assistant