Firmware 2.2.1(4) API Reference [Nov 1, 2025]

0. Overview

  • Authentication (pw): All API calls require the device password via the pw parameter. The value must be provided as a lowercase MD5 hash. The OpenSprinkler app and web interfaces handle this hashing automatically. If you are making direct API calls, you must hash your plaintext password before sending the request. You can use any standard MD5 generation tool for this.
  • Device IP: Throughout this document, os-ip denotes the controller's IP address or hostname.
  • Command Parameters: Parameters can be sent in any order. You do NOT need to include every parameter in a request - any omitted parameter will retain its current value on the device.
  • Return values are all formatted in JSON, for example: {"fwv":221}, {"result":1}. Below is the list of error codes:
Code Meaning
1 Success
2 Unauthorized (missing device password or device password is incorrect)
3 Mismatch (new password and confirmation password do not match)
16 Data Missing (missing required parameters)
17 Out of Range (value exceeds the acceptable range)
18 Data Format Error (provided data does not match required format)
19 RF code Error (RF code does not match required format)
32 Page Not Found (page not found or requested file missing)
48 Not Permitted (e.g. cannot operate on the requested station)
64 Upload failed (e.g. OTA firmware update failed)

1. Major Changes

  • Support for DC-Powered OpenSprinkler v3.4: Includes two new variables related to USB-PD (Power Delivery):
  • Queuing Option for Manual Runs: Manual actions can now choose whether new zones run immediately or later. Applied to Manual Station Run, Run-Once, and Manual Program Start.
    • A new parameter qo is added for these commands, allowing a choice between appending zones to the queue, inserting them at the front, or replacing the existing queue.

In the following, new changes since the last firmware are highlighted in green like here.

2. Get Controller Variables /jc

Usage: http://os-ip/jc?pw=xxx

Variable Explanation
devt Device time in Unix epoch seconds (local time, adjusted to the device’s time zone).
nbrd Number of 8-station groups/boards, including the main controller.
en Operation enable bit (1: enabled; 0: disabled).
sn1 Sensor 1 status (1: active; 0: inactive).
sn2 Sensor 2 status (OS v3.x and OSPi only).
rd Rain delay flag (1: manual rain delay active; 0: not active).
rdst Rain delay stop time (epoch seconds); 0: rain delay is not in effect.
sunrise Today’s sunrise time, number of minutes since midnight.
sunset Today’s sunset time, number of minutes since midnight.
eip External IPv4, as a 32-bit integer: (ip[3]<<24)+(ip[2]<<16)+(ip[1]<<8)+ip[0].
lwc Timestamp (epoch seconds) of the last weather request.
lswc Timestamp (epoch seconds) of the last weather response. 0 means no successful response yet.
lupt Last device reboot time (epoch seconds).
lrbtc Cause code for the last reboot (see List of Reboot Causes).
lrun Last run record: [station_index, program_index, duration, end_time_epoch].
RSSI Wi-Fi signal strength (dBm, OS 3.x only).
mac Hardware MAC address.
loc GPS coordinates of the device location.
jsp JavaScript URL. Default: https://ui.opensprinkler.com/js
wsp Weather script URL. Default: weather.opensprinkler.com
wto Weather adjustment options (fields depend on the selected adjustment method).
wtdata Raw data relayed from the weather server; used to compute watering percentage.
wterr Error code from the last weather server response (see List of Weather Error Codes).
ifkey IFTTT Webhooks key (enables IFTTT notifications).
mqtt MQTT configuration parameters.
curr Total current draw across all zones (mA). Available only on controllers with current sensing capability.
sbits Station status bits. An array where each byte is an LSB bitfield for an 8-station group. Example: 2 (0b00000010) → 2nd station is open; 192 (0b11000000) → 7th and 8th stations are open.
ps Program status per station: each element represents a station consisting of four numbers [pid, rem, start, gid] where pid: program index (0: not running), rem: remaining seconds, start: start time, gid: sequential group ID. If a station’s sbit=0 but pid!=0, it’s queued (waiting but not running yet).
flwrt Flow count window (seconds). This value is firmware-dependent and is NOT the flow sampling rate. Instead flcrt/flwrt gives the flow rate (clicks per second).
flcrt Flow count (windowed): number of flow-sensor clicks during the last flwrt secs.
flcto Flow count (total): cumulative flow-sensor clicks since power-on (reset on reboot).
pq Pause state (0: inactive; 1: active).
pt Countdown timer for an active pause (seconds).
nq Number of elements in the program queue (zones running or waiting).
otc OpenThings Cloud (OTC) configuration parameters.
otcs OTC connection status (0: not enabled; 1: connecting; 2: disconnected; 3: connected).
dname Device name (included in notification messages to identify the controller).
gpio Array of spare/free GPIO pins (usable for GPIO stations).
email Email notification settings.
ocs Overcurrent status. 0: none; 255: system-wide overcurrent; other: index of the station that triggered overcurrent (station index starts from 1).
wtrestr Weather restriction status (0: inactive; 1: active).
wls Array of current multi-day average watering levels. Length depends on provider (e.g., Apple up to 10 days; others may support fewer).
apdv Active/Actual USB-PD voltage (V); read-only, for DC-powered OS v3.4.

3. Change Controller Variables /cv

Usage: http://os-ip/cv?pw=xxx&rsn=x&rrsn=x&rbt=x&en=x&rd=x&re=x&update=x&ap=x&rocs=x

Parameter Meaning
rsn Reset all stations (both running and queued). 1 triggers the reset; 0: no effect.
rrsn Reset all running stations (but not queued ones). 1 triggers the reset.
rbt Reboot the controller. 1 triggers the reboot.
en Enable/disable operation. 1: enable; 0: disable.
rd Set rain delay (hours). Range: 0–32767. 0 clears any active rain delay.
re Set the controller in remote extension mode. 1: enable; 0: disable.
ap Reset to AP mode for Wi-Fi reconfiguration without erasing settings/programs. Effective on OS 3.x only.
update Trigger firmware update (OSPi/Linux only).
rocs Clear overcurrent status (ocs). 1: clears.


Examples:

  • http://os-ip/cv?pw=xxx&rbt=1: reboot controller
  • http://os-ip/cv?pw=xxx&en=0: disable operation
  • http://os-ip/cv?pw=xxx&rd=24: set a 24-hour rain delay

4. Get Options /jo

Usage: http://os-ip/jo?pw=xxx

Note: options marked RO are read-only and not modifiable via the /co command

Variable Explanation
fwv Firmware version (e.g., 221 → v2.2.1). RO
fwm Firmware minor revision number. RO
tz Time zone (offset_hours*4+48). Examples: GMT+0→48; GMT−4→32; GMT+9:30→86. The value must be between 0–108.
dhcp Use DHCP (1: yes, 0: no).
ip{1,2,3,4} Static IP (ignored if dhcp=1).
gw{1,2,3,4} Gateway (router) IP (ignored if dhcp=1).
dns{1,2,3,4} DNS server IP (ignored if dhcp=1).
subn{1,2,3,4} Subnet mask (ignored if dhcp=1).
ntp Use NTP sync (1: yes, 0: no).
ntp{1,2,3,4} Custom NTP server IP (ignored if ntp=0).
hp{0,1} The lower and upper bytes of HTTP port: http_port=(hp1<<8)+hp0.
hwv Hardware version. RO
hwt Hardware type (0xAC: AC-powered; 0xDC: DC-powered; 0x1A: Latch). RO
ext Number of 8-station expansion boards (excluding main controller).
sdt Station delay time (seconds). Range [-600, 600] (i.e. [-10, 10] minutes), in increments / step of 5 seconds.
mas/mas2 Master station 1 and 2 indices (0: none).
mton/mton2 Master 1 and 2 ON Adjusted time (seconds). Range [-600, 600], step 5.
mtof/mtof2 Master 1 and 2 OFF Adjusted time (seconds). Range [-600, 600], step 5.
sn1t Sensor 1 type. 0: none, 1: rain, 2: flow, 3: soil, 240: program switch.
sn1o Sensor 1 option. 0: normally closed, 1: normally open (default).
sn1on/sn1of Sensor 1 delayed-on / delayed-off (minutes).
sn2t/sn2o Sensor 2 type / option (same semantics as Sensor 1).
sn2on/sn2of Sensor 2 delayed-on / delayed-off (minutes).
wl Water level (% watering). Range 0–250.
den Operation enable bit. To change, you must use the /cv command.
ipas Ignore password. 1: ignore; 0: do not ignore.
devid Device ID.
con/lit/dim LCD contrast/backlight/dimming values.
bst Boost time (milliseconds) for DC-powered & Latch controllers. Range 0–1000, step size 4.
uwt Weather adjustment method. 0: Manual; 1: Zimmerman; 2: Auto Rain Delay; 3: ETo; 4: Monthly. NOTE: Previously uwt.bit[7] flagged California water restriction; that bit is no longer used: instead, water restriction is indicated in the wto (weather options) variable.
lg Enable logging (1: on, 0: off).
fpr{0,1} Flow pulse rate (scaled by 100), calculated as ((fpr1<<8)+fpr0)/100.0.
re Remote extension mode. To change, you must use the /cv command.
dexp/mexp Detected / maximum zone expanders (-1: cannot auto-detect). RO
sar Special-station auto-refresh. When 1, special (e.g. RF, HTTP) stations will automatically refresh to ensure in sync with the master controller.
fwire Force wired connection (OS 3.x only). 1: stay wired; 0: allow Wi-Fi.
ife Notification event enable bits. A bit field:
• b0: Program scheduled
• b1: Sensor1 update
• b2: Flow sensor status update
• b3: Weather update (e.g. water level change, eip change)
• b4: Reboot
• b5: Station finish
• b6: Sensor2 update
• b7: Rain delay update
ife2 Extended notification bits:
• b0: Station start
• b1: Flow alert
• b2: Current alert.
imin Undercurrent threshold in mA (/10). Example: imin=10→100 mA.
imax Overcurrent threshold in mA (/10). 0: system default; 255: disabled. Example: imax=120→1200 mA.
tpdv Target USB-PD voltage (in decivolts) for DC-powered OS v3.4+. Example: tpdv=78→7.8 V

5. Change Options /co

Usage: http://os-ip/co?pw=xxx&[opn]=[opv]&loc=x&wto=x&ifkey=x&ttt=x
&otc=x&dname=x&mqtt=x&email=x

Parameter Meaning
[opn] Option name to modify (see the options list above). RO fields cannot be changed. You can include multiple option changes in one call (e.g., &tz=32&dhcp=1).
[opv] New value to be assigned to [opn].
loc Location string (URL-encoded). Accepts "city,state", ZIP code, or "lat,lon". When you use the UI/app to set the location, it always converts it to GPS.
wto Weather options as URL-encoded JSON without the outer {}. Fields depend on the selected method (e.g., Zimmerman has six parameters for the weights and baselines of temp t, humidity h, and rain r.
ifkey IFTTT Webhooks key.
ttt Set device time manually (epoch seconds). Ignored if ntp=1
otc OpenThings Cloud (OTC) configuration as JSON without the outer {}. Example: otc="en":1,"token":"token","server":"ws.cloud.openthings.io","port":80
mqtt MQTT configuration as JSON without the outer {}. Example: mqtt="en":1,"host":"x","port":1883,"pubt":"opensprinkler","subt":""
email Email configuration as JSON without the outer {}. Example: email="en":1,"host":"x","port":465,"user":"a@b.io","pass":"","recipient":""
dname Device name.


Examples:

  • os-ip/co?pw=xxx&loc=42.01,-75.22: change location to GPS coord 42.01,-75.22
  • os-ip/co?pw=xxx&hp0=144&hp1=31: change HTTP port to 8080 (31*256+144=8080)
  • os-ip/co?pw=xxx&sdt=30: set station delay time to 30 seconds
  • os-ip/co?pw=xxx&sn1t=1&sn1o=1: configure sensor1 to rain sensor, normally-open type

6. Set Device Password /sp

Usage: http://os-ip/sp?pw=xxx&npw=xxx&cpw=xxx

Parameter Meaning
npw New password (MD5 hash)
cpw Confirmation (MD5 hash)


Examples:

  • os-ip/sp?pw=xxx&npw=e0ff85143dfa717536cbb668cc8f8e8b&cpw=e0ff85143dfa717536cbb668cc8f8e8b: change password to the MD5 hash of the plaintext password sprinkler.
  • If either npw or cpw is omitted, Data Missing error is returned. If npw and cpw do not match, a Mismatch error is returned. Refer to the list of error code.

7. Get Station Names and Attributes /jn

Usage: http://os-ip/jn?pw=xxx

Variable Explanation
snames Array of station names (length equals number of zones).
maxlen Maximum characters allowed per station name.
stn_grp Each zone's sequential group ID. Value below 255: a sequential group; 255: parallel group.
masop Master1 operation bitfields, stored as an array, where each byte (LSB) represents a 8-zone group. For 24 zones, the array has 3 bytes: first byte → zones 1-8; second byte → zones 9-16; third byte → 17-24. Each byte indicates which zones in that group activate the master zone: For example, 254 (0b11111110) means all zones except the first zone activate master1.
masop2 Master2 operation bitfields. Same layout as masop.
ignore_rain Ignore Rain Delay bitfields.
ignore_sn1 Ignore Sensor1 bitfields.
ignore_sn2 Ignore Sensor2 bitfields.
stn_dis Zone Disable bitfields.
stn_spe Special Station flag bitfields.


Example: {"masop":[255],"masop2":[0],"ignore_rain":[0],"ignore_sn1":[0],"ignore_sn2":[0],"stn_dis":[0],"stn_spe":[0],"stn_grp":[0,0,0,1,0,0,0,0],"snames":["S01","S02","S03","S04","S05","S06","S07","S08"],"maxlen":32}

8. Get Special Station Data /je

Usage: http://os-ip/je?pw=xxx

Response Format: {"0":{"st":xxx, "sd":"xxx"}, "1":{"st":xxx, "sd":"xxx"}, ...}
Only stations with stn_spe bit=1 appear.

Key Meaning
station_id Station index in string form (e.g., "0", "1").
st Special-station type code (see table below).
sd Type-specific data payload associated with st.


Station Types:

st Type Format of sd
0 Standard Should not appear here, as only special stations are listed.
1 RF (Radio Frequency) Either legacy 16-byte RF hex code (protocol 1, 24 bits), or the new 25-byte code (prefixed with H, supporting all protocols and bit lengths).
2 Remote (IP) 14-byte hex code: 8 bytes for IP; 4 for port; 2 for station index.
3 GPIO 3 bytes. First 2 bytes: GPIO index; third byte: active state (1 or 0).
4 HTTP Comma-separated string (up to 240 bytes) formatted as: server,port,on_cmd,off_cmd. Assume server is HTTP.
5 HTTPS Same format as st=4. Assume server is HTTPS.
6 Remote (OTC) 35-byte hex code. First 32 bytes: OTC token, then '\0', then 2 bytes for station index.


Example: {"0":{"st":2,"sd":"c0a80093005002"},"1":{"st":1,"sd":"05331305333C0021"},
"2":{"st":4,"sd":"demo.opensprinkler.com,80,on/?z=1,off"}}

9. Change Station Names and Attributes /cs

Usage: http://os-ip/cs?pw=xxx&s?=x&m?=x&i?=x&j?=x&k?=x&n?=x&d?=x&p?=x&g?=x&sid=xx&st=xx&sd=xx

Parameter Meaning
s? Station name: ? is the station index starting at 0. Example: s2=Front%20Lawn sets the third station to Front Lawn. Max length is maxlen from /jn.
m? Master1 operation bitfields: ? is the board index starting at 0. m0: zones 1-8 (main controller); m1: zones 9-16 and so on. Example: m0=255 sets all zones on the main controller to activate Master1; m1=4 sets the 3rd station on the first expander to activate Master1. Refer to the masop variable in Station Attributes.
n? Master2 operation bitfields. Same format as m?.
i? ignore_rain bitfields.
j? ignore_sn1 bitfields.
k? ignore_sn2 bitfields.
d? stn_dis (station disable) bitfields.
p? stn_spe (station special) bitfields.
g? Station's sequential group ID (not a bitfield). ?: station index.
sid Special-station target index (station id).
st Special-station type (see /je).
sd Special-station data payload (see /je). URL-encoded.


Note:

  • Multiple assignments can be combined in one call; omitted fields are unchanged.
  • To make a station "special", set the corresponding p? bit and provide sid/st/sd.

Examples:

  • os-ip/cs?pw=xxx&s0=Front%20Lawn&s1=Back%20Lawn: set the first two stations' names
  • os-ip/cs?pw=xxx&m0=127&s7=Garage: set station 8's name and master operation bits for board m0 (127=all but station 8 activate Master1).
  • os-ip/cs?pw=xxx&sid=2&st=1&sd=00553300553c001c: set special station data for station 3
  • os-ip/cs?pw=xxx&g4=1: assign group id 1 to station 5.

10. Get Station Status /js

Usage: http://os-ip/js?pw=xxx

Variable Explanation
sn Array of 1/0 indicating each station's On/Off status.
nstations Total number of stations.


Example: {"sn":[1,1,0,0,0,0,0,0],"nstations":8}
Stations 1 and 2 (at indices 0 and 1 in the array) are currently open

11. Manual Station Run /cm

Usage: http://os-ip/cm?pw=xxx&sid=xx&en=x&t=xxx&ssta=x&qo=x

Parameter Meaning
sid Station index (starting at 0).
en Enable (1: open, 0: close).
t Time in seconds (max: 64800 i.e. 18 hours). Required when opening a zone.
qo Queuing option (applies when opening a zone). 0: append after other zones (default); 1: insert ahead of other zones.
ssta Shift remaining stations in the same sequential group when closing a zone (en=0). 0: don’t shift; 1: shift. Ignored when opening a zone.


Note:

  • Opening a master station by itself is not allowed (error), as it cannot be operated independently. To run a master alone, you can make use of a dummy zone (i.e. a zone not physically connected) and open that zone, which in turn opens the associated master(s).
  • Opening a station that is already running or already queued returns an error.
  • Manually started stations are assigned a program ID of 99.

Examples:

  • os-ip/cm?pw=xxx&sid=0&en=1&t=360: open station 1 for 6 minutes, append to the queue.
  • os-ip/cm?pw=xxx&sid=3&en=1&t=300&qo=1: open station 4 for 5 minutes, insert ahead of other zones.
  • os-ip/cm?pw=xxx&sid=3&en=0: close station 4. Remaining stations in the same sequential group retain their original assigned start times.
  • os-ip/cm?pw=xxx&sid=3&en=0&ssta=1: close station 4 and shift remaining stations in the same sequential group, so the next station starts immediately.

12. Manually Start a Program /mp

Usage: http://os-ip/mp?pw=xxx&pid=xx&uwt=x&qo=x

Parameter Meaning
pid Program index (starting from 0).
uwt Use weather (1: apply current watering level; 0: run at 100%).
qo Queuing option. 0: append the new program to the end of the queue; 1: insert at front (preemptive); 2: replace, i.e. reset all zones, clear queue, then start the new program. If qo is omitted, the default behavior is 2 (backward compatible).


Note: Program name annotations are honored when starting a program manually. If pid is out of bound, an error is returned.

Examples:

  • os-ip/mp?pw=xxx&pid=0&uwt=0: reset all zones, then start program 1 at 100% watering level. As qo is omitted, this behavior is backward compatible with previous firmwares.
  • os-ip/mp?pw=xxx&pid=1&uwt=1&qo=0: append program 2 at the end of the queue, using the current watering level.
  • os-ip/mp?pw=xxx&pid=1&uwt=1&qo=1: insert program 2 at the front of the queue.
  • os-ip/mp?pw=xxx&pid=1&uwt=1&qo=2: reset all zones, then start program 2 using the current watering level.

13. Get Program Data /jp

Usage: http://os-ip/jp?pw=xxx

Variable Explanation
nprogs Number of programs.
nboards Number of 8-zone groups (includes the main controller).
mnp Max number of programs allowed (40 for this firmware).
mnst Max number of fixed start times per program (4 in this firmware).
pnsize Max characters allowed for a program name (32 in this firmware).
pd Array of Program Entries; each follows the structure below.


Program Entry Structure:
[flag, days0, days1, [start0, start1, start2, start3], [dur0, dur1,...], name, [endr, from, to]]

Field Explanation
flag Bitfield of program flags (see flag table below).
days0,days1 Start-day data (see Start-day types below).
start0..start3 Start-time data (see Start-time encoding below).
dur* Per-station durations in seconds (max: 64800). The length must equal station count. Support two special values: 65534 → sunrise-to-sunset duration; 65535→ sunset-to-sunrise duration.
name Program name (≤pnsize characters).
[endr,from,to] Date-range tuple (see Date-range tuple below).


flag bitfield

bit(s) Meaning
0 Program enable flag (en). 1: enabled; 0:disabled.
1 Use weather flag (uwt). 1: yes; 0: no.
2–3 Odd/Even restriction. 0: none; 1: odd-day; 2: even-day; 3: undefined.
4–5 Start-day type. 0: weekly; 1: single-run; 2: monthly; 3: interval-day.
6 Start-time type. 0: repeating type; 1: fixed times.
7 Date-range enable. 0: off; 1: on.


Start-day Types. Depending on flag.bits[4-5]:

  • 0 → Weekly: days0.bits[0-6] store the binary selections (LSB) from Monday to Sunday. days1 is unused. Example: days0=127 (0b1111111) runs daily; days0=21 (0b0010101) runs Mon/Wed/Fri.
  • 1 → Single-run: days0 and days1 together form a 16-bit unsigned integer encoding the day (epoch_seconds / 86400).
  • 2 → Monthly: days0 stores the day of the month (1-31). Use 0 for the last day of a month.
  • 3 → Interval-day: days1 is the interval day (every N days); days0 is the remainder ("starting in" offset). Example: days1=3, days0=0 means every 3 days starting today.


Start-time Encoding. Depending on flag.bit[6]:

  • 1 → Fixed start-time: each of start0, 1, 2, 3 is a 16-bit integer representing an independent start time. For each:
    • If bit[15]=1 (negative value), this start time is disabled.
    • If bits[13-14] are both 0, this is a standard time (0-1439) representing the minute count from 00:00 AM to 11:59 PM.
    • If bit[13]=1, this is a sunset-based time; if bit[14]=1, this is a sunrise-based time. In either case, the remaining bits define a signed offset from the sunset / sunrise time, with bit[12] being the sign (1=negative), and bits[0-10] (i.e. start_time & 0x7FF) the absolute value of offset in minutes.
  • 0 → Repeating start-times: start0 stores the first start-time (same encoding as above); start1 is the repeat count; start2 the interval (every N) minutes; start3 unused. Example: [480,5,120,0] → start at 8:00 AM, repeat every 2 hours for 5 times.


Date-range tuple: [endr,from,to]

  • endr: Date-range enable. Must equal flag.bit[7].
  • from, to: Start and end dates, encoded as (month<<5)+day. Example: Feb 3 is encoded as (2<<5)+3=67. Defaults: from=33 (Jan 1), to=415 (Dec 31).
  • from and to are both inclusive. If from=to, it defines a range of one day. If from>to, the range wraps into the next year.


Example: {"nprogs":3, "nboards":1, "mnp":40, "mnst":4, "pnsize":32, "pd":[[3,127,0,[480,2,240,0],[0,2700,0,2700,0,0,0,0],"Summer",[0,33,415]], [2,9,0,[120,0,300,0],[0,3720,0,0,0,0,0,0],"Fall Prog",[0,33,415]],[195,16,0,[1150,-1,-1,-1],[0,0,0,0,0,0,64800,0],"Pipe",[1,67,415]]]}

14. Change Program Data /cp

Usage: http://os-ip/cp?pw=xxx&pid=xx&en=x&uwt=x&name=xxx&v=[flag,days0,days1,[start0,start1,start2,start3],[dur0,dur1,dur2…]]&from=xxx&to=xxx

Parameter Meaning
pid Program index, in the range [-1, N-1]. If pid=-1: add a new program; otherwise, modify an existing program.
en Directly set the program's enable bit (flag.bit0). If present, all other parameters are ignored!
uwt Directly set the uwt bit (flag.bit1). If present, all other params are ignored!
name Program name (URL-encoded, without quotes).
v Program body (see /jp endpoint), excluding name/from/to.
from/to Date-range parameters (month<<5)+day (see /jp endpoint).


Examples:

  • os-ip/cp?pw=xxx&pid=0&en=0: disable program 1.
  • os-ip/cp?pw=xxx&pid=1&uwt=1: enable "use weather" on program 2.
  • os-ip/cp?pw=xxx&pid=-1&v=[3,127,0,[480,2,240,0],[1800,1200,0,0,0,0,0,0]]&name=Summer%20Prog: add a new program, enabled, use weather adjustment, no date range, no restriction, weekday schedule that runs on every day, repeating start time type, start at 8:00 AM, repeat every 4 hours for 2 times, and the watering times are: station 1 – 30 minute; station 2 – 20 minutes, program name is "Summer Prog".
  • os-ip/cp?pw=xxx&pid=-1&v=[131,127,0,[480,2,240,0],[1800,1200,0,0,0,0,0,0]]&name=Winter%20Program&from=353&to=67: add a new program, enabled, using date range from Nov 1 to Feb 3, named "Winter Program", the other parameters are the same as the "Summer Prog" above

15. Delete Program(s) /dp

Usage: http://os-ip/dp?pw=xxx&pid=x

pid: Program index in [0, N-1]. pid=-1 deletes ALL existing programs.

Examples:

  • os-ip/dp?pw=xxx&pid=1: delete program 2.
  • os-ip/dp?pw=xxx&pid=-1: delete all programs.

16. Move Up (Re-order) a Program /up

Usage: http://os-ip/up?pw=xxx&pid=x

pid: Program index in [1, N-1]. pid=0 has no effect.

Examples:

  • os-ip/up?pw=xxx&pid=2: move program 3 up, before program 2.
  • os-ip/up?pw=xxx&pid=0: no effect as the program 1 cannot be moved up.

17. Run-Once Program /cr

Usage: http://os-ip/cr?pw=xxx&t=[x,x,...,x]&cnt=xxx&int=xxx&uwt=xxx&anno=xxx&qo=x

Parameter Meaning
t Array of per-station duration (in seconds). A value of 0 means that station does not run. Stations launched via this command are assigned program ID 254.
cnt Repeat count. 0: run once (no repeats).
int Repeat interval (in minutes). Must be >0 if and only if cnt>0.
uwt Use weather. 1: apply current watering level to durations; 0: no.
anno Program name annotation, in the form of >X where X is an annotation letter. See OpenSprinkler User Manual.
qo Queuing option (same as /mp). 0: append to end; 1: insert at front; 2: replace (reset all zones, clear queue, then start). Default is 2 if qo is omitted.


NOTE: If the program is set to repeat (cnt>0 and int>0), the firmware auto-creates a single-run program named "Run-once with repeat" (plus anno). This is necessary to support repeats.

Examples:

  • os-ip/cr?pw=xxx&t=[60,0,60,0,60,0,60,0]: reset all zones, then start a run-once program that turns on stations 1, 3, 5,7 for 1 minute each. As qo is omitted, this behavior is compatible with previous firmwares.
  • os-ip/cr?pw=xxx&t=[60,0,60,0,60,0,60,0]&uwt=1&qo=0: append the run-once program at the end of the queue, using the current watering level.
  • os-ip/cr?pw=xxx&t=[60,0,60,0,60,0,60,0]&uwt=0&qo=1: insert the run-once program at the front of the queue, using 100% watering level.
  • os-ip/cr?pw=xxx&t=[60,0,60,0,60,0,60,0]&cnt=3&int=15&anno=>N: similar to the first example above, but also set it to repeat every 15 minutes for 3 times. This auto-creates a single-run program, appending the annotation >N to the program name (>N tells the program to run zones in reverse order of zone names).

18. Get Log Data /jl

Usage:
http://os-ip/jl?pw=xxx&start=xxx&end=xxx&type=x
http://os-ip/jl?pw=xxx&hist=n&type=x

Parameter Meaning
start Start time (epoch seconds), inclusive.
end End time (epoch seconds), inclusive. Max span: 365 days.
hist History window in days back from today. 0: today only; 1:today+yesterday; and so on. Max span: 365 days.
type Filter special events (indicated by pid=0). Choices: s1,s2,rd,fl,wl


Log Record Format

  • [pid,sid,dur,end]: standard run
  • [pid,sid,dur,end,flow]: with flow sensor enabled (5th element)
Field Meaning
pid Program index (1-based); special events use pid=0.
sid Station index (0-based); or a special event code (string) when pid=0.
dur Duration in seconds.
end End time (epoch seconds).
flow Optional flow metric for the run (present only if flow sensor is enabled).


Special Event Code
A log record is a special event if its pid=0, in which case sid is a string code:

sid Meaning
s1 Sensor1 event
s2 Sensor2 event
rd Rain delay event
fl Flow reading
wl Watering level log


Example Request: http://os-ip/jl?pw=pw_md5&start=1413567367&end=1413657367
Response: [[3,17,616,1413511817], [0,"rd",86400,1413511845], [254,1,5,1413512107], [1,3,2700,1413552661], [5,3,1200,1413559201]]

19. Delete Log Data /dl

Usage: http://os-ip/dl?pw=xxx&day=n

day: Day index calculated as floor(epoch_seconds/86400). Use day=all to delete all logs.

Examples:

  • os-ip/dl?pw=xxx&day=16361: delete the log file for day Oct 18, 2014.
  • os-ip/dl?pw=xxx&day=all: delete all log files.

20. Change Script URL /cu

Usage: http://os-ip/cu?pw=xxx&jsp=xxx&wsp=xxx

  • jsp: UI/Javascript path (URL encoded)
  • wsp: Weather script path (URL encoded)

Example:

  • os-ip/cu?pw=xxx&jsp=https%3A%2F%2Fui.opensprinkler.com%2Fjs: set UI script path to https://ui.opensprinkler.com/js.

21. Get All /ja

Usage: http://os-ip/ja?pw=xxx
Returns a single JSON combining the return values of /jc, /jo, /jn, /js, /jp.

Variable Source
settings /jc (controller variables)
options /jo (options)
stations /jn (station names & attributes)
status /js (station status)
programs /jp (program data)


Example Return: {"settings":{...},"options":{...},"stations":{...},"status":{...},"programs":{...}}

22. Pause Queue /pq

Usage: http://os-ip/pq?pw=xxx&dur=x&repl=x

Parameter Meaning
dur Toggle-style pause. If no pause is active and dur>0, start a pause of dur seconds. If a pause is active, cancels the pause (resume stations) regardless of dur value.
repl Replace/set pause. Sets the pause to repl seconds (starts new or updates existing). repl=0 cancels any active pause. If both repl and dur are present, repl takes precedence.

Examples:

  • os-ip/pq?pw=xxx&dur=600: start a 10-minute pause if none active; otherwise cancel pause.
  • os-ip/pq?pw=xxx&repl=250: start a 250-second pause if none active; otherwise replace it.

23. Debug Print /db

Usage: http://os-ip/db
Returns diagnostics information (e.g. firmware build date, time, available heap/RAM). Authentication (the pw parameter) not required.

24. List of Reboot Causes

Interpretation of the lrbtc variable in /jc result.
Source: https://github.com/OpenSprinkler/OpenSprinkler-Firmware/blob/master/defines.h

Code Cause
0 None/unknown
1 Factory reset
2 Button triggered
3 Reset to AP mode
4 API/timer triggered
5 API triggered reboot
6 Switched from AP to client mode
7 Firmware update
8 Weather call failed >24h
9 Network failed too many times
10 NTP sync reboot
99 Power-on

25. List of Weather Error Codes

Interpretation of the wterr variable in /jc result.

Code Meaning
0 Success
-1 Request not received
-2 Cannot connect to weather server
-3 Request timed out
-4 Received empty response


Positive codes are application errors from the weather service. Refer to https://github.com/OpenSprinkler/OpenSprinkler-Weather/blob/master/src/errors.ts