API – Change Options Command

[DaveC]

There are 2 notes to point out that binary parameters not specified are set to 0 and binary parameters specified are set to 1 regards of their value. OK, but…

This is clumsy and it breaks a nice attribute of JSON, backward compatibility.
Compatibility: In other requests and commands when you, OS, add a new parameter it doesn’t break app compatibility. The app provider can take advantage of the new item if and when they want to. In Change Options, if you, OS, were to add a new binary parameter, apps would have to change to maintain predictable behavior.
Clumsy:
You can’t just read the current values and set the parameters accordingly because the values are ignored. You have to include or not include the parameter based on its value… in every /co command. Debugging is more complicated because you have to insure that you properly maintain other values when trying to change just one.
Examples:
Some of the examples provided are incorrect. Either the commands are wrong or the descriptions of them are. E.g.
http://os-­‐ip/co?pw=xxx&o17=30 (set station delay time to 30 seconds)
This command will also set the following items to off: NTP, DHCP, Use Rain Sensor, Rain Sensor Type, Ignore Password

Here are some details from my experience:
I was adding the capability to set the watering level in manual mode. I chose to debug my watering level logic before adding the code to include (or not include) all the binary parameters to maintain their current state in the /jo command when setting o23 (wl). I did this to 1) validate the meaning of the note because it didn’t seem like the way it should work (wishful thinking on my part) and 2) to debug one thing at a time. I knew what I was doing so I’m not complaining that I had to go back and set up my OS options (NTP, Rain Sensor Type). Fortunately I run with a static IP, so there was no impact of turning DHCP off. One thing I didn’t expect but understand is that the state of ‘rs’ in /jc changed because ‘rso’ was changed from its default of 1 (normally open) to 0 by not including it in my /co command. Even though I am not using a rain sensor, rs now indicates rain. I don’t think the Rain Sensor Type should affect Rain Sensor Status if Use Rain Senor if off.

OK, so I can make it all work right (until you add a binary option), but what is the advantage of having it work this way and, would you consider making it work like /cv, where binary values do not have to be maintained.

I also just noticed that logging was disabled as result of my action. This was unexpected because it is not listed in the /co options table. It is in the /jo list, after uwt. It is not listed as a binary value but it is and it should be listed (and shaded) in the /co options table.

[Samer]

First let me say I agree with you 100%. Let me explain what happened in the design process.

Initially, Ray built the UI and during that time a very basic HTML form was used without Javascript to send the values. Well, the way forms work for a checkbox is an unchecked box will simply not be sent. This makes sense in the setting of the web however this was interpreted as being unchecked by the firmware because it only expected modification from the UI (not via an API).

This limitation had been carried forward for the simple fact of keeping things backwards compatible. However, this can be changed and we will reopen the discussion to change this moving forward.

In regard to the incorrect example, you are right and we will update the documentation to reflect that.

For the rain sensor type effecting the rain sensor flag itself, this shouldn’t happen. I am going to look into this and get back with you.

Thanks for the information!

[DaveC]

Let me know if I can help with anything. Hopefully other user’s of the API will chime in with their views so you get an idea of the impact to them and their preferences.

Thanks

[DaveC]

What option index for /co corresponds to the ‘lg’ state in /jo? The logging state needs to be preserved when sending a /co command but it’s not in the options table. o40 perhaps?

Thanks

[DaveC]

I wiresharked a /co command and it appears that the Logging State is o36. Please confirm.
I’m curious about the tnn parameters that are not in the API and appear to specify the date/time in addition to ttt. Care to share or this a code exercise? 🙂

[DaveC]

OK, o36 is the logging state option. It needs to be added to the doc and shaded.

In working with the /co command, I noticed a couple of minor behaviors that I didn’t expect.
I incorrectly tried to use &wl to specify the water level (rather than &o23). The response to the command was success. As expected the water level was not set, but I would have expected an error return.
I also incorrectly specified a parameter without a value (e.g. &o2 rather than &o2=1). The response was success. I would have expected an error. Since it was successful, what did OS do? Did it treat it as if the option wasn’t specified, setting the the option to 0, or do nothing with that option?

[Ray]

@DaveC: I apologize that the API document is missing the o36 option. For future reference, you can find the list of options in the source code, specifically in defined.h:
https://github.com/OpenSprinkler/OpenSprinkler-Firmware/blob/master/defines.h
the index is the index of an option in the list (starting with OPTION_FW_VERSION which is o0).

The firmware handles the /co command in the following way:
– it loops through all option names in the form of o?? and searches the GET command to see if the option name exists. It doesn’t reject options that are not in that format. For example, if you send an option named ‘wl’, it won’t report an error and that options is just ignored.
– because o2 is the Use NTP option and it’s a binary option, you don’t need to specify a value — if the option name exists, it’s assumed the value is 1. If that option name doesn’t exist in /co command, it’s assume to be 0. This is explained in the API document, and is due to the way HTML forms process checkbox elements.

[DaveC]

Thanks for the src pointer. I’ll try to spend more time looking at your code for reference. I’ve focused all my spare time on getting my app fully functional.

Initially, I interpreted the API document as you say; no need to specify a value. However, I’m *fairly* sure that when I tried a /co command with the ‘need to preserve’ options in the form o2, o3, etc. (i.e. wtihout any values), it behaved the same as not specifying the option. I’d have to go and try it again to be sure. In wiresharking what the Web GUI does, I decided that I should specify a value, even though the value is ignored. That is working fine.

If you want me to test the ‘no option value specified’ case to insure the doc is correct I will. It’s relatively easy to do.

[BinaryOS]

To modify water levels I’d much rather use
http://os-­‐ip/co?pw=xxx&wl=30
and not worry about turning on/off other configuration options.

[Samer]

We are fixing the binary options being required in firmware 2.1.6.

Thank you for your patience.

[Author]

Posts