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.
pH dosing
Section titled “pH dosing”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)" }Chlorine and ORP
Section titled “Chlorine and ORP”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.

