The Rachio Plugin for Vera home automation controllers is a plugin to give Vera users access and control of their Rachio Iro irrigation controls. The plugin allows the user to see any number of configured controllers, with any number of zones, and shows status and health of each controller and its controlled zones. User can start manual watering schedules for one or multiple zones on demand. This integrates these control features into Vera's Dashboard, allowing the user to use it as the primary interface for all devices in their homes.
If you are unfamiliar with Vera Control, Ltd's home automation systems, you can find more information here.
Getting Started Installing the Plugin
Installation of the plug-in is done through the Vera Plugin/App Store.
UI7 is required. The Rachio Plugin does not run under firmware earlier than UI7 and does not run under openLuup. Version 7.0.21 of UI7 is also excluded (upgrade to 7.0.22 or higher).
From the Vera Dashboard, click the Apps heading the left menu, and then choose Install Apps. Underneath the heading is a search box and a "Search App" button. Enter "Rachio" in the text field and press the "Search App" button. The Rachio Service plugin should be listed. Click the "Details" button, and then the "Install" button on the page that comes up.
Initial Configuration
Install your API Key on the Rachio Service device.
Before continuing, make sure you have a Rachio irrigation controller (Iro) installed and your Rachio account set up. You'll know it's all done if you can log in and use the Rachio web app or the iOS or Android mobile apps.
When you first install the plugin, it will create a single device called "Rachio Service." This is the coordinating service for all Rachio controllers associated with your Rachio account. It will display a status of "Offline (no API key)" until you set your API key. This is done by going to the device settings page, entering your API key in the field provided, and pressing the Set button. Your Rachio API key can be retrieved by logging in to the Rachio web app (https://app.rach.io/), choosing "Account Settings" in the left navigation, and then clicking the "Get API Key" link.
Once you enter a valid API key, you'll see the plugin's status go to "Online," with accompanying activity information. The plugin with then inventory the Rachio Iros associates with your account, and create child devices for the Iros and their zones. The Vera devices this plugin creates are:
- The Rachio Service device (the root device);
- A Rachio Device device for each controller;
- A Rachio Schedule device for each configured schedule on each controller;
- A Rachio Zone device for each zone on each controller.
Yes, that's quite a few devices. My simple Rachio configuration with one 8-zone Iro and two configured schedules makes 12 Vera devices (the Service device, the Device device, eight Zone devices, and two Schedule devices). If that's too much clutter for you, there is a way to hide zones and/or schedules (see below).
Operation
Display Configuration
The Rachio Service device settings contain four switches to control the visibility of zone and schedule devices. If the display of zones, schedules, or both, is too cluttered for you, you can limit what is displayed by manipulating the switches as follows:
- Hide All Zones: Makes all zone devices invisible.
- Hide Disabled Zones: Makes only disabled zones invisible.
- Hide All Schedules: Make all schedule devices invisible.
- Hide Disabled Schedules: Makes only disabled schedules invisible.
When devices are made invisible, they still exist, they are just not visible to you. But, you can still use them in scenes and Lua scripts.
It is sometimes necessary to refresh your browser after changing the above settings to get the Vera app to display properly.
Monitoring Activity
The Rachio Service device handles all of the communication with Rachio for all controllers, schedules, and zones. It is the master. In normal operation, it will show a status of "Online", occasionally with some additional information about its activity (e.g. "Online (updating)").
A status of "Online (delay)" means that the service did not successfully reach Rachio for status information, but the problem was considered "transient" and may resolve itself later. You shouldn't worry about this, unless it's been days since you've seen a plain "Online" status, or the plugin is otherwise behaving strangely.
A status of "Offline" indicates that there has been a fatal error that has interrupted the plugin's operation. An example might be that your Rachio account has been suspended, deleted, or changed, or your API key has changed.
Each Iro controller will have a Rachio Device associated with it. It will have the same name as that assigned in the Rachio web or mobile app. It will display its own status information, which may include any of the following:
- Online - the controller is online and communicating;
- Offline - the controller cannot reach the Rachio service for some reason (no power, no wi-fi, etc.);
- Rain Delay - watering is suspended due to a rain delay;
- Disabled - the controller has been "turned off" using the Rachio web or mobile app;
- Paused - the controller has been paused using the Rachio web or mobile app;
- Processing - the controller is running a watering schedule; additional text provides information about the type of schedule (e.g. "Processing Button" means that manual watering was initiated at the controller itself, while "Processing Manual" indicates a manual schedule started by the app or Vera interface.
Schedules and zones will also show their related activity. Schedules and zones can be enabled or disabled, and their status and icons will reflect that. If the system is watering, the schedule being run will show as running, with remaining time to water counting down. Each zone also shows its activity whenever it is active.
Starting Manual Watering
You can start a single-zone watering cycling by finding the Vera device for the zone in the Dashboard, and moving the slider from 0 to 100% (which corresponds to 0 to 100 minutes of watering). The zone will immediately start watering (assuming the controller isn't disabled, of course).
You can also start a single- or multi-zone watering cycling on a controller by going into the settings page for the controller. The settings page presents a list of checkboxes for each enabled zone on the Iro controller. Check each box for each zone to water, then set the watering time for each zone using the corresponding dropdown. Press the "Start Watering" button to initiate the watering cycle. The zones will water in sequence until all selected zones have finished.
In the image at right, zones 1 and 5 are selected to water for periods of 5 and 15 minutes, respectively. Watering will begin when we push the Start Watering button.
Starting a Schedule
You can start a configured schedule at any time by pressing the "Start" button on the schedule device. The schedule's status will show its remaining runtime.
Note that during any watering schedule that uses cycling, the controller may delay between cycles. Rachio's API does not report these delays as active periods, so the schedule's and controller's statuses will go back to idle for the delay period, and then go back into "processing" status as watering resumes.
Stopping Watering
To stop watering in progress, press the "Stop Watering" button on the Iro controller's device in the Vera dashboard.
Turning an Iro On or Off
Push the "On" button on the Iro device in the Dashboard to turn on the Iro's automatic features. Push the "Off" button to turn them off.
In the Rachio web app, this is referred to as "Standby Mode" in the device settings. Putting an Iro in Standby turns off all of its automatic processing. However, you can still start manual water for one or multiple zones, or start a schedule.
Showing/Hiding Devices
If you wish, you can hide the Vera's zone or schedule devices to reduce clutter on the Vera's Device List. This is done by changing the "Hide" settings on the Settings page of the Rachio Service device. They're not gone; they're just hidden. You can get them back any time by changing the settings.
Lua Scripting
State Variables for the Service Device
The service ID for all variables in the Rachio Service device is urn:toggledbits-com:serviceId:Rachio1. Variables marked send events when modified, so they may be watched or used as triggers.
ServiceCheck
The ServiceCheck variable contains the numeric plugin status. It is 0 if the plugin is running, and non-zero otherwise (i.e. an error has occurred and the plugin is not polling the Rachio API). The specific values are internal and subject to change; the only thing you can rely on is that zero means all is well, and non-zero means not well.
LastUpdate
The LastUpdate variable contains the timestamp (number of seconds since the Unix Epoch) of the last successful query of the Rachio API.
Message
The Message variable contains the last message displayed on the device UI (Vera Dashboard or settings page).
State Variables for Iro Devices
Unless otherwise noted, the service ID for all variables in Rachio Device devices is urn:toggledbits-com:serviceId:RachioDevice1. Variables marked send events when modified, so they may be watched or used as triggers.
On
The On state variable follows the variable of the same name from Rachio's API. It indicates whether the associated Iro is in standby (On=0) or running (On=1). An Iro in standby does not run automatic processes (like watering schedules).
Paused
The Paused state variable tracks the property of the same name from Rachio's API. It's not entirely clear to me how you pause an Iro, or unpause it. There doesn't not seem to be command for it in the API, and I also don't see it represented in their current web and Android apps.
Status
The Status variable tracks the reported device status from the Rachio API. This is not the same as the message that appears in the Vera Dashboard UI.
Message
This is the current message that is displayed on the Vera Dashboard for the Iro. It will likely be different from the Status variable above, as a broader view of the controller status is taken to create this text. The text is informational only, and its content and format should not be relied upon (it may change between versions).
Watering
Watering is a flag (1=true, 0=false) that indicates if the controller is watering any zone. This variable can be watched, or used as a trigger for scenes.
Duration
This is the scheduled duration (minutes) of this schedule.
Remaining
This variable's value is the amount of time (minutes) remaining in the current watering schedule.
LastStart
The most recent time a schedule started watering on this controller. The value is a Unix timestamp (see LastUpdate in the Rachio Service variables, above).
RunEnds
This is end time (as a Unix timestamp) of the most recent schedule run.
LastScheduleName
This is the name of the most recent schedule that ran on the controller. The special name "MANUAL" indicates that the most-recent run was started using a zone runtime slider, or using the web or mobile applications. The special name "BUTTON" indicates that it was started at the front panel of the Rachio controller.
RainDelay
This flag indicates whether the controller's operation is currently rain-delayed (=1) or not (=0).
RainDelayTime
If RainDelay is 1, this value will be the number of minutes remaining in the rain delay period.
State Variables for Schedules
The service ID for all variables in Rachio Schedule devices is urn:toggledbits-com:serviceId:RachioSchedule1. Variables marked send events when modified, so they may be watched or used as triggers.
Enabled
This flag indicates whether the schedule has been enabled (=1) and is eligible to run on the controller, of it has been disabled (=0).
Watering
This flag indicates that the schedule is currently running (=1).
Duration
This is the scheduled duration (minutes) of this schedule.
Remaining
This variable's value is the amount of time (minutes) remaining in the current watering schedule.
LastStart
The most recent time this schedule started watering. The value is a Unix timestamp (see LastUpdate in the Rachio Service variables, above).
RunEnds
This is the schedule end time (as a Unix timestamp) of the run.
State Variables for Zones
The service ID for all variables in Rachio Zone devices is urn:toggledbits-com:serviceId:RachioZone1. Variables marked send events when modified, so they may be watched or used as triggers.
Enabled
This flag variable indicates whether the zone is enabled (=1) or disabled(=0). Enabling and disabling zones can only be done through the Rachio web and mobile apps, currently--it does not seem to be exposed in the public API we use.
Watering
This flag indicates that the zone is currently watering (=1).
Duration
This is the scheduled duration (minutes) of the most recent run.
Remaining
This variable's value is the amount of time (minutes) remaining in the most recent run.
LastStart
The most recent time this zone started watering. The value is a Unix timestamp (see LastUpdate in the Rachio Service variables, above).
RunEnds
This is the schedule end time (as a Unix timestamp) of the most recent run on this zone.
LastScheduleName
This is the name of the most recent schedule that ran this zone. The special name "MANUAL" indicates that the most-recent run was started using the zone runtime slider, or using the web or mobile applications. The special name "BUTTON" indicates that it was started at the front panel of the Rachio controller.
Actions
Take special note of the service IDs, as there are four used by the Rachio Plugin. Your attempt to use an action won't work if you use the wrong service ID.
DeviceOn
The DeviceOn action turns an Iro on. When on, the Iro will run its configured automatic watering schedules. The devnum is the Luup device number of the Iro device.
luup.call_action("urn:toggledbits-com:serviceId:RachioDevice1", "DeviceOn", {}, devnum)
DeviceOff
The DeviceOff action turns an Iro off. Turning an Iro off disables all of its features and automatic watering schedules. The devnum is the Luup device number of the Iro device.
luup.call_action("urn:toggledbits-com:serviceId:RachioDevice1", "DeviceOff", {}, devnum)
DeviceStop
The DeviceStop action immediately stops any running schedule on the Iro (i.e. it stops watering). The devnum is the Luup device number of the Iro device.
luup.call_action("urn:toggledbits-com:serviceId:RachioDevice1", "DeviceStop", {}, devnum)
StartZone
The StartZone action immediately starts a manual schedule for a single irrigation zone. The devnum passed in is the Luup device number of the zone, not the Iro device. The durationMinutes is the number of minutes (0-180) for the schedule to run. Any other running schedule on the Iro is stopped by this action.
luup.call_action("urn:toggledbits-com:serviceId:RachioZone1", "StartZone", { durationMinutes=3 }, devnum)
StartMultiZone
The StartMultiZone action immediately starts a manual schedule for one or more zones on a single Iro. The devnum is the Luup device number of the Iro device. The zoneData is a string containing comma-separated zonenumber=time substrings.
luup.call_action("urn:toggledbits-com:serviceId:RachioDevice1", "StartMultiZone", { zoneData="6=20,1=3" }, devnum)
The example above starts a two-zone manual schedule, with zone 1 watering for 3 minutes, and zone 6 watering for 20 minutes. Zones are run in the order presented in the string, so in this example, zone 6 will run first, then zone 1.
StartSchedule
The StartSchedule action immediately starts a configured schedule. The devnum is the Luup device number of the Iro schedule. The schedule runs according to its configuration, so there are no arguments to pass in to this action.
luup.call_action("urn:toggledbits-com:serviceId:RachioSchedule1", "StartSchedule", {}, devnum)
ImperiHome Integration
The Rachio plugin (as of v1.2) implements the ImperiHome ISS API, which allows ImperiHome to see and control Rachio zones and schedules. To add the Rachio plugin to your ImperiHome configuration:
- Open the ImperiHome app;
- From the menu, choose My Objects;
- Click Add a new object;
- Choose ImperiHome Standard System;
- In the Local API base URL enter: http://your-vera-ip/port_3480/data_request?id=lr_Rachio&action=ISS
- Click the Next button.
ImperiHome should then connect to the Rachio plugin on the Vera and take inventory of zone and schedule devices, and display them in its interface. Control is basic, as ImperiHome does not (as of this writing) implement irrigation valves as a device type, so the zones and schedules are mapped to switches. Turning "on" a zone starts water for a fixed period of 5 minutes. Turn "on" a schedule starts the schedule with its usual zones and durations. Turning "off" either will stop all watering.
Troubleshooting
- Rachio Service device shows "Online (delaying)"
- The "Online (delaying)" service message indicates one of several problems. All are considered "transient" and normally resolve themselves. If they do not resolve by a couple of hours, reloading Luup may help. The types of problems that may cause this message include:
- Temporary local internet access problems (i.e. your Vera can't access the interet);
- Temporary problems at Rachio's API site (e.g. maintenance, minor errors, etc.);
- Excessive API hit rate (too many API queries too quickly)--the plugin limits the rate of queries to Rachio's API, to prevent the plugin's activities, or any scenes or Lua scripted actions you create to operate the plugin, from hammering Rachio's servers. This condition will clear itself if you just leave the UI alone for a couple of minutes.
- I can't figure out how to enable or disable a zone/a schedule.
- It's not you. It isn't there. This function isn't published in Rachio's API, so we don't have it. Rachio's web and mobile apps can do it, so it exists somewhere, and when we find it, we'll add the function to the plugin.
- Rachio's app can do X, but the plugin can't. Why?
- This plugin isn't meant to be a full replacement for Rachio's APIs. We'll consider any enhancement request that helps with operating and monitoring the Rachio, but configuring the Rachio is a much bigger user interface problem, and likely to be a moving target in the Rachio world, so it's not something we're likely to chase. But, always ask, because as the old saying goes, the answer is "no" if you don't ask the question.
- The Rachio Service device stops with "Offline (unsupported firmware)"
- The Rachio Plugin only runs on UI7. One specific version of UI7, 7.0.21 (947/2931/2935/2937), is known to have a bug that prevents inital configuration of the plugin, so this version is excluded. If you are running this version currently, you will need to upgrade to a more recent release to run this plugin.
- Does Rachio Plugin run under ALTUI? openLuup?
- Rachio Plugin works in its most basic form under ALTUI; that is, we haven't done any specific work to use ALTUI's special customization features. Rachio Plugin does not run under openLuup currently. [Author note: I'm a huge fan of both of these projects, so stay tuned for status changes here.]
- Where's the GitHub repo?
- It's at https://github.com/toggledbits/RachioService
- I just need help.
- Contact form coming soon. Until then, please post a message on the Vera Forums.