regenmaschine 0.1.6

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 API.

💧 Installation

$ pip install regenmaschine

💧 Usage

Authentication

First, we need to authenticate. Authentication can 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

# log() can have any number of the parameters shown here:
client.watering.log()                 # Returns log of all watering
client.watering.log(details=True)     # Returns comprehensive 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('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(advanced_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, advanced_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

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:

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

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

Authentication Caching

Although there doesn’t appear to be a limit to the number of times RainMachine will allow authentication to occur, for speed/efficiency, it is often desirable to use the same credentials long-term. 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()

At any point, this authentication can be loaded back into a Regenmaschine client:

# Outputs a dict:
rm.Authenticator.load(auth_json)

# Outputs a string version of the dict:
rm.Authenticator.loads(auth_str)

Beware: the dumped auth object contains the access token needed to query the API, as well as the information needed to reconstruct the client. Therefore, it should be cached and stored securely.

💧 Contributing

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

2. Form the repository.

3. Install the dev environment: pip install pipenv; pipenv lock; pipenv install --dev.

4. Code your new feature or bug fix.

5. Write a test that covers your new functionality.

6. Run tests: pipenv run make test

7. Build new docs: pipenv run make docs

8. Add yourself to AUTHORS.rst.

9. Submit a pull request!