README.md
# 💧 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]
<a href="https://www.buymeacoffee.com/bachya1208P" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
`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': <LocalController>}
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': <RemoteController>, ...}
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