juham-automation 0.0.17__tar.gz → 0.2.7__tar.gz

{juham_automation-0.0.17 → juham_automation-0.2.7}/LICENSE.rst

@@ -1,25 +1,25 @@
-LICENSE
-=======
-
-Copyright (c) 2024, Juha Meskanen
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
- 
-**The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.**
-
- 
-** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. **
-
+LICENSE
+=======
+
+Copyright (c) 2024, Juha Meskanen
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+ 
+**The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.**
+
+ 
+** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. **
+

{juham_automation-0.0.17 → juham_automation-0.2.7}/MANIFEST.in

@@ -1,12 +1,12 @@
-include docs/source/README.rst
-include docs/source/CHANGELOG.rst
-include docs/source/LICENSE.rst
-include docs/source/CONTRIBUTING.rst
-
-recursive-include examples *
-recursive-include tests *
-recursive-include docs/build/html *
-
-# files to be excluded
-global-exclude *~ \#*
-config/*
+include docs/source/README.rst
+include docs/source/CHANGELOG.rst
+include docs/source/LICENSE.rst
+include docs/source/CONTRIBUTING.rst
+
+recursive-include examples *
+recursive-include tests *
+recursive-include docs/build/html *
+
+# files to be excluded
+global-exclude *~ \#*
+config/*

juham_automation-0.2.7/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: juham-automation
+Version: 0.2.7
+Summary: Juha's Ultimate Home Automation Masterpiece
+Author-email: J Meskanen <juham.api@gmail.com>
+Maintainer-email: "J. Meskanen" <juham.api@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/juham/juham/juham-automation
+Project-URL: Bug Reports, https://gitlab.com/juham/juham/juham-automationt
+Project-URL: Funding, https://meskanen.com
+Project-URL: Say Thanks!, http://meskanen.com
+Project-URL: Source, https://gitlab.com/juham/juham/juham-automation
+Keywords: home,automation,juham
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development
+Classifier: Programming Language :: Python :: 3.8
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.rst
+Requires-Dist: juham_core>=0.2.4
+Provides-Extra: dev
+Requires-Dist: check-manifest; extra == "dev"
+Requires-Dist: coverage>=7.0; extra == "dev"
+Dynamic: license-file
+
+Welcome to Juham™ - Juha's Ultimate Home Automation Masterpiece
+===============================================================
+
+Project Description
+-------------------
+
+Beyond its super-cool name, this package provides essential home automation building blocks that address most common needs.
+
+It consists of two main sub-modules:
+
+``automation``:
+
+This folder contains automation classes that listen to Juham™ MQTT topics and control various home automation tasks.
+
+- **spothintafi**: Acquires electricity prices in Finland.
+- **watercirculator**: Automates a water circulator pump based on hot water temperature and motion detection.
+- **heatingoptimizer**: Controls hot water radiators based on temperature sensors and electricity price data.
+- **energycostcalculator**: Monitors power consumption and electricity prices, and computes the energy balance in euros.
+- **energybalancer**: Handles real-time energy balancing and net billing.
+
+``ts``:
+
+This folder contains time series recorders that listen for Juham™ topics and store the data in a time series database for later inspection.
+
+- **electricityprice_ts** : publishes electricity prices to timeseries database.
+- **energybalancer_ts**: for monitoring the operation of energy balancer.
+- **energycostcalculator_ts**: publishes actualized energy prices per hour and per day.
+- **forecast_ts**: publishes the forecast datat to timeseries database.
+- **log_ts**: Writes log events to timeseries datbase.
+- **powerplan_ts**: publishes power plan data to timeseries database, when relays are planned to be switched on/off.
+- **powermeter_ts**: publishes powermeter data to timeseries database.
+
+
+Project Status
+--------------
+
+**Current State**: **Beta (Status 4)**
+
+All classes have been tested to some extent, and no known bugs have been reported. 
+
+
+Project Links
+-------------
+
+- **Source code:** https://gitlab.com/juham/juham/juham-automation
+- **Issue tracker:** https://gitlab.com/juham/juham/juham-automation/-/issues
+- **Documentation:** https://juham-automation-c6383e.gitlab.io
+- **PyPI page:** https://pypi.org/project/juham-automation
+
+  
+
+Features
+--------
+
+**HeatingAutomater** listens to the power meter to compute the net energy balance.
+
+  .. image:: _static/images/juham_powermeter.png
+     :alt: Powermeter
+     :width: 400px
+
+  Powermeter is needed to measure the real-time energy consumption
+
+
+**Energy Revenue** is computed based on the electricity price and transmission costs. This is the total cost one has to pay for consuming energy.
+  
+  .. image:: _static/images/juham_energyrevenue.png
+     :alt: Energy Revenue
+     :width: 400px
+
+  Energy revenue per hour and per day
+
+
+**Real-time temperature** trends monitored by the **Shelly Plus Add-on** and **DS18B20** sensors
+  
+  .. image:: _static/images/juham_boilertemperatures.png
+     :alt: Energy Revenue
+     :width: 400px
+
+  Temperature time series.
+
+
+**Real-time humidity** trends monitored by the **Shelly Plus Add-on** and **DHT22** sensors
+  
+  .. image:: _static/images/juham_humiditysensors.png
+     :alt: Energy Revenue
+     :width: 400px
+
+  Relative humidity time series.
+
+
+  
+**Utilization Optimization Index**: The Utilization Optimization Index predicts the optimal hours for energy consumption by factoring in electricity prices, temperature, and forecasts for wind and solar energy. It identifies the best times to activate heating systems. The cheapest hours within the current period may be skipped if the solar forecast predicts free electricity in the next period.period.
+
+  .. image:: _static/images/juham_uoi.png
+     :alt: Power Plan
+     :width: 400px
+
+  UOI cast for heating the primary and sun pre-heating boilers for two types of solar panels and boilers: electric-based panels and solar thermal panels, which use water circulation. The primary one is electrically heated, while the secondary ‘pre-heating’ boiler is heated by the hot water from the solar thermal panels, or by electricity when there's a positive energy balance.
+
+
+**Power Plan** is computed for the next 12 hours based on the electricity price and solar energy forecast. If no solar energy is available, the power plan determines power consumption, e.g., when the hot water radiators are enabled.
+
+  .. image:: _static/images/juham_powerplan.png
+     :alt: Power Plan
+     :width: 400px
+
+  Powerplan optimizing consumers to use the cheapest hours
+
+
+**Energy Balancer**: When the energy balance is positive (e.g., when solar panels produce more energy than is currently being consumed), the energy balancer is activated. It monitors the energy balance in 15-minute (or one-hour) intervals and computes when a consumer with a specific power demand should be activated to consume all the energy produced so far.
+
+  .. image:: _static/images/juham_automation_energybalancer.png
+     :alt: Energy Balancer
+     :width: 400px
+
+  Energy balancer activating consumers based on the actual real-time net energy
+
+
+**Power Diagnosis**: All controlled relays are monitored to ensure their correct operation. This ensures that relays are enabled according to the power plan and energy balancer commands.
+
+  .. image:: _static/images/juham_automation_relays.png
+     :alt: Relays
+     :width: 400px
+
+  The operation of the relays for diagnosis.
+
+
+Installing
+----------
+
+Juham™ ships with a minimal yet fully functional home automation application that can be found in the **examples** folder.
+It creates a **PowerMeterSimulator** and **ShellyMotionSimulator** objets to generate simulated motion sensor and power meter readings.
+Later, you can replace it with your actual power meter, as well as plug in other input sensors to read and relays to control.
+
+1. Set up a Mosquitto MQTT broker service. For more information read the manuals.
+
+   .. code-block:: bash
+
+      sudo apt install mosquitto mosquitto-clients
+
+2. Configure Juham to talk to Mosquitto.
+
+   In ``PahoMqtt.json``:
+
+   .. code-block:: json
+
+      {"paho_version" : 2}
+
+   In ``Juham.json``:
+
+   .. code-block:: json
+
+      {"mqtt_class_id": "PahoMqtt", "mqtt_root_topic": "myapp", "mqtt_host": "localhost", "mqtt_port": 1883}
+
+   In ``Timeseries.json``:
+
+   .. code-block:: json
+
+      {
+         "token": "your-influx-token",
+         "org": "your-organization",
+         "host": "https://us-east-1-1.aws.cloud2.influxdata.com",
+         "database": "your-database"
+      }
+
+3. In the ``juham/examples`` folder, run:
+
+   .. code-block:: bash
+
+      python3 myapp.py
+
+The application will start and time series data will show up in your InfluxDB database,
+which you can then visualize with tools such as Grafana.

juham_automation-0.2.7/README.rst

@@ -0,0 +1,173 @@
+Welcome to Juham™ - Juha's Ultimate Home Automation Masterpiece
+===============================================================
+
+Project Description
+-------------------
+
+Beyond its super-cool name, this package provides essential home automation building blocks that address most common needs.
+
+It consists of two main sub-modules:
+
+``automation``:
+
+This folder contains automation classes that listen to Juham™ MQTT topics and control various home automation tasks.
+
+- **spothintafi**: Acquires electricity prices in Finland.
+- **watercirculator**: Automates a water circulator pump based on hot water temperature and motion detection.
+- **heatingoptimizer**: Controls hot water radiators based on temperature sensors and electricity price data.
+- **energycostcalculator**: Monitors power consumption and electricity prices, and computes the energy balance in euros.
+- **energybalancer**: Handles real-time energy balancing and net billing.
+
+``ts``:
+
+This folder contains time series recorders that listen for Juham™ topics and store the data in a time series database for later inspection.
+
+- **electricityprice_ts** : publishes electricity prices to timeseries database.
+- **energybalancer_ts**: for monitoring the operation of energy balancer.
+- **energycostcalculator_ts**: publishes actualized energy prices per hour and per day.
+- **forecast_ts**: publishes the forecast datat to timeseries database.
+- **log_ts**: Writes log events to timeseries datbase.
+- **powerplan_ts**: publishes power plan data to timeseries database, when relays are planned to be switched on/off.
+- **powermeter_ts**: publishes powermeter data to timeseries database.
+
+
+Project Status
+--------------
+
+**Current State**: **Beta (Status 4)**
+
+All classes have been tested to some extent, and no known bugs have been reported. 
+
+
+Project Links
+-------------
+
+- **Source code:** https://gitlab.com/juham/juham/juham-automation
+- **Issue tracker:** https://gitlab.com/juham/juham/juham-automation/-/issues
+- **Documentation:** https://juham-automation-c6383e.gitlab.io
+- **PyPI page:** https://pypi.org/project/juham-automation
+
+  
+
+Features
+--------
+
+**HeatingAutomater** listens to the power meter to compute the net energy balance.
+
+  .. image:: _static/images/juham_powermeter.png
+     :alt: Powermeter
+     :width: 400px
+
+  Powermeter is needed to measure the real-time energy consumption
+
+
+**Energy Revenue** is computed based on the electricity price and transmission costs. This is the total cost one has to pay for consuming energy.
+  
+  .. image:: _static/images/juham_energyrevenue.png
+     :alt: Energy Revenue
+     :width: 400px
+
+  Energy revenue per hour and per day
+
+
+**Real-time temperature** trends monitored by the **Shelly Plus Add-on** and **DS18B20** sensors
+  
+  .. image:: _static/images/juham_boilertemperatures.png
+     :alt: Energy Revenue
+     :width: 400px
+
+  Temperature time series.
+
+
+**Real-time humidity** trends monitored by the **Shelly Plus Add-on** and **DHT22** sensors
+  
+  .. image:: _static/images/juham_humiditysensors.png
+     :alt: Energy Revenue
+     :width: 400px
+
+  Relative humidity time series.
+
+
+  
+**Utilization Optimization Index**: The Utilization Optimization Index predicts the optimal hours for energy consumption by factoring in electricity prices, temperature, and forecasts for wind and solar energy. It identifies the best times to activate heating systems. The cheapest hours within the current period may be skipped if the solar forecast predicts free electricity in the next period.period.
+
+  .. image:: _static/images/juham_uoi.png
+     :alt: Power Plan
+     :width: 400px
+
+  UOI cast for heating the primary and sun pre-heating boilers for two types of solar panels and boilers: electric-based panels and solar thermal panels, which use water circulation. The primary one is electrically heated, while the secondary ‘pre-heating’ boiler is heated by the hot water from the solar thermal panels, or by electricity when there's a positive energy balance.
+
+
+**Power Plan** is computed for the next 12 hours based on the electricity price and solar energy forecast. If no solar energy is available, the power plan determines power consumption, e.g., when the hot water radiators are enabled.
+
+  .. image:: _static/images/juham_powerplan.png
+     :alt: Power Plan
+     :width: 400px
+
+  Powerplan optimizing consumers to use the cheapest hours
+
+
+**Energy Balancer**: When the energy balance is positive (e.g., when solar panels produce more energy than is currently being consumed), the energy balancer is activated. It monitors the energy balance in 15-minute (or one-hour) intervals and computes when a consumer with a specific power demand should be activated to consume all the energy produced so far.
+
+  .. image:: _static/images/juham_automation_energybalancer.png
+     :alt: Energy Balancer
+     :width: 400px
+
+  Energy balancer activating consumers based on the actual real-time net energy
+
+
+**Power Diagnosis**: All controlled relays are monitored to ensure their correct operation. This ensures that relays are enabled according to the power plan and energy balancer commands.
+
+  .. image:: _static/images/juham_automation_relays.png
+     :alt: Relays
+     :width: 400px
+
+  The operation of the relays for diagnosis.
+
+
+Installing
+----------
+
+Juham™ ships with a minimal yet fully functional home automation application that can be found in the **examples** folder.
+It creates a **PowerMeterSimulator** and **ShellyMotionSimulator** objets to generate simulated motion sensor and power meter readings.
+Later, you can replace it with your actual power meter, as well as plug in other input sensors to read and relays to control.
+
+1. Set up a Mosquitto MQTT broker service. For more information read the manuals.
+
+   .. code-block:: bash
+
+      sudo apt install mosquitto mosquitto-clients
+
+2. Configure Juham to talk to Mosquitto.
+
+   In ``PahoMqtt.json``:
+
+   .. code-block:: json
+
+      {"paho_version" : 2}
+
+   In ``Juham.json``:
+
+   .. code-block:: json
+
+      {"mqtt_class_id": "PahoMqtt", "mqtt_root_topic": "myapp", "mqtt_host": "localhost", "mqtt_port": 1883}
+
+   In ``Timeseries.json``:
+
+   .. code-block:: json
+
+      {
+         "token": "your-influx-token",
+         "org": "your-organization",
+         "host": "https://us-east-1-1.aws.cloud2.influxdata.com",
+         "database": "your-database"
+      }
+
+3. In the ``juham/examples`` folder, run:
+
+   .. code-block:: bash
+
+      python3 myapp.py
+
+The application will start and time series data will show up in your InfluxDB database,
+which you can then visualize with tools such as Grafana.

juham_automation-0.2.7/docs/source/CHANGELOG.rst

@@ -0,0 +1,191 @@
+Changelog
+=========
+
+[0.2.7] - December 1 2025
+-------------------------
+
+- LeakDetector migrated from juham-watermeter
+
+
+[0.2.6] - November 30 2025
+--------------------------
+
+- More agressive spot sensitivity.
+
+  
+
+[0.2.5] - 2025-11-21
+--------------------
+
+- Project development status elevated to **Beta**.
+- Added an electricity-forecast–aware heating algorithm:
+  If today's electricity price is high and tomorrow's is lower, the system
+  automatically reduces heating today to optimize cost.
+- Introduced **SupervisorThread**, responsible for:
+  - Detecting and listing crashed threads
+  - Logging failures
+  - Automatically restarting affected threads
+- Added a significant number of new unit tests to improve stability and
+  coverage.
+- Extracted **powermeter_simulator.py** into a separate simulation plugin
+  for cleaner architecture and modularity.
+
+  
+
+[0.1.13] - Nov 15, 2025
+-----------------------
+
+- Installation instructions added into README.rst
+- Failure in **ts/log_ts.py** logging method logged the failure, leading to Infinite logging loop. Fixed.
+
+
+[0.1.11] - Nov 11, 2025
+-----------------------
+
+- New heating plan attributes published to timeseries
+- Heating plan now includes flags indicating whether temperature and solar power forecasts were used.
+- Min and max temperature limits published with the powerplan.
+- Minor issues in docstrings fixed.
+- Unit tests updated to reflect new heating plan attributes.
+
+
+[0.1.5] - Nov 07, 2025
+----------------------
+
+- Heating plan optimization logic improved to better account for temperature and solar power forecasts.
+- Unit tests added for significantly higher coverage.
+- Documentation updated to reflect changes in temperature and solar power forecast handling.
+- SolarForecast and TemperatureForecast fields added to PowerPlan time series.
+
+
+
+[0.1.3] - Nov 01, 2025
+----------------------
+
+- Added support for arbitrary energy balancing intervals in the automation module. 
+- Default energy balancing interval changed from 1 hour to 15 minutes to comply with the new EU energy market directive.
+- Updated energy cost calculator and heating optimizer components to work with configurable intervals.
+- Improved unit tests to validate behavior across various interval lengths.
+
+
+
+[0.1.1] - Oct 28, 2025
+----------------------
+
+- Project status elevated from Pre-Alpha to Alpha.
+- The default energy balancing interval for **HeatingOptimizer** is now 15 minutes.
+- Added "converage" package to [project.optional-dependencies] in pyproject.toml
+
+
+
+[0.0.73] - Aug 30, 2025
+-----------------------
+
+- Default boiler temperature limits adjusted.
+
+
+[0.0.34] - May 02, 2025
+-----------------------
+
+- Weight attribute added to heatingoptimizer. Determines how large a share of the time slot 
+  a consumer receives compared to others.
+ 
+
+  
+[0.0.33] - May 01, 2025
+-----------------------
+
+- Workaround to Sphinx issue with multiply defined instance variables.
+
+
+[0.0.32] - April 27, 2025
+-------------------------
+
+* **HeatingOptimizer** single minimum and maximum temperature attributes replaced by a montly limits.
+  
+.. code-block:: python
+
+    pip install masterpiece_plugin
+    boiler.temperature_limits = {
+        1: (50, 68),  # January: colder, need hotter heating water
+        2: (50, 68),  # February
+        3: (50, 68),  # March
+        4: (40, 68),  # April
+        5: (30, 68),  # May
+        6: (30, 68),  # June: warmer, need less heating
+        7: (30, 68),  # July
+        8: (30, 68),  # August
+        9: (40, 68),  # September
+        10: (50, 68),  # October
+        11: (50, 68),  # November
+        12: (50, 68),  # December
+    }
+
+* **HeatingOptimizer** class attributes documented.
+
+
+
+[0.0.31] - April 21, 2025
+-------------------------
+
+* EnergyBalancer and EnergyBalancerTs classes improved. There is now two MQTT sub-topics: status,
+  for controlling consumers, and diagnostics for monitoring the operation of the energy balancer.
+
+
+[0.0.29] - April 20, 2025
+-------------------------
+
+* Bug fixes to EnergyBalancer.
+* PriceForecast class updated (not there yet)
+
+[0.0.28] - April 20, 2025
+-------------------------
+
+* EnergyBalancer logic improved. Instead of activating all consumers at the same time, it now activates them one at a time
+  in a serialized manner to minimize the maximum power (and fuse capacity, which affects the energy bill) required
+  during balancing cycles. 
+
+
+[0.0.27] - April 16, 2025
+-------------------------
+
+* CI pipeline unification.
+* EnergyBalacing features isolated from the HeatingOptimizer and implemented as a separate energybalancer module.
+
+
+
+[0.0.23] - April 04, 2025
+-------------------------
+* The HotWaterOptimizer class has been renamed to HeatingOptimizer to better reflect its general-purpose nature.
+* Added test_energybalancer.py
+* Added publish_diagnostics() method to track energy balance driven heating.
+* Added heatingoptimizer_ts module to support time series recording.
+* Fixed bug in net-energy balancing system.
+* Removed redundand dependencies in ``pyproject.toml``.
+* Enabled net energy balance feature.
+  
+
+[0.1.12] - March 03, 2025
+-------------------------
+
+* Updated for the new modularized ci-templates and docs
+* New unit tests written, for better coverage. Not nearly there yet.
+
+
+[0.1.8-10] - February 23, 2025
+------------------------------
+
+* Support for grid (network) prices and tax added.
+
+* Bug fix in the computation of the utilization optimization index: solar power was previously
+  given in kW, while radiator power was in W, which underestimated the effect of available solar power.
+
+* New attribute added to time series: GridCost (cost and tax per kWh)
+  
+
+
+[0.1.7] - February 08, 2025
+---------------------------
+
+Initial release for GitLab. Pre-alpha!
+