Welcome to Juham™ documentation!¶

Contents:
Welcome to Juham™ - Juha’s Ultimate Home Automation Masterpiece¶
Project Description¶
This package extends the juham_core
package, providing home automation building blocks that cover most common needs.
It consists of two main sub-modules:

automation
spothintafi: Acquires electricity prices in Finland.
watercirculator: Automates a water circulator pump based on hot water temperature and motion detection.
hotwateroptimizer: 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.
ts
This folder contains time series recorders that listen for Juham™ topics and store the data in a time series database for later inspection.
Project Status¶
Current State: Pre-Alpha (Status 2)
All classes have been tested to some extent, and no known bugs have been reported. However, the code still requires work in terms of design and robustness. For instance, electricity prices are currently hard-coded to use euros, but this should be configurable to support multiple currencies.
Special Thanks¶
This project would not have been possible without the generous support of two exceptional individuals: Teppo K. and Mahi.
Teppo K. provided the initial spark for this project by donating a Raspberry Pi, a temperature sensor, and giving an inspiring demonstration of his own home automation system—effectively dragging me down the rabbit hole of endless tinkering.
Mahi has been instrumental in translating my half-baked ideas into Python code, offering invaluable support and encouragement—while also ensuring that every time I thought I was done, I wasn’t.
Because of these two gentlemen, my already minimal spare time dropped into the negatives as I desperately tried to push the system to some semblance of professionalism.
I’m truly grateful to both—really. 😅
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. **
Contributing to Juham™ - Juha’s Ultimate Home Automation Masterpiece¶
Thank You!¶
Thank you in advance for your forthcoming contributions, whether they are bug fixes, documentation improvements, entirely new features, or simply feedback. Your efforts will be highly appreciated and will help turn this project from its current mission state into an actual masterpiece.
Design Patterns¶
Please read the developer documentation and understand the few design patterns behind Juham™ before contributing. This will help ensure that your contributions align with the project’s design and goals. .. todo:: (okay, the documentation is currently lacking many essential chapters, add.)
Code Formatting¶
To help maintain consistent code formatting across different developers, we use ‘black’ python formatter, by Microsoft.
Strange, the formatter doesn’t seem to format that much, it doesn’t organize imports, doesn’t adjust docstring lenghts .. todo:: most likely I don’t know how to use it properly, read the docs.
Using Emacs and Makefile¶
Despite my attempts to fall in love with Eclipse, VSCode and other IDEs, I still find Emacs and Makefile the best tools for many workflows. So there is a Makefile in the root folder. For those old dogs who are like me
make help
More Stuff¶
Todo
TBA
Changelog¶
[0.1.8] - February23, 2025¶
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.
[0.1.7] - February 08, 2025¶
Initial release for GitLab. Pre-alpha!
TODOs for Juham™¶
Well structured and priorized list of TODOs for Juham™
Automation¶
[ ] Configurable units
- [_] Feature to optimize the balance between solar power production and electricity consumption to minimize costs
associated with electricity transmission.
[_] Support for the current 1-Hour, and the forthcoming 15-Minute Imbalance Settlement Period
- [_] Bought five small solar panel elements, capable to produce electricity up to 5 volts. This could be used as a
real time solar radiation sensor with Shelly Plus 1 wifi relay.
Design¶
[_] Support for MQTT password, encrypted in the .json configuration file, for security.
[_] Simulation classes for essential data sources, for development, testing, and demonstration purposes.
Documentation¶
[_] Design and integrate a distinctive and highly professional Juham™ look with an outstanding logo and other graphics.
Testing¶
[_] Write unit tests for all classes
Inline TODO¶
The following items have been extraced from the source code.
Todo
TBA
(The original entry is located in ../CONTRIBUTING.rst, line 43.)