This project provides a Python daemon to transform a Raspberry PI into a bridge between GPIO inputs/outputs and HomeAssistant, through MQTT. In particular this software allows to:
- sample low-voltage inputs from Raspberry GPIO pins directly (with no isolation/protection/HAT), publish them on MQTT and get them exposed to Home Assistant as binary sensors;
- sample a wide range of electrical signals (voltages) from 3V-48V AC or DC, using a dedicated Raspberry HAT, publish them on MQTT and get them exposed to Home Assistant as binary sensors;
- expose Raspberry GPIO output pins in Home Assistant as switches or as buttons to e.g. activate relays, using a dedicated Raspberry HAT / relay board or just drive low-voltage electrical devices;
All these features are implemented in an Home Assistant-friendly fashion. For example, this utility requires no configuration on Home Assistant-side thanks to MQTT discovery messages that are automatically published and let Home Assistant automatically discover the devices. In other words you will just need to prepare 1 configuration file (the rpi2home-assistant config file) and that's it. All properties of the exposed devices (names, icons, descriptions, etc) can be provided/customized in the rpi2home-assistant config file.
An example of a panel of sensors/actuators created using rpi2home-assistant in Home Assistant 2024.5 (sensor/switch/button names have been blurred for privacy reasons; binary sensor status is shown in Italian language):
This software is meant to run on a Raspberry PI. In addition to standard GPIOs, rpi2home-assistant optionally provides specific support for the following hat:
- Sequent Microsystem 16 opto-insulated inputs HAT. This hat allows to sample a wide range of electrical signals (voltages) from 3V-48V AC or DC. rpi2home-assistant exposes the sampled values over MQTT, to ease their integration as (binary) sensors in Home Assistant.
The suggested way to use a RaspberryPI to drive external loads is through the use of relay boards. There are a number of alternatives available on the market. The majority of them is really simple and ask for the 3.3V or 5V power supply and then connect to the RaspberryPI through GPIO pins either active high or active low. A couple of suggested hats exposing relays are:
Beyond that, this software is meant to be compatible with all 40-pin Raspberry Pi boards (Raspberry Pi 1 Model A+ & B+, Raspberry Pi 2, Raspberry Pi 3, Raspberry Pi 4, Raspberry Pi 5).
Software prerequisites are:
- you must have an MQTT broker running somewhere (e.g. a Mosquitto broker);
- Python >= 3.11; for Raspberry it means you must be using Debian bookworm 12 or Raspberry Pi OS 12 or higher;
- there is no particular constraint on the Home Assistant version, even if the project is continuously tested almost only against the latest Home Assistant version available.
The Raspberry Pi OS does not allow to install Python software using pip.
Trying to install a Python package that way leads to an error like:
error: externally-managed-environment [...]
That means that to install Python software, a virtual environment has to be used. This procedure automates the creation of the venv and has been tested on Raspberry Pi OS 12 (bookworm). Just copy-paste on your raspberry each command:
sudo su
# python3-dev is needed by a dependency (rpi-gpio) which compiles native C code
# pigpiod is a package providing the daemon that is required by the pigpio GPIO factory
apt install git python3-venv python3-dev pigpiod
cd /root
git clone https://github.com/f18m/rpi2home-assistant.git
cd rpi2home-assistant/
make raspbian_install
make raspbian_enable_at_boot
make raspbian_start
Then of course it's important to populate the configuration file, with the specific pinouts for your raspberry HATs (see Preqrequisites section).
The configuration file of rpi2home-assistant is of course /etc/rpi2home-assistant.yaml.
During the installation the default config file with dummy options is installed.
It is useful to showcase the syntax. See config.yaml for
the full documentation of the configuration options.
This python code needs to run as root due to ensure access to the Raspberry I2C and GPIO peripherals.
After starting the application you can verify from the logs whether it's running successfully:
journalctl -u rpi2home-assistant --since="5min ago"
This project also provides a multi-arch docker image to ease testing. You can launch this software into a docker container by running:
docker run -d \
--volume <your config file>:/etc/rpi2home-assistant.yaml \
--privileged --hostname $(hostname) \
ghcr.io/f18m/rpi2home-assistant:<latest version>
However please note that using Docker on a Raspberry PI is probably an overkill for this application, so the preferred way to save CPU is to install using a dedicated Python venv (see above).
This section contains information useful in case you want to hack/collaborate on the project. Patches/improvements and new features are welcome.
This project uses poetry as build system (https://python-poetry.org/) so the 'build' is as simple as:
python3 -m build
To develop changes you can create a branch and push changes there. Then:
make format
make lint
make docker
make unit-test
make integration-test
To validate locally your changes.
Finally, once ready, check out your branch on your raspberry and then run:
python3 -m venv ~/rpi2home-assistant-venv
~/rpi2home-assistant-venv/bin/pip3 install .
source ~/rpi2home-assistant-venv/bin/activate
cd <checkout_folder>/raspy2mqtt
./raspy2mqtt -c /etc/rpi2home-assistant.yaml
Alternatively you can test manually on your local machine by running:
make run-mosquitto
nano myconfig.yaml # stick the Mosquitto port exposed locally inside the config file
make run-docker CONFIG_FILE_FOR_DOCKER=myconfig.yaml
- Sequent Microsystem 16 opto-insulated inputs python library
- aiomqtt python library
- AsyncIO tutorial
- Home Assistant
Very similar project, more flexible and much bigger, targeting specific sensor boards:
- Eventually get rid of GPIOZERO + PIGPIOD which consume CPU and also force use of e.g. the queue.Queue due to the multithreading issues; replace these 2 parts with direct Raspberry PI GPIO access?