Toro Tempus Air

Driver: toro_tempus_air

Cloud-only smart irrigation control for the Toro Tempus Air controller family (Tempus 4, Tempus 8, Tempus 12, Tempus 16). The Tempus Air gateway phones home to the MyToro cloud; there is no local LAN API, so all commands flow through api.mytoro.com.

Prerequisites

• A MyToro cloud account that already has the Tempus Air controller paired through the MyToro mobile app.
• The controller online and reachable from the internet. If the WAN is down, no commands will land.
• Two-factor authentication disabled on the MyToro account (or a long-lived app password, if Toro adds 2FA in the future).

Setup steps

1. Open the MyToro mobile app and confirm the Tempus Air controller is paired and reporting status.
2. In GEM, add a device:
   • Driver: toro_tempus_air
   • username: your MyToro account email
   • password: your MyToro account password (stored encrypted)
3. If your MyToro account has more than one site / controller, run get_sites from the Script Console and copy the desired site id into the site_id device attribute. Single-controller accounts auto-select.
4. Run get_zones — you should see a list of zones with numeric ids and labels.
5. Create one GEM zone per Tempus Air zone. Set the GEM zone address to the Tempus zone id (typically 1 through 16).

Attribute reference

Device attributes

Name	Required	Default	Description
username	yes	—	MyToro account email.
password	yes	—	MyToro account password (stored encrypted via the secure-attribute pipeline).
api_base	no	https://api.mytoro.com	Override the API base URL. Leave at default unless directed otherwise.
site_id	no	—	Site / controller id. Only required on accounts with more than one site.
status_interval	no	60000	How often to poll zone state from the cloud, in milliseconds. The gateway phones home every 5-10 minutes, so polling faster than that mostly hits cached state. Values below 1000 are raised to 1000; a value that is blank, zero, negative, unreadable or too large for a timer uses 60000.
default_run_seconds	no	600	Default run duration when on is called without a duration argument.

Zone

Address: the Tempus zone id as returned by get_zones (typically a small integer like 1 through 16).

Surfaced zone attributes:

• state — on (zone is currently watering) or off
• remaining_seconds — seconds left in the current run, when known

Commands

Command	Args	Notes
on	address, duration (seconds)	Start a manual run on a zone. Duration defaults to default_run_seconds and is capped at 4 h (14400 s).
off	address	Stop a running zone immediately.
stop_all	—	Stop irrigation on every zone for this site.
get_zones	—	List irrigation zones for the configured site.
get_sites	—	List sites / controllers visible to this account.
get_status	address	Read the current valve state and remaining run time for one zone.
pause_schedule	—	TODO — endpoint shape unverified against vendor docs. Returns not yet implemented.
resume_schedule	—	TODO — endpoint shape unverified against vendor docs. Returns not yet implemented.

Known limitations

• Cloud only. No local LAN API exists on Tempus Air. WAN outage means no control.
• Polling latency. Cloud state can lag wire state by several seconds because the gateway batches state updates. The status polling loop catches up at status_interval.
• Cloud outages. If the MyToro cloud cannot be reached (or refuses the login) when GEM connects, the driver tries again after 30 seconds, doubling the wait up to 5 minutes. While the cloud is unreachable the status poll keeps running, but after three failed passes in a row it slows down (doubling up to at least 5 minutes) and speeds back up as soon as the cloud answers. A refused login holds off further background logins for 30 seconds, doubling up to 5 minutes; commands you send yourself still try to log in.
• Errors are reported, not hidden. A command the cloud answers with an HTTP error, or with a web page instead of JSON (a captive portal or proxy), returns an error rather than looking like success. Zone state is left alone when a status read fails.
• Schedule editing is out of scope. Use the MyToro app or web portal for schedule create / modify / delete. This driver only does ad-hoc manual runs and reads.
• Some command paths marked TODO. pause_schedule and resume_schedule are listed in getCommands() for discoverability but return not yet implemented until the vendor publishes a verified API reference. Honest stub is preferred over fabricated endpoints.

Troubleshooting

• 401 on every request. Confirm the email / password by signing into the MyToro mobile app. If 2FA is now enabled on the account, this driver will not work until Toro publishes an app-password mechanism.
• get_zones returns an empty list. site_id may be wrong on multi-controller accounts. Run get_sites and copy the correct id.
• Manual run lands but never stops. The Tempus controller enforces server-side max run durations; pass duration explicitly on the on command rather than relying on default_run_seconds.
• Login succeeds, every other call returns not found. Likely an api_base override pointing at a stale endpoint. Reset api_base to the default and retry.