rpi2home-assistant 2.3.0__py2.py3-none-any.whl

rpi2home_assistant-2.3.0.dist-info/METADATA

@@ -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?

rpi2home_assistant-2.3.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+_raspy2mqtt_version.py,sha256=fpc6pwpIb6e3qF1WOyVnbUkHq-QnCDr_IHqJobzPyaw,18
+raspy2mqtt/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+raspy2mqtt/circular_buffer.py,sha256=Tai1vZVy283WVsfeEU190cmIY3nn8ZiXgl8IsyaE1rk,5161
+raspy2mqtt/config.py,sha256=UQLUc_xN6I7F2TLqmriTeanHvj5u_UaGiQjP0vLIqJ0,29076
+raspy2mqtt/constants.py,sha256=LBLFJ41AIoerpWVhk3ras57g8bwPn-e32CFBGzMIwHc,2478
+raspy2mqtt/gpio_inputs_handler.py,sha256=aWYz0PfR02GZ13voYbm7FrVdRJww6hPnPbIgaACMGTY,6851
+raspy2mqtt/gpio_outputs_handler.py,sha256=56E2gZvgVrkY9DSZUv5TuZvj-8bK-WYNMDfoWRWNYZs,15052
+raspy2mqtt/homeassistant_status_tracker.py,sha256=Lhbiy7T1FFubrzoCxtjhs4PvjZ3j4xwpF-VZaenWSCA,4323
+raspy2mqtt/main.py,sha256=B3tiXsGre7zOR_nh7CTASLX1tHzdMUszDplWZy3cCbM,10306
+raspy2mqtt/optoisolated_inputs_handler.py,sha256=i5agFjU-oztyCoqocFc8dOGGbWMeQfcGPG0FVCArYOo,13802
+raspy2mqtt/stats.py,sha256=djerxFpBI-u5ou5-IKxfXue6V0A35L-Mw9b1RZKzFfI,1806
+rpi2home_assistant-2.3.0.dist-info/METADATA,sha256=IbxcBzt9ZWnvXJGMQW34MojQ1PXPO-L8Mp_bBZx66CI,9211
+rpi2home_assistant-2.3.0.dist-info/WHEEL,sha256=tkmg4JIqwd9H8mL30xA7crRmoStyCtGp0VWshokd1Jc,105
+rpi2home_assistant-2.3.0.dist-info/entry_points.txt,sha256=09rc8Ngm8K0OG9S2gnHpF0GOI_BP4kjzY8MwpFAIGGE,58
+rpi2home_assistant-2.3.0.dist-info/licenses/LICENSE,sha256=LNCMmwHYhpNMgfJd8r5KzZrf5Sqv2OsOOrQ39Jzahf8,1505
+rpi2home_assistant-2.3.0.dist-info/RECORD,,

rpi2home_assistant-2.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any

rpi2home_assistant-2.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+raspy2mqtt = raspy2mqtt.main:entrypoint

rpi2home_assistant-2.3.0.dist-info/licenses/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.