A one-script installer that turns a Raspberry Pi + CC2531 USB adapter into a vendor-neutral Zigbee home automation gateway running Domoticz — supporting 800+ Zigbee devices from any manufacturer.
Raspberry Pi with CC2531 USB Zigbee adapter — the complete Pimoticz hardware.
The problem
Cheap Zigbee home automation devices are everywhere, but they're locked to the manufacturer's gateway — limiting you to a small set of supported devices. With commercial off-the-shelf (COTS) hardware, you can build your own vendor-neutral gateway, but it requires setting up multiple components:
- Raspberry Pi
- CC2531 USB Zigbee adapter (with Koenkk firmware, ~$12 on Amazon)
- Raspberry Pi OS (32-bit)
- Node.js (v12 or higher)
- zigbee2mqtt
- Mosquitto MQTT broker
- Domoticz
- zigbee2mqtt plugin for Domoticz
For beginners, getting all these components working together is a challenging task. Pimoticz simplifies this with an automated installer script — in about 5 minutes you should be ready to pair your first Zigbee device.
Items needed
- Raspberry Pi
- Micro SD card
- 5V power adapter
- CC2531 USB Zigbee adapter
Important: To avoid the CC2531 programming setup, buy a pre-programmed USB adapter with Koenkk firmware (CC2531_DEFAULT_20190608.zip or higher).
Raspberry Pi OS setup
CC2531 USB adapter, keyboard, mouse, monitor, and internet connection are only needed during the initial setup.
Step 1 — Prepare the SD card using Raspberry Pi Imager and install Raspberry Pi OS 32-bit.
Step 2 — Insert the SD card, connect keyboard/mouse/monitor and internet to your Raspberry Pi, then power on.
Step 3 — On first boot, the setup wizard will guide you through:
- Language and keyboard layout (important for correct local time — Domoticz needs it)
- Set a new password for the
piuser - Black border check (not important — Raspi will run headless after setup)
- Wi-Fi setup (skip if using Ethernet)
- Software update (optional — can skip to save time)
- Reboot to apply settings
Pimoticz software stack — zigbee2mqtt, Mosquitto, and Domoticz working together.
Pimoticz installation
Open a terminal on the Raspberry Pi (locally or via SSH) and run:
git clone https://github.com/hackboxguy/pimoticz.git cd /home/pi/pimoticz sudo ./setup.sh -h my-pimoticz # -h hostname is optional # wait ~5 minutes for setup to complete sudo reboot
Setup script in progress — installing all dependencies automatically.
After reboot, open a browser and navigate to http://127.0.0.1:8080 or http://my-pimoticz:8080 — Domoticz will show the detected CC2531 Zigbee coordinator.
Domoticz running on Pimoticz — CC2531 Zigbee coordinator detected and ready to pair devices.
Your Pimoticz gateway is ready. You can now pair Zigbee devices from any manufacturer — Xiaomi, IKEA, Philips Hue, Sonoff, and 800+ more.
SOURCE CODE
github.com/hackboxguy/pimoticz — installer script and documentation
