Metadata-Version: 2.1 Name: regenmaschine Version: 2024.3.0 Summary: A simple API for RainMachine sprinkler controllers Home-page: https://github.com/bachya/regenmaschine License: MIT Author: Aaron Bach Author-email: bachya1208@gmail.com Requires-Python: >=3.10,<4.0 Classifier: License :: OSI Approved :: MIT License Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.10 Classifier: Programming Language :: Python :: 3.11 Classifier: Programming Language :: Python :: 3.12 Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Programming Language :: Python :: Implementation :: PyPy Requires-Dist: aiohttp (>=3.8.0) Requires-Dist: certifi (>=2023.07.22) Requires-Dist: frozenlist (>=1.4.0,<2.0.0) Requires-Dist: typing-extensions (>=4.3.0,<5.0.0) Requires-Dist: yarl (>=1.9.2) Project-URL: Bug Tracker, https://github.com/bachya/regenmaschine/issues Project-URL: Changelog, https://github.com/bachya/regenmaschine/releases Project-URL: Repository, https://github.com/bachya/regenmaschine Description-Content-Type: text/markdown # 💧 Regenmaschine: A Simple Python Library for RainMachine™ [![CI][ci-badge]][ci] [![PyPI][pypi-badge]][pypi] [![Version][version-badge]][version] [![License][license-badge]][license] [![Code Coverage][codecov-badge]][codecov] [![Maintainability][maintainability-badge]][maintainability] Buy Me A Coffee `regenmaschine` (German for "rain machine") is a simple, clean, well-tested Python library for interacting with [RainMachine™ smart sprinkler controllers][regenmaschine]. It gives developers an easy API to manage their controllers over their local LAN or remotely via the RainMachine™ cloud. - [Remote Access Announcement](#remote-access-announcement-2022-06-26) - [Python Versions](#python-versions) - [Installation](#installation) - [Usage](#usage) - [Loading Controllers Multiple Times](#loading-controllers-multiple-times) - [Contributing](#contributing) # Remote Access Announcement (2022-06-26) On June 2, 2022, RainMachine announced a [Premium Services][rainmachine-premium] addition; under this new model, remote access is _only_ available to subscribers of these Premium Services. I do not currently intend to subscribe to Premium Services; as such, the remote access abilities of `regenmaschine` will remain as-is from here on out unless spurred on by others. They may stop working at any time. PRs from subscribing users are always welcome. # Python Versions `regenmaschine` is currently supported on: - Python 3.10 - Python 3.11 - Python 3.12 # Installation ```bash pip install regenmaschine ``` # Usage Creating a `regenmaschine` `Client` might be the easiest thing you do all day: ```python import asyncio from aiohttp import ClientSession from regenmaschine import Client async def main() -> None: """Run!""" client = Client() # ... asyncio.run(main()) ``` By default, the library creates a new connection to the sprinkler controller with each coroutine. If you are calling a large number of coroutines (or merely want to squeeze out every second of runtime savings possible), an [`aiohttp`][aiohttp] `ClientSession` can be used for connection pooling: See the module docstrings throughout the library for full info on all parameters, return types, etc. ```python import asyncio from aiohttp import ClientSession from regenmaschine import Client async def main() -> None: """Run!""" async with ClientSession() as session: client = Client(session=session) asyncio.run(main()) ``` ## Loading Local (Accessible Over the LAN) Controllers Once you have a client, you can load a local controller (i.e., one that is accessible over the LAN) very easily: ```python import asyncio from aiohttp import ClientSession from regenmaschine import Client async def main() -> None: """Run!""" async with ClientSession() as session: client = Client(session=session) await client.load_local("192.168.1.101", "my_password", port=8080, use_ssl=True) controllers = client.controllers # >>> {'ab:cd:ef:12:34:56': } asyncio.run(main()) ``` ## Loading Remote (Accessible Over the RainMachine Cloud) Controllers If you have 1, 2 or 100 other local controllers, you can load them in the same way – `client.controllers` will keep your controllers all organized. What if you have controllers around the world and can't access them all over the same local network? No problem! `regenmaschine` allows you to load remote controllers very easily, as well: ```python import asyncio from aiohttp import ClientSession from regenmaschine import Client async def main() -> None: """Run!""" async with ClientSession() as session: client = Client(session=session) await client.load_remote("rainmachine_email@host.com", "my_password") controllers = client.controllers # >>> {'xx:xx:xx:xx:xx:xx': , ...} asyncio.run(main()) ``` Bonus tip: `client.load_remote` will load _all_ controllers owned by that email address. ## Using the Controller Regardless of the type of controller you have loaded (local or remote), the same properties and methods are available to each: ```python import asyncio import datetime from aiohttp import ClientSession from regenmaschine import Client async def main() -> None: """Run!""" async with ClientSession() as session: client = Client(session=session) # Load a local controller: await client.load_local("192.168.1.101", "my_password", port=8080, use_ssl=True) # Load all remote controllers associated with an account: await client.load_remote("rainmachine_email@host.com", "my_password") # They all act the same! The only difference is that remote API calls # will pass through the RainMachine™ cloud: for mac_address, controller in client.controllers: # Print some client properties: print(f"Name: {controller.name}") print(f"Host: {controller.host}") print(f"MAC Address: {controller.mac}") print(f"API Version: {controller.api_version}") print(f"Software Version: {controller.software_version}") print(f"Hardware Version: {controller.hardware_version}") # Get all diagnostic information: diagnostics = await controller.diagnostics.current() # Get all weather parsers: parsers = await controller.parsers.current() # Get all programs: programs = await controller.programs.all() # Include inactive programs: programs = await controller.programs.all(include_inactive=True) # Get a specific program: program_1 = await controller.programs.get(1) # Enable or disable a specific program: await controller.programs.enable(1) await controller.programs.disable(1) # Get the next run time for all programs: runs = await controller.programs.next() # Get all running programs: programs = await controller.programs.running() # Start and stop a program: await controller.programs.start(1) await controller.programs.stop(1) # Get basic details about all zones: zones = await controller.zones.all() # Get advanced details about all zones: zones = await controller.zones.all(details=True) # Include inactive zones: zones = await controller.zones.all(include_inactive=True) # Get basic details about a specific zone: zone_1 = await controller.zones.get(1) # Get advanced details about a specific zone: zone_1 = await controller.zones.get(1, details=True) # Enable or disable a specific zone: await controller.zones.enable(1) await controller.zones.disable(1) # Start a zone for 60 seconds: await controller.zones.start(1, 60) # ...and stop it: await controller.zones.stop(1) # Get all running zones: programs = await controller.zones.running() # Get the device name: name = await controller.provisioning.device_name # Get all provisioning settings: settings = await controller.provisioning.settings() # Get all networking info related to the device: wifi = await controller.provisioning.wifi() # Get various types of active watering restrictions: current = await controller.restrictions.current() universal = await controller.restrictions.universal() hourly = await controller.restrictions.hourly() raindelay = await controller.restrictions.raindelay() # Set universal restrictions – note that the payload is the same structure # as returned by controller.restrictions.universal(): await controller.restrictions.set_universal( { "hotDaysExtraWatering": False, "freezeProtectEnabled": True, } ) # Get watering stats: today = await controller.stats.on_date(datetime.date.today()) upcoming_days = await controller.stats.upcoming(details=True) # Get info on various watering activities not already covered: log = await controller.watering.log(datetime.date.today(), 2) queue = await controller.watering.queue() runs = await controller.watering.runs(datetime.date.today()) # Pause all watering activities for 30 seconds: await controller.watering.pause_all(30) # Unpause all watering activities: await controller.watering.unpause_all() # Stop all watering activities: await controller.watering.stop_all() # See if a firmware update is available: update_data = await controller.machine.get_firmware_update_status() # ...and request the update: update_data = await controller.machine.update_firmware() # Reboot the controller: update_data = await controller.machine.reboot() # Return the current flow meter data: flowmeter = await controller.watering.flowmeter() # Add values to flowmeter counters from an external smart water meter # not wired directly to the controller. # Units can be "clicks", "gal", "m3" and "litre". await controller.watering.post_flowmeter({"value": 2000, "units": "clicks"}) asyncio.run(main()) ``` Check out `example.py`, the tests, and the source files themselves for method signatures and more examples. For additional reference, the full RainMachine™ API documentation is available [here][rainmachine-api]. # Loading Controllers Multiple Times It is technically possible to load a controller multiple times. Let's pretend for a moment that: - We have a local controller named `Home` (available at `192.168.1.101`). - We have a remote controller named `Grandma's House`. - Both controllers live under our email address: `user@host.com` If we load them thus: ```python import asyncio from aiohttp import ClientSession from regenmaschine import Client async def main() -> None: """Run!""" async with ClientSession() as session: client = Client(session=session) # Load "Home" locally: await client.load_local("192.168.1.101", "my_password") # Load all of my controllers remotely: await client.load_remote("user@host.com", "my_password") asyncio.run(main()) ``` ...then we will have the following: 1. `Home` will be a `LocalController` and accessible over the LAN. 2. `Grandma's House` will be a `RemoteController` and accessible only over the RainMachine™ cloud. Notice that `regenmaschine` is smart enough to not overwrite a controller that already exists: even though `Home` exists as a remote controller owned by `user@host.com`, it had already been loaded locally. By default, `regenmaschine` will only load a controller if it hasn't been loaded before (locally _or_ remotely). If you want to change this behavior, both `load_local` and `load_remote` accept an optional `skip_existing` parameter: ```python import asyncio from aiohttp import ClientSession from regenmaschine import Client async def main() -> None: """Run!""" async with ClientSession() as session: client = Client(session=session) # Load all of my controllers remotely: await client.load_remote("user@host.com", "my_password") # Load "Home" locally, overwriting the existing remote controller: await client.load_local("192.168.1.101", "my_password", skip_existing=False) asyncio.run(main()) ``` # Contributing Thanks to all of [our contributors][contributors] so far! 1. [Check for open features/bugs][issues] or [initiate a discussion on one][new-issue]. 2. [Fork the repository][fork]. 3. (_optional, but highly recommended_) Create a virtual environment: `python3 -m venv .venv` 4. (_optional, but highly recommended_) Enter the virtual environment: `source ./.venv/bin/activate` 5. Install the dev environment: `script/setup` 6. Code your new feature or bug fix on a new branch. 7. Write tests that cover your new functionality. 8. Run tests and ensure 100% code coverage: `poetry run pytest --cov regenmaschine tests` 9. Update `README.md` with any new documentation. 10. Submit a pull request! [aiohttp]: https://github.com/aio-libs/aiohttp [ci-badge]: https://img.shields.io/github/actions/workflow/status/bachya/regenmaschine/test.yml [ci]: https://github.com/bachya/regenmaschine/actions [codecov-badge]: https://codecov.io/gh/bachya/regenmaschine/branch/dev/graph/badge.svg [codecov]: https://codecov.io/gh/bachya/regenmaschine [contributors]: https://github.com/bachya/regenmaschine/graphs/contributors [fork]: https://github.com/bachya/regenmaschine/fork [issues]: https://github.com/bachya/regenmaschine/issues [license-badge]: https://img.shields.io/pypi/l/regenmaschine.svg [license]: https://github.com/bachya/regenmaschine/blob/main/LICENSE [maintainability-badge]: https://api.codeclimate.com/v1/badges/cb14e60d5f5a4c2ccb2c/maintainability [maintainability]: https://codeclimate.com/github/bachya/regenmaschine/maintainability [new-issue]: https://github.com/bachya/regenmaschine/issues/new [pypi-badge]: https://img.shields.io/pypi/v/regenmaschine.svg [pypi]: https://pypi.python.org/pypi/regenmaschine [rainmachine-api]: https://rainmachine.docs.apiary.io/ [rainmachine-premium]: https://www.rainmachine.com/premium/ [regenmaschine]: http://www.rainmachine.com/ [version-badge]: https://img.shields.io/pypi/pyversions/regenmaschine.svg [version]: https://pypi.python.org/pypi/regenmaschine