FAQ & tips

Three things, each worked out separately for the pool and the hot tub:

• Chlorine now. How much chlorine is probably left since your last test, so you know when it’s getting low without testing every day.
• pH now. pH creeps up over time; it estimates how far it has gone, and what the acid or base you logged did to it.
• Your routine. A chemical you add on a regular schedule, in about the same amount, is suggested when it’s next due.

When a prediction says chlorine is probably low or pH has drifted, a card suggests the dose. Log it in one tap, or test first. Predictions can also arrive as notifications, at the time they’re expected to come true.

From your own water. Every pair of tests is a small experiment: what the water had, what you added in between, how many swam, and what was left. Over a few weeks that adds up to how fast your pool loses chlorine in a day and to each swimmer, and how fast its pH rises. A sunny, busy pool and a shaded, covered one learn very different rates.

Recent weeks count more than older ones, so it follows the seasons: a pool that uses more chlorine in July than in May is predicted for July. Everything is worked out on your phone from your log, each time it changes; nothing is sent anywhere to do it.

The chlorine prediction needs at least five chlorine tests over two weeks or more. Tests between 2 hours and 10 days apart are the useful ones. Allowing for swimmers needs a few gaps between tests with swims logged in them. Until then, the status card estimates with typical rates and says it’s less sure.

Predictions are on for the pool to begin with, and off for the hot tub. Turn them on or off for each in Settings.

• The last test is over 10 days old: it asks for a test instead of guessing.
• Something was added that it can’t put a number on, such as trichlor tablets in a floater, bleach of unknown strength, or a product it doesn’t know. The stretch around it is left out.
• The water was changed. A water change starts the water over, so it’s left out too.

• Log everything you add, with the real amount and product (“Liquid Chlorine 10%”, not just “chlorine”).
• Log swims and soaks, roughly: two people for an hour is enough.
• Get the volume right in Settings: every ppm is worked out from it.
• Test at a similar time of day, when you can: sun makes the afternoon different from the morning.
• Use a drop-count kit (FAS-DPD, like the Taylor K-2006) if you can. Test strips are too coarse to learn from well.

Every estimate carries a range that widens the longer it’s been since the test, and it’s wider still until the app has learned your water. Tap a value on the status card, or open a prediction, to see the range and what it was worked out from. A prediction is a reason to test or to dose, never a replacement for testing before you swim.

From what’s known about the water now:

• Some things decide it outright: a chemical added too recently to have mixed in, cloudy or green water, or a hot tub over 104 °F.
• Chlorine and pH are estimated from the last test, since they’re rarely tested right before a swim. Each estimate has a range, and the answer follows how likely it is that the water is in the safe range.
• What isn’t known (CYA, which sets how much chlorine is enough, or pH) makes it less sure.

So it says Safe to swim when it’s confident, Should be safe when it probably is, and Not sure: test first when too much isn’t known. In a hot tub it says “soak”.

The status card counts it down, with the pump or jets running: longer for granules that dissolve slowly or heat the water (cal-hypo, dichlor, calcium chloride) in a pool. If a product’s label says to wait longer, the label wins.

Stabilizer (CYA) protects chlorine from the sun, but it also holds most of it back, so the more CYA the water has, the more chlorine it needs to do the same job. H2Oracle uses Trouble Free Pool’s chlorine levels for your CYA, and the reading form says which it used (“For CYA 45: target 6–8 ppm, minimum 3”). Without a CYA test it uses a fixed range, so test CYA every month or so.

SLAM (Shock Level And Maintain) is Trouble Free Pool’s way to clear algae or cloudy water: raise chlorine to a shock level set by your CYA and keep it there until the water passes three checks. When a test finds combined chlorine well above its limit (and CYA has been tested), the reading form recommends a SLAM, and Start the SLAM lays it out as a plan: the dose, when to top up and test again, and the checks, with a reminder for each step. For green or cloudy water, Trouble Free Pool’s advice is a SLAM too.

No. In the reading form, switch Enter as to Taylor drops and type the drops you counted (FAS-DPD chlorine, TA, hardness), the pH color and the CYA tube mark. It does the math for the sample size you used, and keeps the drops with the reading. It also does the acid and base demand test, and reads phosphate off the K-1106 cards.

Yes: choose Bromine for it in Settings. Ranges become bromine’s (4–6 ppm in a hot tub, 3–5 in a pool, from the CDC), Taylor drops count for bromine, and CYA and combined chlorine aren’t asked for. Low bromine is raised with chlorine or an oxidizer, which turns the bromide already in the water back into bromine. After a water change, add sodium bromide to build that bromide up again: the water change explains how much.

Turn on Salt water for that pool or hot tub in Settings and enter the range from the generator’s manual. Tests then ask for salt, the form says how much pool salt to add (in 40 lb bags for a pool) or how much water to replace when it’s high, and salt gets its own chip on the status card.

The rule of thumb: hot tub water lasts for about gallons ÷ 3 bathers, one person in for one soak. A 400 gallon tub is good for about 133. H2Oracle counts the people in the soaks you log since the last change, works out how quickly you’re using it, and dates the next change. It’s also due after 6 months however little it’s used, since everything added stays in the water (change or turn that off in Settings). A partial change gives back its share.

To begin with: a hot tub’s filter is rinsed every 2 weeks, deep cleaned in filter cleaner every 3 months and replaced every year; a pool’s is cleaned every 3 months and replaced (cartridges) every 3 years. Set your own in Settings, or turn any of them off. A replacement counts as a clean, and a clean as a rinse.

Settings › Webhook sends each chemical, test, swim and upkeep you log, edit or delete on that phone to an address you choose, as it happens. Point it at Home Assistant, Node-RED or anything that takes a webhook, and start an automation: run the filter pump for an hour after chemicals go in, turn on the jets, or note a test in your logbook.

1. In Home Assistant, go to Settings › Automations & scenes, create an automation, and add a Webhook trigger. Give it an ID such as h2oracle-pool.
2. In H2Oracle, open Settings › Webhook, turn it on, and enter the address: http://homeassistant.local:8123/api/webhook/h2oracle-pool (use your Home Assistant’s own address).
3. Tap Send a test. “Sent” means Home Assistant got it.
4. Choose which types to send, and save.

An automation that runs the pump for an hour after a chemical is added to the pool:

alias: Run the pool pump after adding chemicals
triggers:
  - trigger: webhook
    webhook_id: h2oracle-pool
    allowed_methods: [POST]
    local_only: true
conditions:
  - condition: template
    value_template: >
      {{ trigger.json.action == 'created'
         and trigger.json.event_type == 'chemical'
         and trigger.json.water_body == 'pool' }}
actions:
  - action: switch.turn_on
    target:
      entity_id: switch.pool_pump
  - delay: "01:00:00"
  - action: switch.turn_off
    target:
      entity_id: switch.pool_pump

Change switch.pool_pump to your pump’s switch.

A POST with JSON. For a chemical:

{
  "source": "h2oracle",
  "action": "created",
  "event_type": "chemical",
  "event_id": "…",
  "water_body": "pool",
  "water_body_name": "Swimming Pool",
  "gallons": 15000,
  "timestamp": "2026-11-14T15:04:05.000Z",
  "chemical": {
    "name": "Liquid Chlorine 10%",
    "amount": 64,
    "unit": "fl oz",
    "strength_percent": 10
  }
}

• action: created, updated or deleted (and test from Send a test).
• event_type: chemical, reading, session or upkeep.
• water_body: pool or hot_tub.
• chemical: name, amount, unit, and strength_percent when the name has one, purpose.
• reading: sanitizer, ph, free_chlorine (or bromine), combined_chlorine, alkalinity, calcium_hardness, cya, salt, phosphates_ppb, temperature_f, clarity: whichever were tested.
• session: bathers, duration_minutes, activity.
• upkeep: task (water_change, filter_rinse, filter_clean, filter_replace) and, for a water change, percent.

In a Home Assistant template, read them as trigger.json.chemical.amount, trigger.json.session.bathers and so on.

• Away from home? Home Assistant only takes webhooks from your home network while local_only is on. The phone has to be on your Wi-Fi (or VPN).
• Check the address, port included (:8123). If homeassistant.local doesn’t work on your phone, use Home Assistant’s IP address.
• Your own HTTPS certificate? If your server’s certificate comes from your own certificate authority, install that CA on the phone. On Android: Settings › Security › Encryption & credentials › Install a certificate › CA certificate. H2Oracle trusts CAs installed this way.
• Plain http:// works too, on your own network.

If an event can’t be sent, a message says why, and Settings › Webhook shows how the last one went. Events aren’t sent again later.

No. The webhook is set up on each phone separately, and only the phone that logs an event sends it. With household sync, events from another phone don’t trigger yours. Set it up on every phone that should trigger the automation.

In Settings › Household sync, one phone starts a household and becomes its main phone. It invites each of the others with a QR code or link that works once. From then on, every phone has the same history, water setup and treatment plans; reminders and the webhook stay each phone’s own. There are no accounts or passwords. The main phone sees every phone and can remove one; turning sync off on the main phone deletes the household from the server.

No: sync keeps phones in step, it isn’t a backup. Save a backup file from Settings › Back up and restore now and then, and keep it in Drive or Files. It restores everything on a new phone.

Android comes first. An iPhone version is planned.

Not yet: H2Oracle uses gallons and °F for now. Metric units, with a separate Celsius setting, are planned.