Zigbee2MQTT on RPI with CC2530/CC2591

James Young · May 2, 2019

So, if you’ve flashed a CC2530/CC2591 from my previous post, you now probably want to get it talking to something. Here’s how you can do that.


I will assume you are wanting to do the following;

  • Use a Raspberry Pi 2/3 running Raspbian to act at the bridge between the CC2530/CC2591 and MQTT.
  • You’re using Raspbian Stretch.
  • You want to use Zigbee2MQTT to get this thing talking to something like HomeAssistant.
  • You want to use the RPI’s built-in UART and directly wire the module to the RPI.
  • You don’t care about Bluetooth on the RPI.
  • You already have Docker installed on the RPI.
  • You already have Docker-Compose installed on the RPI.
  • You already have your CC2530/CC2591 flashed with KoenKK’s Z-Stack firmware, and it’s a recent version.
  • You have a mqtt server somewhere already.

Phew. Now with all that in line, let’s get moving.

Hardware Setup

<figcaption>CC2530/CC2591 Pinout Diagram</figcaption></figure>

<figcaption>RPI2/3 GPIO Pinout</figcaption>

Using the two charts above, you will need to make the following connections;

VCC (Supply) VCC 3V3
GND (Ground) GND G
RXD (Receive Data) P0_2 RPI Pin 8 (TXD)
TXD (Transmit Data) P0_3 RPI Pin 10 (RXD)

This is the minimum set of pins required. Note that RXD on the CC2591 gets connected to TXD on the RPI. This is normal.

Do not connect the CC2530 to the 5V lines on the RPI. Doing so will likely destroy the CC2530.

Configure UART on the RPI

What we’ll be doing is using the UART on the RPI. There are a number of ways to do this, but we’ll use the method which disables Bluetooth and puts the UART on the high-performance device /dev/ttyAMA0.

Edit your /boot/config.txt and add the following;


Then edit /boot/cmdline.txt and remove the following bit from the only line;


Reboot your Pi, and you should now have the UART pins listed above manifest on /dev/ttyAMA0. Don’t try and use minicom or similar to connect to it, you won’t see much useful.

Set up a HomeAssistant Docker-Compose File

We’re going to use Docker Compose to run zigbee2mqtt in a container. Make a directory somewhere for it, and a data directory, like so;

mkdir -p /srv/zigbee2mqtt/data

Then edit /srv/zigbee2mqtt/docker-compose.yml, and fill it in like this;

version: '2'
image: koenkk/zigbee2mqtt:arm32v6
restart: always
- /srv/zigbee2mqtt/data:/app/data
- /dev/ttyAMA0:/dev/ttyAMA0

Now, this will spin up a zigbee2mqtt service when you start it, which will always restart when stopped, using /dev/ttyAMA0 as we defined earlier. Lastly, create a /srv/zigbee2mqtt/data/configuration.yaml and fill it in like this;

homeassistant: true
permit_join: true
base_topic: zigbee2mqtt
server: 'mqtt://YOURMQTTSERVERHERE:1883'
include_device_information: true
port: /dev/ttyAMA0
log_level: info
baudrate: 115200
rtscts: false

I strongly suggest you change the network key, and disable permit_join when you have all your devices up. There’s various other things to do here too, but this should get you started.

Once that’s done, a simple;

docker-compose up

Should bring up your container. Press Ctrl-\ to break out without terminating it.

Twitter, Facebook