rpi2home-assistant 2.3.0__tar.gz

rpi2home_assistant-2.3.0/.github/workflows/docker-push.yml

@@ -0,0 +1,27 @@
+name: docker-push CI
+
+on:
+  push:
+    # Pattern matched against refs/tags
+    tags:        
+    - '*'           # Push events to every tag not containing /
+  
+jobs:
+  docker_push:
+    runs-on: ubuntu-latest
+  
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: build and push Docker image
+        uses: mr-smithers-excellent/docker-build-push@v6
+        with:
+          # options related to BUILDing the docker image:
+          multiPlatform: true
+          platform: linux/amd64,linux/arm64,linux/arm/v7
+          image: rpi2home-assistant
+          addLatest: true
+          # options related to PUSHing the docker image:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.PAT_TOKEN_FOR_GITHUB }}

rpi2home_assistant-2.3.0/.github/workflows/main.yml

@@ -0,0 +1,67 @@
+name: main CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  # -------------------------------------------------------------------------- 
+  #                                    build                                   
+  # -------------------------------------------------------------------------- 
+  build:
+    runs-on: ubuntu-24.04
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: install pypi-packaged dependencies
+      run: sudo pip3 install build
+
+    # test Python packaging
+    - name: package the pypi
+      run: |
+        python3 -m build
+
+  # -------------------------------------------------------------------------- 
+  #                           formatter_and_linter                                   
+  # -------------------------------------------------------------------------- 
+  formatter_and_linter:
+    runs-on: ubuntu-24.04
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: install pypi-packaged dependencies
+      run: sudo pip3 install black ruff
+    - name: run formatter
+      run: black . --check
+    - name: run linter
+      run: ruff check src/raspy2mqtt/
+    
+  # -------------------------------------------------------------------------- 
+  #                                   tests                                   
+  # -------------------------------------------------------------------------- 
+  tests:
+    runs-on: ubuntu-24.04
+
+    steps:
+    - uses: actions/checkout@v4
+
+    # testcontainers 4.6.0 has introduced the MosquittoContainer, see
+    # https://github.com/testcontainers/testcontainers-python/releases/tag/testcontainers-v4.6.0
+    - name: install pypi-packaged dependencies for unit and integration tests
+      run: sudo pip3 install pytest 'testcontainers>=4.6.0' paho-mqtt aiomqtt schema
+
+    # FIXME: we should have all dependencies centralized in the TOML file and install them as:
+    # - name: Install dependencies
+    #   run: |
+    #     poetry install --no-interaction --with dev --all-extras
+    #     poetry show --tree
+
+    - name: run unit tests
+      run: pytest -vvv -m unit
+
+    - name: build docker image
+      run: docker build -t rpi2home-assistant:latest .
+    - name: run integration tests
+      run: pytest -vvv --capture=no -m integration

rpi2home_assistant-2.3.0/.github/workflows/pypi-release.yml

@@ -0,0 +1,51 @@
+name: pypi-release
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+
+    # setup python
+    - uses: actions/checkout@v4
+    - name: set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+    - name: install pypa/build
+      run: >-
+        python3 -m
+        pip install build --user
+    
+    # package & store artifacts
+    - name: package the pypi
+      run: |
+        python3 -m build
+    - name: store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+  
+  publish-to-pypi:
+    # only publish to PyPI on tag pushes
+    if: startsWith(github.ref, 'refs/tags/')
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/r/rpi2home-assistant
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

rpi2home_assistant-2.3.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+src/raspy2mqtt/__pycache__/
+tests/__pycache__/
+
+# autogenerated by hatch-vcs:
+src/_raspy2mqtt_version.py

rpi2home_assistant-2.3.0/Dockerfile

@@ -0,0 +1,30 @@
+# Stage 1: the builder
+FROM python:3.11-slim AS builder
+
+# NOTE: git is required to get the "hatch-vcs" plugin to work and produce the _raspy2mqtt_version.py file
+RUN apt update && apt install -y git
+
+WORKDIR /build
+COPY requirements.txt pyproject.toml README.md /build/
+ADD ./src ./src/
+COPY ./.git ./.git/
+
+RUN python -m pip install --upgrade pip
+RUN pip install --target=/build/deps -r requirements.txt
+RUN pip install build
+RUN python -m build --wheel --outdir /build/wheel
+
+
+# Stage 2: Create the final image
+FROM python:3.11-slim
+
+LABEL org.opencontainers.image.source=https://github.com/f18m/rpi2home-assistant
+
+# install the wheel
+WORKDIR /app
+COPY --from=builder /build/wheel/*.whl .
+RUN pip3 install --no-cache-dir *.whl
+
+ENV PYTHONUNBUFFERED=1
+ENTRYPOINT [ "raspy2mqtt" ]
+

rpi2home_assistant-2.3.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Francesco Montorsi
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

rpi2home_assistant-2.3.0/Makefile

@@ -0,0 +1,136 @@
+#
+# This Makefile can be used to install this project on a Raspbian OS.
+# The specifics of Raspbian OS are that:
+#  * pip3 install <module-name> will not work and fail with msg:
+#     "error: externally-managed-environment [...]"
+#
+# So this makefile takes care of automating
+#  * creation of venv
+#  * installation of this project into that venv
+#  * distribution of config file in standard system folders
+#
+
+SHELL = /bin/bash
+
+ifeq ($(BINDEST),)
+BINDEST=/root
+endif
+ifeq ($(CFGDEST),)
+CFGDEST=/etc
+endif
+ifeq ($(SYSTEMDUNITDEST),)
+SYSTEMDUNITDEST=/lib/systemd/system/
+endif
+ifeq ($(CONFIG_FILE_FOR_DOCKER),)
+# NOTE: please override this with a config file containing a valid MQTT broker config
+CONFIG_FILE_FOR_DOCKER=$(shell pwd)/tests/integration-test-config.yaml
+endif
+
+all: build-wheel lint test
+
+#
+# TARGETS FOR DEPLOYING ON RaspBian
+#
+
+raspbian_install:
+	# check OS version
+	@if [[ `lsb_release -i -s 2>/dev/null` != "Raspbian" && `lsb_release -i -s 2>/dev/null` != "Debian" ]] || (( `lsb_release -r -s 2>/dev/null` < 12 )); then \
+		echo ; \
+		echo "** WARNING **" ; echo "THIS SOFTWARE HAS BEEN TESTED ONLY ON RASPBIAN 12 OR HIGHER AND REQUIRES PYTHON3.11" ; \
+		echo "CHECK IF THIS DISTRIBUTION IS OK... PROCEEDING BUT EXPECT ERRORS" ; \
+		echo ; \
+	else \
+		echo "Your operating system seems to be OK for rpi2home-assistant" ; \
+	fi
+	# install python venv
+	python3 -m venv $(BINDEST)/rpi2home-assistant-venv
+	$(BINDEST)/rpi2home-assistant-venv/bin/pip3 install .
+	# install app config (only if MISSING, don't overwrite customizations)
+	@if [[ -f $(CFGDEST)/rpi2home-assistant.yaml ]]; then \
+		echo "WARNING: a configuration file already exists; copying the updated one with .new suffix" ; \
+		cp -av config.yaml $(CFGDEST)/rpi2home-assistant.yaml.new ; \
+	else \
+		cp -av config.yaml $(CFGDEST)/rpi2home-assistant.yaml ; \
+	fi
+	# install systemd config
+	chmod 644 systemd/*.service
+	cp -av systemd/*.service $(SYSTEMDUNITDEST)/
+	systemctl daemon-reload
+
+raspbian_enable_at_boot:
+	systemctl enable rpi2home-assistant.service
+	# this is assuming that the Debian package "pigpiod" is already installed:
+	systemctl enable pigpiod.service
+
+raspbian_start:
+	systemctl start rpi2home-assistant.service
+	systemctl start pigpiod.service
+
+raspbian_show_logs:
+	journalctl -u rpi2home-assistant
+
+raspbian_update_dependencies:
+	$(BINDEST)/rpi2home-assistant-venv/bin/pip3 install --upgrade .
+
+raspbian_uninstall:
+	@rm -fv $(SYSTEMDUNITDEST)/rpi2home-assistant.service
+	systemctl daemon-reload
+	@echo "Considering deleting also:"
+	@echo " $(CFGDEST)/rpi2home-assistant.yaml/*"
+	@echo " $(BINDEST)/rpi2home-assistant-venv"
+
+#
+# TARGETS FOR DEVELOPMENT
+#
+
+docker:
+	docker build -t rpi2home-assistant:latest .
+
+run-docker:
+	@if [ ! -f $(CONFIG_FILE_FOR_DOCKER) ]; then \
+		echo "Could not find the config file $(CONFIG_FILE_FOR_DOCKER) to mount inside the docker... please specify a valid config file with CONFIG_FILE_FOR_DOCKER option." ; \
+		exit 3 ; \
+	fi
+	docker run --rm -ti --env DISABLE_HW=1 --network=host \
+		-v $(CONFIG_FILE_FOR_DOCKER):/etc/rpi2home-assistant.yaml \
+		rpi2home-assistant:latest
+
+run-mosquitto:
+	docker run -d --publish 1883:1883 \
+		--volume $$(pwd)/tests/integration-test-mosquitto.conf:/mosquitto/config/mosquitto.conf \
+		eclipse-mosquitto:latest
+
+test: unit-test integration-test
+
+unit-test:
+ifeq ($(REGEX),)
+	pytest -vvv --log-level=INFO -m unit
+else
+	pytest -vvvv --log-level=INFO -s -m unit -k $(REGEX)
+endif
+
+# NOTE: during integration-tests the "testcontainers" project will be used to spin up 
+#       both a Mosquitto broker and the rpi2home-assistant docker, so make sure you don't
+#       have a Mosquitto broker (or other containers) already listening on the 1883 port
+#       when using this target:
+integration-test:
+ifeq ($(REGEX),)
+	pytest -vvvv --log-level=INFO -s -m integration
+else
+	pytest -vvvv --log-level=INFO -s -m integration -k $(REGEX)
+endif
+
+build-wheel:
+	python3 -m build --wheel --outdir dist/
+
+test-wheel:
+	rm -rf dist/ && \
+ 		pip3 uninstall -y rpi2home-assistant && \
+		$(MAKE) build-wheel && \
+		pip3 install dist/rpi2home_assistant-*py3-none-any.whl
+
+format:
+	black .
+
+lint:
+	ruff check src/raspy2mqtt/

rpi2home_assistant-2.3.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: rpi2home-assistant
+Version: 2.3.0
+Summary: Raspberry PI to Home Assistant bridge through MQTT for wired sensors/actuators
+Project-URL: Homepage, https://github.com/f18m/rpi2home-assistant
+Project-URL: Bug Tracker, https://github.com/f18m/rpi2home-assistant/issues
+Author-email: Francesco Montorsi <francesco.montorsi.nospam@gmail.com>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Dist: aiomqtt==2.4.0
+Requires-Dist: gpiozero==2.0.1
+Requires-Dist: pigpio==1.78
+Requires-Dist: pyyaml==6.0.2
+Requires-Dist: schema==0.7.7
+Requires-Dist: sm16inpind==1.0.1
+Description-Content-Type: text/markdown
+
+# rpi2home-assistant
+
+This project provides a Python daemon to **transform a [Raspberry PI](https://www.raspberrypi.com/) 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](https://www.home-assistant.io/integrations/binary_sensor.mqtt/);
+* 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](https://www.home-assistant.io/integrations/binary_sensor.mqtt/);
+* expose Raspberry GPIO output pins in Home Assistant as [switches](https://www.home-assistant.io/integrations/switch.mqtt/) or as [buttons](https://www.home-assistant.io/integrations/button.mqtt/) 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](https://www.home-assistant.io/)-friendly fashion.
+For example, this utility requires **no configuration on Home Assistant-side** thanks to [MQTT discovery messages](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery) 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):
+
+![Home Assistant screenshot](/docs/screenshot1.png?raw=true "Home Assistant screenshot")
+
+
+# Prerequisites
+
+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](/docs/seq-microsystem-optoisolated-hat.png?raw=true "Sequent Microsystem 16 opto-insulated inputs HAT")
+
+* [Sequent Microsystem 16 opto-insulated inputs HAT](https://sequentmicrosystems.com/collections/all-io-cards/products/16-universal-inputs-card-for-raspberry-pi). 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.
+
+<!--
+Note that Sequent Microsystem board is connecting the pin 37 (GPIO 26) of the Raspberry Pi 
+to a pushbutton. This software monitors this pin, and if pressed for more than the
+desired time, issues the shut-down command to the Raspberry PI board.
+-->
+
+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:
+
+![SeenGreat 2CH output opto-insulated relay HAT](/docs/seengreat-2ch-relay.png?raw=true "SeenGreat 2CH output opto-insulated relay HAT")
+
+* [SeenGreat 2CH output opto-insulated relay HAT](https://seengreat.com/wiki/107/).
+
+![Sunfounder 4CH output opto-insulated relay HAT](/docs/sunfounder-4ch-relay.png?raw=true "Sunfounder 4CH output opto-insulated relay HAT")
+
+* [Sunfounder 4 Channel 5V Relay Module](http://wiki.sunfounder.cc/index.php?title=4_Channel_5V_Relay_Module).
+
+
+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](https://www.raspberrypi.com/software/operating-systems/) 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.
+
+# Documentation
+
+## How to install on a Raspberry Pi with Debian Bookworm 12
+
+The [Raspberry Pi OS](https://www.raspberrypi.com/software/operating-systems/) 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](#prerequisites) section). 
+
+## Configuration file
+
+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](config.yaml) for 
+the full documentation of the configuration options.
+
+## Permissions
+
+This python code needs to run as `root` due to ensure access to the Raspberry I2C and GPIO peripherals.
+
+## Logs
+
+After starting the application you can verify from the logs whether it's running successfully:
+
+```
+journalctl -u rpi2home-assistant --since="5min ago"
+```
+
+## Deploy/test with Docker
+
+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).
+
+
+# Development
+
+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
+```
+
+
+
+# Useful links
+
+* [Sequent Microsystem 16 opto-insulated inputs python library](https://github.com/SequentMicrosystems/16inpind-rpi)
+* [aiomqtt python library](https://github.com/sbtinstruments/aiomqtt)
+* [AsyncIO tutorial](https://realpython.com/python-concurrency/#asyncio-version)
+* [Home Assistant](https://www.home-assistant.io/)
+
+Very similar project, more flexible and much bigger, targeting specific sensor boards:
+* [mqtt-io](https://github.com/flyte/mqtt-io)
+
+
+# TODO
+
+- 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?