API – Change Station Names and Attributes

[DaveC]

What values (xxx) are used for the i, d, and q parameters? Since the sid is specified (or is it?) these seem like binary parameters, i.e. 1 (on) or 0 (off). However, the description calls it a bit field.

[DaveC]

I wiresharked the web app to see what it does when zone 1 is disabled and then enabled. The results were a bit surprising:
GET /cs?pw=*****&s0=FrontLawn+Left+1&q0=255&q1=255&q2=255&i0=255&i1=255&i2=255&d0=1&d1=0&d2=0
GET /cs?pw=*****&s0=FrontLawn+Left+1&q0=255&q1=255&q2=255&i0=255&i1=255&i2=255&d0=0&d1=0&d2=0

It appears that the ‘d’ parameter is a binary parameter (on or off). Great. But…
Why are all the other parameters included, why that collection of parameters and zones and why are ‘q’ and ‘i’ treated differently than ‘d’? Specifically:
Zone 1 name (unchanged)
Zones 1 – 3 Ignore Rain parameter (unchanged) AND each zone specified as a bit field (255). It appears that to change the Ignore Rain (or Sequential) parameter for say Zone 1, one would specify it as &i=254. Yes? Why not binary?
Zones 1 – 3 Sequential parameter (unchanged) AND each zone specified as a bit field (255)
Zones 2 and 3 Enable parameter (unchanged)

I did all of this with FW 2.1.5

[Ray]

As explained in the API document of 2.1.5, section 8:
https://opensprinkler.freshdesk.com/solution/articles/5000632570
these parameters are all ‘bit fields’ — each value encodes the 8 bits of one board. For example, d0 corresponds to ‘disable’ flags of the 8 stations on the master controller, d1 corresponds to the next 8 stations and so on.

I should add that the reason it’s done this way is for legacy reasons: in the past names and attributes of all stations are edited on one single page and submitted together with one call to the /cs command. So encoding the data into bit fields significantly reduces the amount of parameters. Now that the UI allows editing one station at a time, in theory we don’t need to use bit fields any more, but we decided to still keep it the same way for backward compatibility reasons.

[DaveC]

OK. I understand the legacy rational, but it does make it more complicated for the programmer. A simple station attribute change becomes a ‘group of 8’ station update (even the use of the term ‘board index’ has a legacy definition since expansion boards have 16 stations on them). OK, I’ll stop whining…

In the ‘cs’ definition the ‘?’ is used in 2 ways: It is the station index when use with ‘s’ and it is the board index when used with ‘m’ and ‘n’, both of which are stated explicitly and the examples show them, For ‘i’, ‘d’ and ‘q’, ‘?’ is not defined explicitly nor are there examples for them. I can see what you intended now, but since these are all per-station attributes, it seemed like ‘m’ and ‘n’ were the exceptions because the use of ‘?’ was explicitly defined for them.

My suggestion for the API doc: For ‘i’, ‘d’, and ‘q’, state explicitly that ‘?’ is the board index in the same why that it is done for ‘m’ and ‘n’ OR at the start of the Parameter section state that ‘?’ is the board index except when used with ‘s’. Also, there should be a note to remind the programmer that when changing a station attribute, other than its name, you have to preserve the state of the other stations on that board index.

Thanks

[Author]

Posts