Skip to content
Device API v1 is enabled per client on request and is not on by default. See what is available today.

Chemistry settings

Both endpoints take the complete settings object as returned by chemistryCard. The controller replaces every field with what you send, and any field you omit is sent as 0 or false. Always read, modify and write back the whole object.

Values of 0 are treated as “not set” by validation and pass through unchanged, so a missing numeric field will not be rejected. On the controller 0 is not a safe default: a dose length of 0 keeps the doser on continuously while the reading is out of range, a daily limit of 0 stops dosing altogether, and a target of 0 makes every reading out of range. Never send a partial object.

The remaining drum volumes count down as the controller doses, so take the values from a fresh read: the first chemistryCard after a long idle period can be a cached copy (see How reads work), and writing a stale remaining volume back erases the usage since then. A remaining volume larger than the drum volume is set to 0 at the next dose.

The dosing logic runs only when the controller’s chemistry probe is enabled, which is the normal state.

POST…/setPhSettings

{
"ph_dosing": true,
"ph_dosing_time": 60,
"desired_ph_level": 74,
"acid_drum_volume": 20000,
"remain_acid_volume": 10000,
"reset_acid_volume": false,
"max_dose_pre_day": 10,
"dose_intervals": 30,
"ph_dose_rate": 100
}
Field Type Range Meaning
ph_dosing bool Acid dosing enabled
desired_ph_level int 60 to 85 Target pH × 10
ph_dosing_time int 1 to 600 Length of one dose, seconds
dose_intervals int 1 to 120 Minimum gap between doses, minutes
max_dose_pre_day int 1 to 50 Daily dose limit, number of doses. The count resets at 03:01 controller local time
acid_drum_volume int 1 to 1,000,000 Drum capacity, mL
remain_acid_volume int 0 to 1,000,000 Acid remaining, mL
reset_acid_volume bool true sets the remaining volume to acid_drum_volume from this same request, overriding remain_acid_volume. Acts once; reads always return false. It does not reset the daily dose count
ph_dose_rate int Doser flow rate, mL per minute. Used only to estimate the remaining volume (the controller counts down rate / 60 × dose time per dose, with the division rounded down to whole mL per second, so a rate below 60 stops the estimate). It does not change the dose itself. The controller’s default is 120; keep the value it reports

current_dose_today and ph_doser_timer are read-only and ignored if sent.

Response: 200 with data.message holding the controller’s acknowledgement, a JSON string such as {"status":"SUCCESS","message":"Successfully update pH Settings","info":""}. The write waits up to 3 seconds for the controller, plus any time spent behind other commands to the same controller, and a timeout returns 500 with failed to set pH settings: timeout waiting for response. A body the controller cannot parse gets no reply at all and also ends as a timeout. Out-of-range values return 400, listing every violation:

{ "status": "FAILED", "message": "invalid pH settings: desired_ph_level must be 60-85 (got 90); dose_intervals must be 1-120 (got 121)" }

POST…/setChlorineSettings

{
"orp_controlled": true,
"desired_orp_level_mineral": 650,
"liquid_chlorine_dosing": false,
"desired_orp_level_liquid": 650,
"chlorine_dosing_time": 60,
"chlorine_drum_volume": 20000,
"remain_chlorine_volume": 15000,
"reset_chlorine_volume": false,
"max_dose_pre_day": 10,
"dose_intervals": 30,
"liquid_dose_rate": 100,
"mineral_max_duration_preday": 0
}
Field Type Range Meaning
orp_controlled bool true: the salt or mineral chlorinator output is switched by ORP, on below the target and off above it with a 10 mV band, only while the pump is running and the readings have settled. false: the output is held off. The controller cannot tell whether an ORP probe is fitted; without one the reading stays below the target and the chlorinator runs whenever flow is stable, and because the output keeps the pump running (see interlocks) the pump then runs outside its schedule. Set false or a daily cap on such installations
desired_orp_level_mineral int 300 to 900 ORP target for the mineral or salt chlorinator, mV
mineral_max_duration_preday int Daily run-time cap for the mineral or salt chlorinator, seconds; 0 for no cap. mineral_dosing_duration_today reports the seconds used so far
liquid_chlorine_dosing bool Liquid chlorine dosing enabled
desired_orp_level_liquid int 300 to 900 ORP target for liquid chlorine, mV
chlorine_dosing_time int 1 to 600 Length of one liquid dose, seconds
dose_intervals int 1 to 120 Minimum gap between liquid doses, minutes
max_dose_pre_day int 1 to 50 Daily liquid dose limit, number of doses, reset at 03:01 controller local time
chlorine_drum_volume int 1 to 1,000,000 Drum capacity, mL
remain_chlorine_volume int 0 to 1,000,000 Chlorine remaining, mL
reset_chlorine_volume bool true sets the remaining volume to chlorine_drum_volume from this same request, overriding remain_chlorine_volume. Acts once; reads always return false
liquid_dose_rate int Doser flow rate, mL per minute, used only for the remaining-volume estimate as for ph_dose_rate; keep the reported value

current_dose_today, liquid_doser_timer and mineral_dosing_duration_today are read-only and ignored if sent. Validation errors use the prefix invalid chlorine settings:.

This write also waits up to 3 seconds; a timeout returns 500 with timeout waiting for response. The controller’s acknowledgement text for this command reads Successfully update pH Settings; it is the chlorine settings that were written.

Both writes clear the cached dashboardInfo and the relevant settings read, so the next chemistryCard shows the new values.