Feedback on the 2.1.6 API
As someone trying to provide SW that can be used by others to integrate OpenSprinkler with Crestron automation systems, the API document is not complete enough to provide all the info needed to code to. The API itself also has some shortcomings that make using it in this kind of environment a bit difficult.
Here’s my accumulated feedback on the 2.1.6 API, both the document and the API itself with suggestions.
Section 1 – Introduction
“You can find online MD5 hash tools to convert plain text password to MD5.”
It should also be noted that some of these tools produce MD5 hashes with uppercase hex digits, but OpenSprinkler requires that they be lower case.
PIDs are used inconsistently across the API. In some cases, like Section 2 and Section 17, PIDs start with 1, i.e. PID = 1 refers to the first program. In other sections, such as Section 13, PIDs start with 0, i.e. PID = 0 refers to the first program. I think I understand why this occurs, but it is important to be clear about it in the doc. It should be noted in this section to warn people to watch for the different usage.
Section 2 – Get Controller Variables
rdst:
Typo (no -> not)
rdst: Rain delay stop time (0: rain delay no in effect;…
rdst: Rain delay stop time (0: rain delay not in effect;…
loc:
It appears that this variable can have different returns depending on how location is setup. E.g.
“loc”:”City, State”
“loc”:”40.57537,-104.83635″
“loc”:”pws: KMANANTU15)”
Is a zip code a valid return? The example in Section 5 shows setting location by zip code.
The document should describe the different forms of returns that may need to be parsed. Are there any others?
Useful to note both here and in Section 5 that loc is read as a controller variable but set as an option.
ps:
“pid is the program index (0 means non)”. What is “(0 means non)” trying to say? E.g. That this station is not part of any program? OR that the station running was not run as part of a program? OR ?
This is a case where the special use of PID = 0 should be clearly described.
sbits:
If this is the same data as /js sn: but formatted differently, it would be helpful to say that in both sections. If it is not, then the sections should describe in what situations they can be different.
lrun:
Since this is the first reference to “station index”, it would be helpful to state that stations start from 0, as is done in later references.
curr:
flwrt:
flcrt:
In addition to describing what they are it would be useful to provide any other info that might be needed when using them. E.g. the range of values in the return and how to map flow clicks to a rate (e.g. it’s flow sensor specific). Updating the /jc example (as mentioned below) would probably cover most of this.
wto:
Describe the return so that the contents can be parsed and used. It is partly described in Section 5, but it appears that the return here is not exactly the same as the string used to set it (in Section 5).
My system, which does not use weather options, returns: “wto”:{} So, it can be null.
I’ve seen an example in the forum that looks like: wto”:{“h”:90,”t”:90,”r”:90}
The doc should say that it can be null or that it contains {…} and what the values mean. Since the doc refers to “weights”, I assume that “t”:90 does not mean 90 degrees.
It is useful to note that it is read here but set by Change Options.
Example Return: It is out of date. It would be useful to give a 2.1.6 example including the use of the new variables. The examples in some other sections could also benefit from updates.
Section 3 – Change Controller Variables
rsn:
“Binary Value” (0 or 1) would imply a that a 1 causes a reset, but sending any value, either a 0 or a 1, causes the reset. Is this what you intended? The doc should state the behavior.
rbt:
Is the behavior in rsn also true for rbt?
rd:
What is the maximum number of hours that can be set? The User Manual does not address this either. It appears to be quite large. While it’s unlikely that someone will want to set it to an extremely large value, it would be good to know the range and perhaps to limit it to prevent unintended issues. I assume you would get {“result”:17} “Out of range” if you set it larger than whatever the maximum is. As a quick experiment I set it to 4000 days (96000 hours) in the GUI and it set the rain the delay to Apr, 2019.
re:
Is this a binary value where 1 = use as remote extension and 0 = remote extension mode off?
As is the case with some items where the get and change are handled in different major sections, this one is set via Change Controller Variables but read via Get Options. It would be useful to highlight this asymmetry where it occurs, perhaps even in Section 1 so people are prepared for it,
Section 4 – Get Options
den:
I think this is the same as ‘/jc en’. If so it would be good to say that in both sections. In cases where the same data is set or returned by different API calls (sometimes in a different format), it helps to note that they are the same.
uwt:
“Water restriction information for California is encoded in the last bit.” I think a bit more information would be useful on this. What is the encoding? Does it mean that setting high order bit enables CA water restrictions? Is it only valid when the adjustment method is other than manual i.e. 129 (0x81)? What happens if the value is set to 128 (0x80)?
hwt:
I understand the 0x terminology but it would be more straight forward in the doc to state what the actual return values are. E.g. 0xAC = AC power type returns “hwt”:172. Yes, 0xAC = 172 decimal, but since the return is in decimal why not make it simple?
Section 5 – Change Options
loc:
“Location string (url encoded).” What are the valid ways that a location can be set? This is a similar question to the question in Section 2. E.g. Zip Code? ‘City, State’? ‘lat,long’?
Useful to note that it is set here, but returned in Get Controller Variables.
wto:
Typo: (in -> is) “Weather options which in a JSON…” -> “Weather options which is a JSON…”
It is not clear from the description how to specify this parameter. More info is needed and an example.
o36:
036 is missing. It is the option to set the state of logging and it is one of the ‘special’ binary options. It should be added to the options list with shading as it may need to be included in the command to maintain the state of logging.
Are there any others that are missing? o40 is a gap (as is o36). Does the o40 gap represent another missing item? Is it a new shaded item?
Examples:
The examples should be updated to be clear about the effect of including/omitting the shaded options.
Using the first example item: ‘http://os-ip/co?pw=xxx&loc=95050’
In addition to changing the location, this command will turn off ntp, dhcp, use of the rain sensor, and logging,; set the rain sensor type to normally closed; and enforce using a password.
I understand that this special case of preserving options is the result of how the interface developed over time and it preserves compatibility, BUT it is also a source of bugs for an app developer. If you are not going to change the API then more attention to the info in the doc is needed. Note: Because o36 is missing I had to discover why logging kept being turned off when I changed options. I provided this feedback back when the 2.1.5 doc was released and it was ack’d. However, the 2.1.6 doc still has the error.
Section 6 – Set Password
The current password, supplied in the command, must be MD5 hashed, but the new password is in clear text. It would be useful to state this explicitly to avoid any confusion with the info in Section 1.
Section 11 – Manual Station Run
It should be noted here that all manual station runs will show up as PID 99 in the ‘ps’ field of Get Controller Variables.
Section 16 – Start Run-Once Program
It should be noted here that all run once programs will show up as PID 254 in the ‘ps’ field of Get Controller Variables.
As suggested in another forum thread, it would be useful to allow a PID to be specified as a run-once program parameter. This would allow bringing some other program attributes with it, e.g. repeat data.
Section 17 – Get Log Data
It should be noted that hist = 0 delivers the log data for the current day. Hist = 1 delivers the day before and the current day, etc.
As the examples show, when the PID = 0, the next field is not the SID but the event code. This should be noted in the description. This is another case where PID = 0 has a special meaning.
The ‘Return Value:’ description does not seem to be correct with the addition of the 2 new event types. The events, fl and wl, likely do not provide a duration and an end time in their arrays. What do the return arrays for these look like?
Suggestion:
[Re]start/[re]boot events should show up in the log along with their cause, when it is known. Part of the value of the log is to know when something unexpected or wrong has occurred. Restarts are significant events. E.g. If a program is running and there is a power fail / restore, the remaining part of the program that was running will not run and potentially some future programs will not run. Looking at the log you would only see that something you expected to run did not. If the restart event was there you would have an idea why.
Power fail/restores are not the only thing that can cause a reboot. A reboot can be requested through the API. In this case you know what caused it. It is also done internally by the FW if there are no successful server (aka weather) call in 24 hours or if the network checks fail 6 times. Again you know what the cause is. These types of reboots should be in the log along with a code to indicate the cause. I understand that the FW generated reboots try not to interfere with running programs, but it is not clear if an API requested reboot does.
There are probably 2 that you can’t distinguish from one another: A crash/restart and a power fail/restart, but crashes are hopefully infrequent.
Here is an example of an event you could add to the log: rbt. The log entry array might look like: [0, “rbt”, restart code, 0] where restart codes are: 1 – Unknown (most likely powerfail), 2 – API initiated, 3 – Server call failed, 4 – Network issue, etc.
Section 20 – Get all
The description ‘This command returns the combined result of /jc, /jo, /jn, /js, /jp in one command.’ That implies that it looks like what you would see if you concatenated the returns from the 5 requests. However, that is not the case. It actually appears to be exactly what you get when you export the config file. I.e. the 5 returns are concatenated and then wrapped in {settings: …. } The description should be more accurate.
One more suggestion: Having some form of unsolicited notification of change would make the dealing with this device more efficient. This would particularly helpful when associated with data that does not change frequently such as Zone data or Program data. The Web GUI and Mobile App typically do not run all the time, so polling for everything may be an acceptable trade-off. When integrated into a larger automation system, regular polling for Zone and Program data adds overhead. my solution has been to have settable and different polling intervals for for different kinds of data, but this creates larger windows where data can be stale.