regenmaschine 0.2.4

A simple API for RainMachine sprinkler controllers

Regenmaschine: A Simple Python Library for RainMachine™

Regenmaschine (German for “rain machine”) is a simple, clean, well-tested Python library for interacting with RainMachine™ smart sprinkler controllers. It gives developers an easy API to manage their controllers over a LAN or via RainMachine™’s cloud.

💧 Installation

$ pip install regenmaschine

💧 Usage

Authentication & Creating a Client

Authentication is the first step and an be done against the local device or the cloud API:

import regenmaschine as rm

# Using the local API:
auth = rm.Authenticator.create_local('<DEVICE_IP_ADDRESS>', '<PASSWORD>')

# Using the remote API:
auth = rm.Authenticator.create_remote('<EMAIL ADDRESS>', '<PASSWORD>')

If authentication is successful, this auth object can then be used to create a client:

client = rm.Client(auth)

Diagnostics

More info on responses, etc: http://docs.rainmachine.apiary.io/#reference/diagnostics

client.diagnostics.current() # Returns current diagnostic info
client.diagnostics.log()     # Returns entire device log

Programs

More info on responses, etc: http://docs.rainmachine.apiary.io/#reference/programs

client.programs.all()     # Returns all program info
client.programs.get(1)    # Returns info about program with UID of 1
client.programs.next()    # Returns the next run date/time for all programs
client.programs.running() # Returns all running programs
client.programs.start(7)  # Starts program 7
client.programs.stop(7)   # Stops program 7

Restrictions

More info on responses, etc: http://docs.rainmachine.apiary.io/#reference/restrictions

client.restrictions.current()   # Returns currently active restrictions
client.restrictions.hourly()    # Returns restrictions over the next hour
client.restrictions.raindelay() # Returns all restrictions due to rain
client.restrictions.universal() # Returns the global list of restrictions

Stats

More info on responses, etc: http://docs.rainmachine.apiary.io/#reference/daily-stats

client.stats.on_date('6/29/2017')           # Returns all stats for a date
client.stats.on_date('2017-06-29')          # Returns all stats for a date
client.stats.on_date('1 week ago')          # Returns all stats for a date
client.stats.upcoming()                     # Returns expected stats for the next 7 days
client.stats.upcoming(include_details=True) # Deeper look at the next 7 days

Watering

More info on responses, etc: http://docs.rainmachine.apiary.io/#reference/watering

client.watering.log()                              # Returns log of all watering
client.watering.log(details=True)                  # Returns full log of all watering
client.watering.log('6/29/2017', 2)                # Returns log for 6/27-6/29
client.watering.log('2017-06-29', 2)               # Returns log for 6/27-6/29
client.watering.log('2017-06-29', 2, details=True) # Returns full log for 6/27-6/29
client.watering.log('2 days ago', 3)               # Returns log 2-5 days ago

client.watering.queue()                            # Returns the active queue of watering activities
client.watering.runs('6/29/2017', 2)               # Alternate view of log()
client.watering.runs('2017-06-29', 2)              # Alternate view of log()
client.watering.runs('2 days ago', 3)              # Alternate view of log()
client.watering.stop_all()                         # Immediately stops all programs and zones

Weather Services

More info on responses, etc: http://docs.rainmachine.apiary.io/#reference/weather-services

client.parsers.current() # Returns current weather services being used

Zones

More info on responses, etc: http://docs.rainmachine.apiary.io/#reference/zones

client.zones.all()                   # Returns all zone info
client.zones.all(properties=True)    # Returns advanced info for all zones
client.zones.get(2)                  # Returns info about a zone with UID of 2
client.zones.get(2, properties=True) # Returns advanced info about zone 2
client.zones.start(3, 60)            # Starts zone 3 for 60 seconds
client.zones.stop(3)                 # Stops zone 3

# You can also simulate what a zone will do:
properties = client.zones.get(2, properties=True)
client.zones.simulate(properties)

Authentication Caching

There doesn’t appear to be a limit on the number of times RainMachine™ will allow new access tokens to be generated. However, it may be desirable to use the same credentials long term. Therefore, the auth object can be dumped and saved:

# Outputs a dict:
auth_json = auth.dump()

# Outputs a string version of the dict:
auth_str = auth.dumps()

The auth object contains the access token used to authenticate API requests, as well as an expiration timeframe and more:

{
  "sprinkler_id": None,
  "cookies": {
    "access_token": "24551da62895"
  },
  "api_url": "https://192.168.1.100:8080/api/4",
  "url": "https://192.168.1.100:8080/api/4",
  "checksum": u "c5e29cdef3b1e",
  "expires_in": 157680000,
  "api_endpoint": "auth/login",
  "access_token": u "24551da62895",
  "verify_ssl": False,
  "session": None,
  "expiration": u "Fri, 01 Jul 2022 20:11:48 GMT",
  "timeout": 10,
  "status_code": 0,
  "using_remote_api": False,
  "data": {
    "pwd": "MY_RM_PASSWORD",
    "remember": 1
  }
}

TAKE NOTE: the dumped auth object contains the access token needed to query the API, sprinkler IDs, RainMachine™ credentials, and other sensitive information. Therefore, it should be cached and stored securely.

One common use of this mechanism would be to check the expiration date of the access token; assuming it is still valid, a corresponding client can be recreated quite easily:

auth = rm.Authenticator.load(auth_json)
# ...or...
auth = rm.Authenticator.loads(auth_str)

client = rm.Client(auth)

Exceptions

Regenmaschine relies on two other libraries: Requests and Maya; as such, Regenmaschine may raise any of the exceptions that they provide.

Beyond that, Regenmaschine defines a few exceptions of its own:

• regenmaschine.exceptions.BrokenAPICall: returned when an API call only works on the local or remote APIs, but not both

• regenmaschine.exceptions.InvalidAuthenticator: returned when invalid authentication data is fed into regenmaschine.Authenticator.load() or regenmaschine.Authenticator.loads()

💧 Contributing

1. Check for open features/bugs or initiate a discussion on one.

2. Fork the repository.

3. Install the dev environment: make init.

4. Enter the virtual environment: pipenv shell

5. Code your new feature or bug fix.

6. Write a test that covers your new functionality.

7. Run tests: make test

8. Build new docs: make docs

9. Add yourself to AUTHORS.rst.

10. Submit a pull request!