Water Chemistry¶

Pool Manager monitors up to eight water chemistry parameters. Each parameter has a defined acceptable range and an ideal target value used for scoring and dosage calculations.

Parameter Ranges¶

Values within the minimum--maximum range are considered acceptable. The target value represents the ideal level for each parameter.

Chemistry Status¶

Each parameter is evaluated individually and assigned one of three statuses: good, warning, or bad. These are exposed as enum sensors for use in dashboards and automations.

How the status is determined¶

The status is derived from the parameter's individual quality score (the same score used in the water quality score calculation):

When a parameter's status changes between updates, a poolman_event is fired on the Home Assistant event bus so you can trigger automations. See Events for the full event schema.

Water Quality Score¶

The water quality score is a 0--100% value displayed by the sensor.{pool}_water_quality_score entity. It provides a single-number summary of your pool's overall water chemistry health.

How it is calculated¶

Each available parameter is scored individually against its acceptable range:

• A reading at the target value scores 100
• A reading at the minimum or maximum boundary scores 0
• Values between the boundary and the target are scored linearly
• Values outside the acceptable range score 0

The overall water quality score is the average of all individual parameter scores.

Which parameters are included¶

Only parameters for which a sensor is configured and currently reporting a valid value are included in the score. If you only have pH and ORP sensors, the score is computed from those two. Adding free chlorine, salt, TAC, CYA, or hardness sensors increases the accuracy of the score.

If no parameter has a valid reading, the score is unavailable.

Chemical Products¶

Pool Manager recommends chemical products based on your configured treatment type. The sanitizer-related products adapt to your treatment method, while pH and TAC products are universal.

Universal products¶

Sanitizer products by treatment type¶

pH Dosage Calculation¶

When pH deviates from the target (7.2) by more than the tolerance (0.1), Pool Manager calculates the required dosage:

Where:

• 150 g per 10 m³ is the base dosage for a 0.2 pH change
• The product is pH- if pH is above target, pH+ if below

TAC Dosage Calculation¶

When TAC falls below the minimum (80 ppm), the integration calculates the sodium bicarbonate dosage needed to reach the target (120 ppm):

Where 18 g of sodium bicarbonate per m³ raises TAC by 10 ppm.

When TAC is above the maximum (150 ppm), pH- treatments are recommended as they indirectly lower alkalinity.

CYA Dosage Calculation¶

When CYA (cyanuric acid / stabilizer) falls below the minimum (20 ppm), the integration calculates the stabilizer dosage needed to reach the target (40 ppm):

Where 1 g of cyanuric acid per m³ raises CYA by 1 ppm.

When CYA is above the maximum (75 ppm), no chemical product can lower it. The integration recommends a partial water drain instead.

Hardness Dosage Calculation¶

When calcium hardness falls below the minimum (150 ppm), the integration calculates the calcium chloride dosage needed to reach the target (250 ppm):

Where 1.5 g of CaCl₂ per m³ raises hardness by 1 ppm.

When hardness is above the maximum (400 ppm), no chemical product can lower it. The integration recommends a partial water drain instead.

Free Chlorine¶

Free chlorine measures the amount of active, available chlorine in the water. Unlike ORP (which provides an indirect measure of sanitizer effectiveness), free chlorine is a direct measurement that supplements the ORP-based sanitizer evaluation.

When free chlorine is out of range, Pool Manager recommends the appropriate product but does not calculate a specific dosage, because the required amount depends on many factors (CYA level, UV exposure, bather load, etc.):

Electrical Conductivity (EC)¶

Electrical conductivity (EC) measures the water's ability to conduct an electrical current, which correlates with total dissolved solids (TDS). It is a useful diagnostic indicator for tracking mineral buildup, salt levels, or general water freshness over time.

EC is exposed as a read-only sensor with no status, no scoring, and no rules. There is no universal ideal range because acceptable EC values vary widely depending on treatment type (salt electrolysis pools run at 3000--6000 µS/cm, while chlorine-treated pools are typically 500--1500 µS/cm), water source, and local conditions.

Use the sensor.{pool}_ec entity for trending and diagnostics in your dashboards.

Total Dissolved Solids (TDS)¶

Total Dissolved Solids (TDS) estimates the concentration of all dissolved minerals, salts, and organic matter in the pool water. High TDS reduces sanitizer effectiveness, can cause cloudy water, and may lead to scaling on pool surfaces and equipment.

TDS is computed from EC (Electrical Conductivity) using a configurable conversion factor:

The default factor is 0.5, which is standard for freshwater pools. You can adjust it during setup or in the options flow (typical range: 0.4--0.8) to match your water composition.

When TDS is out of range, Pool Manager recommends the appropriate action:

Manual TDS measurement¶

You can record a manual TDS measurement using the poolman.record_measure service with the tds parameter. Manual measurements override the computed value until the next sensor update.

Salt¶

Salt level monitoring is relevant for pools using salt electrolysis treatment. The salt sensor tracks the concentration of dissolved salt in the water, which is critical for the electrolysis cell to function properly.

When salt level is out of range, Pool Manager recommends the appropriate action:

Salt Dosage Calculation¶

When salt falls below the minimum (2700 ppm), the integration calculates the salt dosage needed to reach the target (3200 ppm):

Where 3 kg of salt per m³ raises salt level by 1000 ppm.

Spoon Equivalents¶

When measuring spoon sizes are configured, dosage recommendations include an approximate number of spoons alongside the gram-based quantity. This makes it easier to measure products in practice without a scale.

How it works¶

Each chemical product has an approximate bulk density (g/mL) that is used to convert grams to milliliters. The volume is then divided by the spoon size to determine the number of spoons.

When multiple spoon sizes are configured, the integration selects the one that minimizes rounding error when rounded to a whole number of spoons (the best-fit strategy).

Product density table¶

Tablet products¶

Tablet products (chlorine tablets, bromine tablets, active oxygen tablets) are excluded from spoon equivalents because they are not measured with spoons.

Recommendation display¶

When spoon equivalents are available, the recommendation message format is:

Add 300g of ph_minus (300g of ph_minus, 18 Large spoons)

The spoon_count and spoon_name values are also available as sensor attributes for use in dashboards and automations.

Service input¶

The poolman.add_treatment service accepts spoon-based input as an alternative to grams:

When spoons and spoon_name are provided (and quantity_g is omitted), the service converts the spoon count to grams using the product's density and the named spoon's volume.