Welcome to Juham™ documentation!¶

Welcome to Juham™ - Juha’s Ultimate Home Automation Masterpiece¶
Project Status¶
Current State: Pre-Alpha (Status 2) In its current form, Juham™ may still resemble more of a home automation experiment (or even a “mess”) than a “masterpiece,” but I’m actively developing it to reach that goal!
Please check out the CHANGELOG file for changes in this release.
Goals¶
The aim of Juham™ is to develop a robust home automation framework capable of controlling all the devices in my home, with the potential to be adapted for other homes as well.
Getting Started¶
### Installation
Install Juham™ core functionality:
pip install juham
This will install the basic framework needed to get started.
Explore the available features and install any additional modules you require. For example, to add weather forecasting plugins:
pip install juham_visualcrossing pip install juham_openweathermap
Set up InfluxDB 3.0 and Grafana Cloud. These services are optional, but I strongly recommend using them to monitor your home remotely. Juham™ can function without them, but visualizing and recording data greatly enhances the system’s capabilities.
Configure Juham™. This involves a two-step process:
Step 1: Initialize the configuration by running:
juham --init
This will generate JSON configuration files in your home directory at
~/.juham/config/*
.Step 2: Edit the following configuration files to fit your setup:
Base.json
: Provide your MQTT host and port information.JDatabase.json
: Enter your InfluxDB account details.RVisualCrossing.json
: Add your Visual Crossing API key for weather forecasts.Shelly*.json
: If you have Shelly devices, configure them here.
Perform a test run of Juham™ without the
--init
argument to check for any errors:juham
If the system runs smoothly, you can set up
juham
as a service to run continuously.
Tailoring to Your Home¶
Every home is unique, and Juham™ serves as a customizable starting point for building your own home automation system.
Special Thanks¶
This project would not have been possible without the generous support of two exceptional individuals: my friend, Teppo K., and my son, Mahi.
Teppo provided the initial spark for this project by donating a Raspberry Pi, a temperature sensor, and an inspiring demonstration of his own home automation system.
My son Mahi has been instrumental in translating my ideas into Python code, offering invaluable support and encouragement throughout the development process.
I am deeply grateful to both of you — thank you!
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.0.11] - December 08, 2024¶
Masterpiece-0.1.4: updated and tested for the new masterpiece stable-0.1.4 release.
Type-hinting: completed, py.typed file added.
OpenWeatherMap and VisualCrossing pluginized: Classes removed and implemented as separate plugin modules.
[0.0.10] - October 20, 2024¶
README, CHANGELOG: pyproject.toml still referenced these assuming they where in Sphinx’s docs/source folder. Fixed.
Time Module Added: The methods ‘timestamp()’, ‘quantize()’ and a few others moved from the ‘Masterpiece’ framework to the ‘Juham’ framework, where time management is an essential feature. See ‘juham.base.time’.
[0.0.9] - October 20, 2024¶
README, CHANGELOG: pyproject.toml still referenced these assuming they where in Sphinx’s docs/source folder. Fixed.
Time Module Added: The methods ‘timestamp()’, ‘quantize()’ and a few others moved from the ‘Masterpiece’ framework to the ‘Juham’ framework, where time management is an essential feature. See ‘juham.base.time’.
[0.0.8] - October 20, 2024¶
Docs folder refactored: this CHANGELOG and other standard files e.g. README moved into the root directory, for GitLab compatibility.
[0.0.5] - July 30, 2024¶
register_topic() and valid_topic() methods moved into JMqtt class, where they belong, for proper object-oriented design.
Added another Shelly Plus 1 device into the myhome.py to control the heating contactor of the hot water boiler.
[0.0.4] - July 23, 2024¶
The cls.initialize_class() method now accepts a boolean parameter to control whether the class attempts to initialize its attributes from the configuration file. The default value is True. This update eliminates the need to create a configuration file for classes whose attributes are fully determined by other means, such as being c onfigured by another class.
The on_message() method parameter has been typed to eliminate errors with linters.
The Base class now imports MQTTMessage as MqttMsg. This is a temporary solution, but it moves the code closer to a proper abstraction that allows any MQTT implementation to be plugged in.
The LogRecord class has been registered for recording application events, such as warnings and errors, to a time series database.
Additional classes have been documented, albeit to varying degrees.
Mqtt class introduces topic registration feature, where classes that introduce new topics can register them as known valid topics. All calls to subscribe() and publish() methods check if the topic in question is registered as valid known topic. If not ValueError exception is thrown.
RVisualCrossing class reports an error if the APIKEY needed to acquire weather forecast data has not been configured in its “config/RVisualCrossing.json” file.
[0.0.3] - June 29, 2024¶
Bug fixes:
Setup issue: 0.0.2 required Python 3.12 for type hinting, and for _class_id : str| None = None to work. As all my attempts to upgrade my workstations to use the new python to 3.12 failed miserably, code base reverted back to Python 3.8.
Wrong signature of JApp.configure(), fixed.
JApp.register() comparison if cls.get_class_id == None fixed to if cls.get_class_id() is None
Several == None comparisons changed to ‘ is None’ to make pylint happy (need to figure out what this is about)
wrong import ordering fixed to satisfy pylint (built-in packages first, 3rd party next, juham last)
Bug in acquiring solar energy forecast from Visual Crossing fixed.
[0.0.2] - June 21, 2024¶
Key updates include:
Extended Shelly device support to include the ‘Shelly Motion Sensor’, which helps determine if anyone is at home and controls the hot water circulator pump accordingly.
Implemented several simulation classes for testing environments without actual sensor data:
Shelly Motion Sensor Simulator
Shelly Plus 1 Simulator
Replaced the Doxygen (C++) documentation tool with Python’s native Sphinx.
Fully implemented the plugin architecture; all existing classes are now genuine plugins, even though they are deployed in a single package.
Introduced a serialization system based on JSON format.
Reformatted Python code using the ‘black’ code formatter.
Automated class initialization e.g. calling of cls.load_json() and atexit.register() methods upon import.
Shortened long imports (e.g., from juham.shelly.jshellymotion import ShellyMotion) using __init__.py, resulting in cleaner imports (e.g., from juham.shelly import ShellyMotion).
Updated filename and classname conventions from C-style to Pythonic (e.g., JShellyMotion to ShellyMotion).
Added support for multiple configurations via startup arguments: –configuration-folder [path]. This allows running the same automation app on different sites or for various purposes (e.g., production, testing).
Started transition to Python type annotations. Installed mypy and wooah, I’w missed type checking so much!
Adopted f-string convention, e.g. self.log(f”Forecast for {days} days acquired”).
UML class diagrams.
[snip]
[0.0.1] - May 23, 2024¶
Private in-house releases, not published to the Python repository — for everyone’s sake.
Added support for more devices:
Shelly PRO Energy Meter
HomeWizard Water Meter
Introduced the class factory method pattern.
Added class-specific JSON configuration files, allowing automation classes to be configured instead of hardcoding settings in Python.
More refined class hierarchy, for minimizing code/functionality ratio.
First unit tests added
[snip]
[0.0.0] - May 21, 2024¶
Initial release featuring:
A functioning system
Some unconventional use of the Python programming language
Mosquitto MQTT via Paho
InfluxDB V3 time series recording
Python package installable via pip, based on pyproject.toml
MIT license
README, CHANGELOG, and other standard files in .rst format
A cool project name, ‘Juham™’, with a note: M currently stands for mission rather than masterpiece
Initial support for Shelly WiFi relays with temperature sensors
Some docstrings and related developer documentation generated with Doxygen
TODOs for Juham™¶
An exceptionally well structured and priorized list of TODOs for Juham™
Automation¶
- [_] 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.
[_] …
Python¶
[X] Class registration methods have to call cls.load_json() and atexit.register() methods, could this be automated?
[X] Long imports e.g. juham.shelly.jshellymotion import JShellyMotion?
[_] Major design decision: continue with the current multi-threading architecture (which Python currently does not really support well), or move to multi-processing or asyncio instead?
[_] Python type annotations (type hinting).
Design¶
[_] Decouple threads and functionality: any task should be runnable by a thread, an external process (perhaps run via cron), or by using an async IO approach.
[_] 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¶
[X] Replace the current Doxygen (C++) with some native python documentation too e.g. Sphinx?
[_] Extract FIXME and TODO inline comments from the source code with the autogenerated Sphinx docs
[_] Design and integrate a distinctive and highly professional Juham™ look with an outstanding logo and other graphics.
[_] …
Testing¶
[X] Support multiple configurations via startup arguments (one for testing, one for real)
[_] Write unit tests for all classes
[_] Mocking (e.g. unittest.mock?)
Inline TODO¶
The following items have been extraced from the source code:
Todo
TBA
(The original entry is located in ../CONTRIBUTING.rst, line 43.)
Todo
rewrite to meet the architecture and design patterns.
(The original entry is located in C:\Users\juham\juham\juham\automation\rpowerplan.py:docstring of juham.automation.rpowerplan.RPowerPlan, line 5.)
Todo
introduce general algorithm for managing any number of any consumers.
(The original entry is located in C:\Users\juham\juham\juham\automation\rpowerplan.py:docstring of juham.automation.rpowerplan.RPowerPlan, line 6.)