Skip to content
amd989Public
forked from moustik/xbee2mqtt

About

XBee to MQTT gateway - Python 3 daemon for bridging XBee ZigBee radios to MQTT brokers

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

xbee2mqtt

Docker Pulls Docker Image Size Build Status

A Python 3 daemon that bridges XBee ZigBee radios to MQTT brokers. It monitors a coordinator XBee connected to a serial port, translates radio messages to MQTT topics, and enables remote control of XBee digital I/O pins through MQTT commands.

From version 0.3 it also supports setting digital pins LOW or HIGH on remote radios.

Key requirements:

  • The XBee radio must be configured in API mode (not transparent mode)
  • Python 3.6+ (migrated from Python 2.7)

Quick Start with Docker (Recommended)

The easiest way to run xbee2mqtt is using Docker. Pre-built images available for all major architectures!

Using Docker Hub (Recommended)

# Pull the latest image (automatically selects your architecture)
docker pull amd989/xbee2mqtt:latest

# Or use docker-compose (see docker-compose.yml)
docker-compose up -d

Supported architectures:

  • linux/amd64 - x86 64-bit (PCs, servers, cloud)
  • linux/arm64 - ARM 64-bit (Raspberry Pi 3/4/5 with 64-bit OS)
  • linux/arm/v7 - ARM 32-bit v7 (Raspberry Pi 2/3/4 with 32-bit OS)
  • linux/arm/v6 - ARM 32-bit v6 (Raspberry Pi Zero, Pi 1)
  • linux/386 - x86 32-bit

Quick Setup

# 1. Copy and configure
cp config/xbee2mqtt.yaml.sample config/xbee2mqtt.yaml
# Edit config/xbee2mqtt.yaml with your settings

# 2. Update docker-compose.yml with your serial device
#    USB adapter: /dev/ttyUSB0 (default)
#    Raspberry Pi GPIO: /dev/ttyAMA0 or /dev/serial0

# 3. Start with Docker Compose
docker-compose up -d

# 4. View logs
docker-compose logs -f

Raspberry Pi users: If connecting XBee to GPIO UART pins, uncomment the Raspberry Pi device lines in docker-compose.yml. See RASPBERRY_PI.md for complete Raspberry Pi setup guide.

See README.docker.md for detailed Docker deployment instructions.

Install as a Package (Alternative to Docker)

On Debian, Ubuntu or Raspberry Pi OS (Bookworm or Trixie), xbee2mqtt can run as a systemd service instead of a container:

curl -fsSL https://packages.alejandro.md/setup.sh | sudo sh
sudo apt install xbee2mqtt

That adds the packages.alejandro.md repository and installs xbee2mqtt. One package fits every architecture (amd64, arm64, armhf, armel), so it runs on any Raspberry Pi. On Fedora, Rocky or Alma, the same setup.sh line works, followed by sudo dnf install xbee2mqtt. Updates come with the rest of the system (sudo apt upgrade), and the service is restarted after an update.

Installing doesn't start anything. Set the serial port and your MQTT broker in the config first (see Configuration):

sudo nano /etc/xbee2mqtt/xbee2mqtt.yaml

Then start the service and have it start on boot:

sudo systemctl enable --now xbee2mqtt
journalctl -u xbee2mqtt -f    # logs

The service runs as the xbee2mqtt user, which is in the dialout group so it can open the serial port. Your edits to /etc/xbee2mqtt/xbee2mqtt.yaml are kept across updates. If the radio doesn't answer, stop the service and probe the port to find its baud rate and mode:

sudo systemctl stop xbee2mqtt
sudo -u xbee2mqtt xbee2mqtt-probe /dev/ttyUSB0

Requirements

Python 3.6 or higher is required. All dependencies will be installed automatically.

Option 1: Docker (Recommended)

  • Docker and Docker Compose installed
  • XBee coordinator radio connected via:
    • USB-to-Serial adapter (any Linux/macOS/Windows)
    • Raspberry Pi GPIO UART pins
    • Direct USB connection to Raspberry Pi

Option 2: Native Installation

Install dependencies in a virtual environment:

# Create virtual environment and install dependencies
./do setup

# Or manually with pip
pip install -r requirements.txt

Required packages:

  • pyyaml >= 5.4.1
  • pyserial >= 3.5
  • paho-mqtt >= 1.6.1
  • parse >= 1.19.0
  • xbee >= 2.3.2
  • pytest >= 7.4.0 (for testing)

Installation

Docker Installation

  1. Clone the repository:

    git clone <repository-url>
    cd xbee2mqtt
  2. Configure and run:

    cp config/xbee2mqtt.yaml.sample config/xbee2mqtt.yaml
    # Edit config/xbee2mqtt.yaml
    docker-compose up -d

Native Installation

  1. Clone the repository

  2. Set up virtual environment:

    ./do setup
  3. Configure the application (see Configuration section below)

Configuration

Copy the sample configuration and edit it:

cp config/xbee2mqtt.yaml.sample config/xbee2mqtt.yaml

Then edit config/xbee2mqtt.yaml with your settings. The configuration is straightforward:

general

duplicate_check_window lets you define a time window in seconds where messages for the same topic and with the same value will be ignored as duplicates. default_topic_pattern lets you define a default topic for every message. It accepts two placeholders: {address} for the radio address and {port}. The port can be the radio pin (dio-12, adc-1, adc-7,...) or a string for messages sent through the UART of the sending radio. routes dictionary defines the topics map. Set publish_undefined_topic False to filter out topics not defined in the routes dictionary. If it's True and the route is not defined it will be mapped to a topic defined by the default_topic_pattern. For every defined route a subscription to the same route plus "/set" will be done. If the route maps to a digital port in the remote radio you can change its status to OUTPUT LOW ot OUTPUT HIGH by publishing a 0 or a 1 to this topic.

radio

Configuration of the port where the XBee is attached to. All messages are defined by the originating radio address (an 8 byte value) and a port or pin. The default_port_name parameter lets you define what port name to use when the message was originally sent through the UART interface of the originating radio To send a custom message just send "port:value\n" through the UART interface of the radio, if no port is specified the default_port_name value will be used.

mqtt

These are standard Mosquitto parameters. The status topic is the topic to post messages when the daemon starts or stops.

processor

The processor is responsible for pre-processing the values before publishing them. There are several filters defined in libs/Filters.py

Running

With Docker

# Start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

# Restart
docker-compose restart

As a Package

sudo systemctl enable --now xbee2mqtt   # start, and start on boot
sudo systemctl restart xbee2mqtt        # after editing /etc/xbee2mqtt/xbee2mqtt.yaml
journalctl -u xbee2mqtt -f              # logs

Native Deployment

The utility runs as a daemon. Control it with:

# Using the helper script (automatically uses virtualenv)
./do start
./do stop
./do restart

# Or directly with Python
python xbee2mqtt.py start
python xbee2mqtt.py stop
python xbee2mqtt.py restart
python xbee2mqtt.py reload  # Reload config without restarting

Debugging

Monitor raw XBee messages:

./do console  # or: python xbee2console.py

Testing

Verify the Python 3 migration and run tests:

# Verify migration (checks Python version, dependencies, syntax, imports)
python verify_migration.py

# Run unit tests
pytest tests/TestProcessor.py -v
# or: ./do tests

All tests should pass:

✅ Python version: 3.6+
✅ All dependencies installed
✅ No syntax errors
✅ All modules import successfully
✅ 10/10 filter tests passing

For detailed testing procedures, see the verification script output.

Migration from Python 2

This project has been migrated from Python 2.7 to Python 3.9+. Key changes:

  • ✅ Python 3.6+ required
  • ✅ Modern test framework (pytest instead of nose)
  • ✅ Updated dependencies (pyyaml instead of pyaml)
  • ✅ Docker support with Python 3.9 base image
  • ✅ All tests passing

If you were using an older version, simply:

  1. Update your Python version to 3.6+
  2. Reinstall dependencies: pip install -r requirements.txt
  3. Verify: python verify_migration.py

Documentation

Browse all documentation in the docs/ folder.

License

GPL v3 - See COPYING for details

Support

For issues, questions, or contributions, please open an issue on the repository.

About

XBee to MQTT gateway - Python 3 daemon for bridging XBee ZigBee radios to MQTT brokers

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages