A cheap soil probe publishes a number between 0 and 100 that is not a percentage of anything. This turns it into water content you can act on, and says nothing until it can.
The 0 to 100 index is the oscillator output rescaled between two factory endpoints, usually air and water. Neither endpoint is your soil, so 40 does not mean forty percent of anything.
Bulk density, texture and organic content all shift the reading for the same water content. A number that is right in sand is wrong in clay, and no factory calibration knows which you have.
An air gap along the electrode, a stone, or a probe above the root zone changes the answer more than soil type, temperature and salinity put together.
What the index is, honestly stated: a monotone, short-term-stable, site-specific ordinal signal. That is exactly enough to calibrate, and nowhere near enough to read as a percentage.
This is the part most worth reading before installing, so it is not at the bottom of the page.
unknown. A provisional value improved over time was considered and rejected: downstream there is an irrigation controller that cannot tell a provisional number from a settled one.Not the sample. One irrigation to one dry-down is one experiment, with a wet anchor at field capacity after drainage and a dry anchor at the deepest depletion reached. Five complete cycles by default.
Theil-Sen over the pairwise slopes, with an optional thermal term. A single bad afternoon moves a least-squares fit; it does not move a median of slopes.
Readings during irrigation, inside the drainage window, while it rains, on frozen soil or from a stale deficit never become samples. Every refusal is named and counted, so a probe that never calibrates can say why.
Enough cycles, enough samples, a real span of the probe's range, a monotone relation and a bounded residual. Miss one and nothing is published.
Recent disagreement between the published line and the reference is reported as drift, which is the early warning that a probe is ageing. Turning a calibration knob on the device invalidates the history, because after that the index means something else.
A probe with a flat battery keeps publishing its last reading for ever. Silence is judged against the probe's own observed cadence rather than a fixed timeout, and a reading that stands still while the soil demonstrably dries is caught as a stopped sensing element, not mistaken for bad placement.
A cheap capacitive soil probe already in Home Assistant, publishing an index between 0 and 100. Most Zigbee and ESPHome soil sensors qualify. Its temperature channel, battery and device-side calibration knobs are discovered on their own.
A water deficit sensor in millimetres or inches. This is the reference the probe is taught against. Any water balance model will do; NeverDry produces one.
A soil description. Texture from a dropdown and root depth, or your own field capacity and wilting point if you have measured them.
Patience. Five complete irrigation cycles is roughly three weeks on a garden bed. There is no way to shorten that which is not a lie about the evidence.
1. In HACS, open the three dot menu and choose Custom repositories.
2. Paste https://github.com/never-dry/NeverDryCalibrator with category Integration.
3. Download it from the card that appears, then restart Home Assistant.
4. Add the integration, then add one probe per pair of probe and deficit sensor.
This is the thing the project actually needs, and it is worth more than a star.
The error budget is argued from physics and the thresholds are argued from how each failure looks. Turning any of that from argued into measured takes probes in real ground, in soils that are not the author's, reported by the people who own them. If you have a cheap probe and a water balance, run it for a few cycles and say what came out: which soil, which probe, whether it reached calibrated, what the placement diagnostic said, and whether the published number matched anything you could check independently.
A negative result is as useful as a positive one. A probe that never calibrates and names the reason it kept refusing is a bug report about the thresholds, which is precisely what is missing.
Something broken rather than unclear? Open an issue. The diagnostics download carries the samples, the cycles and every refusal, which is usually the whole answer.
NeverDry Calibrator is free and open source - the other way to support it is to star it and spread the word:
Know someone running a cheap soil sensor they do not quite trust? Spread the word:
NeverDry decides when and how long to water, from a FAO-56 water balance, and makes sure the valve always closes. It produces the deficit this project needs.
NeverDry Calibrator goes the other way: it takes that deficit as a reference and teaches a cheap probe what its own numbers mean, so the measurement in the ground and the model on the wall finally speak the same units.
Either works on its own. Together the model gets a witness and the probe gets a scale.
NeverDry Calibrator is a hobby project for residential use. It is not certified for agricultural, commercial, or safety-critical applications. The declared error budget is argued from soil physics and has not yet been verified against probes in the ground with an independent control. Do not use the published figure where being wrong is expensive. The authors accept no liability for any damage or loss.
Developed by drake69 with AI assistance (Claude by Anthropic).
The reasoning behind every threshold, the alternatives rejected and what remains wrong are written out in the repository: the calibration method and how a dead probe is detected.