Version 2.1.6

[Studley]

Martin,

Unfortunately restarting does not help. I have tried many locations (London, Tokyo, Melbourne) and after restarting the time is still 14 hours out with -4:00 still showing in time zone.

I have also wiped the directory and performed a new git pull with the same result…

Is there somewhere in the code I can manually force +10:00?

[Samer]

I will look into why this isn’t working but in the meantime, as a work around:

1) Export your configuration
2) Look for the variable “tz”:
3) Change the value using the following encoding:

minute = ( minute / 15 >> 0 ) / 4;
hour = hour + ( hour >= 0 ? minute : -minute );

tz = ( ( hour + 12 ) * 4 ) >> 0;

4) Import the new configuration

You can also use the API to modify the “tz” variable however the command to change that option will require you to provide all binary based options otherwise it will clear them. The method above avoids any disturbance to those variables.

I will let you know if I can reproduce or fix the issue with OSPi.

Thanks!

[Studley]

That worked perfectly, thank you.

[Anonymous]

Hy all,

I would like to upload the 2.1.6.hex with avrdude, please, give me a link for downloading the FW.

regards,

zipp….

[Ray]

The compiled firmwares are all in this Github repository:
https://github.com/OpenSprinkler/OpenSprinkler-Compiled-Firmware

[Anonymous]

Dear Ray,

Thanks! I’m learning something new gevery day about OS.

Regards, zipp….

[sakos]

Hi,

It seems that the Master Off Delay does not work. Despite it is set to 5 or 10 seconds it switches of exactly at the stop of last valve. It works if it was set to 0.

[Ray]

@sakos, thanks for reporting this. I checked the firmware and there is indeed a bug that causes the master station to turn off as soon as an associated station turns off. So a positive master off delay behaves the same as if it’s 0. However, a negative master off delay should still work as intended. We will address this in the next firmware update.

[DaveC]

Hi,

Do you have a target time for when you will update the API document? While I understand many of the change that were made, I roll my app based on the doc. It’s also an opportunity for you to get feedback on the doc. If you have a draft in progress and want feedback on it before you publish it, I’m happy to do that.

[Ray]

I just finished updating the user manual (and will post this shortly today). I am working on updating the API document and it should be available this weekend. Sorry about the delay.

[DaveC]

No worries about the time. Thanks!

[Ray]

The user manual and API document of firmware 2.1.6 are both posted today:
https://opensprinkler.freshdesk.com/support/home

[DaveC]

Thanks for posting the 2.1.6 API and User Manual.

As far as I can tell my feedback on the 2.1.5 API doc is still valid for 2.1.6.
https://opensprinkler.com/forums/topic/api-document-feedback/
I’ll provide any additional feedback when I complete updating my app for 2.1.6

[LeighGr]

Darn. That Master Off Delay bug is not what I wanted to hear. I’ve a remote station, configured as a master, to switch on the borehole pump on whenever the main master switches on, which controls the tank pump. The tank empties quicker than the borehole can fill is, so I was hoping to add a master off delay to the remote master.

Besides the fact that the setting has no effect, I’d like to be able to have the master off delay to be as high as an hour, as the current 60 seconds isn’t going to help. Currently we manually control the borehole pump, but sometimes wake up in the middle of the night to an overflowing tank, when we’ve forgotten to turn if off.

I’ll have to go back to the drawing board. Maybe have the remote master trigger an Arduino which then adds the off delay?

[sakos]

Hi,

I would do like this.
Configure two independet masters. One for the tank pump, one for the borehole pump. Assign both masters to normal stations.
Add a virtual (not equipped) station at the end of your irrigation programs. Assing only the borehole pump as master to this virtual station. The lenght of virtual station timing will act as a delayed run of your borehole pump. You can program any delay whatever you want within seconds to several hours range. Even this delay can be tuned according to the water consumptions of individual programs. I mean that shorter programs need less extra run of borehole pump.

[Ray]

@sakos: thanks for sharing the tip. Indeed if you need to delay master off at the end of a program, the work-around is to create a ‘dummy’ station (virtual station as you said) and assign it to activate master. This way, this station will keep the master on for its duration.

[DaveC]

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.

[BinaryOS]

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.

Thanks for this info DaveC, I referenced the API document only to find my logging had been turned off when adjusting wl (watering level) 8-(

Bit of a trap when the API Document is incorrect.

[Ray]

Thanks DaveC — will be updating the API document shortly and thanks for the detailed comments and corrections!

[Ray]

I just updated firmware 2.1.6 API document, addressing most comments DaveC described. First of all, thanks to DaveC for sending detailed comments, very much appreciated. The updated API document can be found here:
https://opensprinkler.freshdesk.com/helpdesk/attachments/5073792611
There doesn’t seem to be a way to retain the attachment ID of the previous version, so the PDF link is different from the previous version.

Let me briefly go over the comments and provide some more background information:

* MD5 hash password: the firmware itself actually is not aware of the particular format of the password — it merely stores the data that’s passed to it, and compares a password with what it has stored. However, the app automatically computes the MD5 hash and when you type in a plaintext password in the app, it always converts that to MD5 hash and sends that to the controller. In that sense, if you only use the API to access the controller and never use the app, you can still store plaintext password (but this is now strongly discouraged).

* Location string: similar to the password, the firmware is not aware of the particular format of the location string. When you use the app to set the location, it always converts it to a GPS coords (because Wunderground API works most reliably with GPS coords and not city,state name or zip code). Except if it’s a PWS station ID, then the app preserves it. Again, if you only use the API to access the controller and never use the app, you can still pass a zip code to it and it won’t convert that to GPS coords on its own.

* Program index starting from 0 vs 1: I know this is confusing and you are right that most of it is inherited from legacy code. It’s hard to change them right away because the app is designed to be compatible with all versions of firmware, and it’s better to keep the old way to minimize the burden of customizing the app for every different version of firmware.

* Missing options: good catch on o36 — this is completely my fault for missing it, and it’s now added. The other missing option is o40, which is firmware minor version (read-only)

* Reboot: this will be partially addressed in the upcoming firmware 2.1.7, which has added support for IFTTT and can send push notifications on ‘reboot’ events. It doesn’t report the cause of the reboot yet, but that will be the next step.

Again, thanks for the comments. I apologize for my very slow response time, but please do not be discouraged by that.

[Author]

Posts