-
Notifications
You must be signed in to change notification settings - Fork 2
API Detail
The fountain can be controlled through its "public" API by POSTing a request to php/act.php. The Webfront will return JSON with at least one field, success, either true or false, indicating "in general" if what you wanted to happen happened.
It's RESTful, I suppose, although for most operations (like controlling valves) you'll need to initialize your session (one of the possible request 'opcodes') to make sure your application is allowed to assume control of the fountain at that time (and something more important isn't using it).
Every API request requires the two fields key and request to be populated. key is a 64-byte API key generated for your application's use - this key is used by the native server to manage authorization and priority of requests. We should be doing this over HTTPS, but we're not (yet). Yes, it's vulnerable to packet sniffing and replay attacks, but for the most part this communication is all happening on our intranet, so we should be relatively safe.
The request field will be the name of one of the allowed actions detailed below. Any parameters a request needs are enumerated below the action title.
I'll add more as time goes on - for now we've just got the bare minimum here for remotely controlling the fountain.
Just pass this request with your API key (which should be POSTed with any request anyway) and check the JSON that gets returned - if its success field is true, you've got control of the fountain!
This doesn't guarantee how long you'll have control - remember to check the JSON on other requests to see if it fails, and if it does suddenly, check to see if another requestControl gets it back (returns success:true). Don't try to fight too much with other API users who may be contending for control at the same permissions level ;).
For any valves you want to set to either on or off, pass its name as a parameter and a true or false as a value. true corresponds to a valve being enabled, and false will close the valve. Parameter names should be in the format V1, V8, V10, HC, HR, etc.
You can set multiple valve states at once by passing multiple parameters. Alternatively, you can pass a single parameter STATE which is an integer representing the entire state of the valves.
Possible values for parameters are: V1 (bit 1 from the right), V2 (2), V3 (3), V4, V5, V6, V7, V8, V9, V10 (10), H1 (Vertical jet) (13), H2 (14), H3 (15), H4 (16), H5 (17), H6 (18), H7 (19), H8 (20), H9 (21), H10 (22), VC (11), VR (12), HC (23), HR (24)
Similar to setValveState, except a value of true corresponds to toggling a valve rather than setting it to on. A value of false or just not passing the valve name as a parameter at all will be ignored.