📘 Guide JoyReef
← Indice 📄 Scarica PDF

Configure Automatic Top-Off (ATO)

Reading time: ~15 minutes · Execution time: ~20 minutes · Audience: anyone who completed guide 05 and has at least one smart plug and one level sensor already configured

🟡 Important Guide — a feature that almost everyone will want to activate. Without it, the system works but is much less effective.

🗺️ Your JoyReef Path:

  1. Shopping list
  2. Controller assembly
  3. Firmware + WiFi
  4. Tank and sensor configuration
  5. Tasmota smart plugs
  6. Automatic Top-Off (ATO) ← YOU ARE HERE
  7. Temperature
  8. Water change
  9. Advanced automations

1. What you are about to do

ATO (Automatic Top-Off) is the first — and probably most useful — of the JoyReef automations. It serves to replace the fresh water that evaporates from your marine tank, maintaining constant salinity and level.

In a reef tank, fresh water evaporates continuously (leaving the salt behind). Without an ATO, you have to top off by hand, almost every day: forgetting for a week means crazy salinity, exposed heaters, and skimmers out of tune.

With the ATO configured, the portal keeps an eye on the water level through a float switch in the sump. When the level drops below the threshold, it turns on a top-off pump (connected to a Tasmota smart plug) for a few seconds, which pumps RODI water from a reservoir. When the level returns, it turns it off. All automatic, 24/7.

In this guide, you will configure:

2. What you need

Before starting, you must have already configured:

💡 Recommended (not mandatory): dual sensors. ATO with only one level sensor (the "minimum") works, but has no mechanical safety net: if the minimum sensor gets stuck (hair, biofilm, crystallized salt), the pump starts and never stops until it hits the max daily limit or the dosing timeout. With a second "maximum" sensor positioned 1-2 cm above the minimum, the system can stop the pump even if the main sensor fails.

💡 Have more than one level sensor? You can have ATO + water change + skimmer full + osmosis reservoir all monitored. In this guide, you configure only the ATO; other automations have dedicated guides (08 for water change, others coming soon).

3. How Automatic Top-Off works

Before touching the configuration page, take two minutes to understand the logic: it will help you avoid setting random values or getting scared by the first "lockout" you see.

The basic principle

The system is a very simple loop that runs on the physical controller (not on the portal: this is important, it works even if internet goes down):

every N seconds:
    if the minimum sensor says "low water" for at least X seconds:
        turn on the pump
        wait for the sensor to say "water ok" again
        turn off the pump
        wait Y seconds before checking again (lockout)

The parameters (X, Y, and several others) are configured on the page. Let's look at them all, as each has a specific safety purpose.

The 3 levels of safety

ATO is the "riskiest" system of all automation: if it goes wrong, you empty your osmosis reservoir into the tank (= salinity shock → corals die). For this reason, there are three overlapping safety filters:

1. Limit per single dosing (max_dose) Maximum time the pump can stay on in a single cycle. If it exceeds this, the system goes into "fault" and stops until you unlock it manually. Typical: 60-180 seconds. Purpose: block the pump if the minimum sensor is stuck "low" and never returns to "ok."

2. Daily limit (max_daily) Total time the pump can work in 24 hours. If exceeded, fault. Typical: 600-1800 seconds (10-30 total minutes). Purpose: block the system if there is a small continuous leak (e.g., sump tap dripping): the pump would top off for hours without realizing it.

3. Lockout between cycles (lockout) Minimum pause between one stop and the next start. Even if the sensor immediately says "I still have low water," the system waits. Typical: 30-120 seconds. Purpose: give the newly pumped water time to stabilize in the sump (waves from the return pump cause the float switch to oscillate).

What happens in case of a fault

If one of the limits is triggered, you will see on the portal (and on the controller) the status "LOCKED FOR SAFETY" with the reason for the fault:

In all these cases, the pump remains off and you must click "Unlock now" after understanding why. Do not unlock blindly: if you unlock without resolving the cause, the fault will return within seconds, and in the meantime, you might have pumped more liters into the tank.

4. Step 1 — Open the ATO page

From the JoyReef portal:

  1. Open portal.joy-reef.com and log in
  2. In the left menu, click on the "ATO" item (water pump icon 💧)
  3. Or go directly to portal.joy-reef.com/ato

The "ATO" page opens with various boxes. If an orange banner appears at the top saying "Tank not selected" → go back to guide 04 and set a tank as primary, then return here.

If an orange banner appears saying "No level sensor assigned" → go back to guide 04 sensor section and assign at least one sensor to the role ATO operating level (or equivalent). ATO cannot function without it.

📷 PLACEHOLDER-ATO-PAGE-EMPTY

🖼️ Image to insert here (Empty ATO page): screenshot of the ATO page on first access, with the "ATO active" toggle off and empty fields.

5. Step 2 — Configure level sensors

In the first card "Levels," you find 4 fields:

Minimum level sensor (mandatory)

The float switch that detects when water has dropped enough to start the top-off. Typically positioned in the sump, where the level drops first (because evaporation "discharges" the sump surface).

In the "Minimum level sensor" menu, select the level sensor you assigned as ATO operating level (or Sump - Minimum level if you chose that role). You'll recognize it by the controller name next to it (e.g., "ATO operating level · Main Controller").

Minimum condition

Float switches can behave in two ways depending on the model:

In practice: try manually raising and lowering the float with the tank full, see what changes in the "Sensors" section of the portal, and choose the condition that corresponds to "low water."

💡 In doubt? Leave it as "Low" and test: if the pump starts when it shouldn't (tank full), come back here and change it to "High."

This is the safety net: a second float switch positioned 1-2 cm above the minimum. Its only function is to say "STOP" if water reaches it — meaning the minimum didn't work and we are already beyond the operating level.

In the "Maximum level sensor" menu, select the sensor you assigned as Sump - Maximum level (or ATO operating level if you have a single dual float with two contacts).

If you don't have a second float switch, leave it as "None": the ATO will still work, but you'll only be protected by the time/quantity limits (see section 7).

Maximum condition

Same logic as the minimum: choose the condition that corresponds to "water too high." Typically "High": the sensor signals "HIGH" when the water lifts it.

📷 PLACEHOLDER-ATO-LEVELS

🖼️ Image to insert here (Filled Levels card): screenshot of the "Levels" card with minimum sensor selected (e.g., "ATO operating level · Main Controller"), "Low" condition, maximum sensor selected, and "High" condition.

6. Step 3 — Choose the top-off pump

In the second card "Actuator":

ATO Pump

In the "ATO Pump" menu, select the smart plug to which you connected the top-off pump. The menu shows all smart plugs assigned to your tank (= those you configured in guide 05).

If the menu is empty or you don't see the right plug:

Start state / Stop state

These two menus tell the system what the "on state" of your pump is relative to the smart plug. In 99% of cases:

That is: to turn on the pump, we send ON to the plug; to turn it off, OFF. Leave the defaults unless you have a strange configuration (e.g., pump driven by an inverted relay).

📷 PLACEHOLDER-ATO-ACTUATOR

🖼️ Image to insert here (Filled Actuator card): screenshot of the "Actuator" card with the "Top-off Pump" smart plug selected and default ON/OFF states.

7. Step 4 — Set safety limits

In the third card "Limits," you find 5 numerical fields. All in seconds.

Recommended values for a typical sump (~50 liter sump for a 200L net tank) with a standard AC top-off pump (5-10 W, ~80 L/h):

Field Recommended Value Purpose
Max dose duration 120 (= 2 min) The pump draws ~2.5L in 2 minutes, enough to top off 1-2 cm of evaporation in the sump. If the level doesn't return in 2 minutes, there's a problem
Max daily duration 1200 (= 20 min) Total 20 min/day = ~25L of RODI water per day, well above typical evaporation. If you exceed this, there's a leak
Lockout 60 (= 1 min) After each stop, wait 1 min before it can restart: newly pumped water stabilizes in the sump
Activation delay 5 The minimum sensor must say "low" for at least 5 consecutive seconds before starting the pump. Filters false positives from wave oscillations
Stop delay 2 The maximum sensor must say "high" for 2 consecutive seconds before stopping the pump (anti-oscillation)

How to calibrate for your specific tank

If your tank is much smaller/larger, or the pump much more/less powerful, recalibrate:

⚠️ DO NOT set max_dose = 0 or max_daily = 0: zero means "no limit," and you remove your protections. Even if you are sure of your configuration, always leave sensible values: they will save your aquarium the day a sensor fails.

📷 PLACEHOLDER-ATO-LIMITS

🖼️ Image to insert here (Filled Limits card): screenshot of the "Limits" card with recommended values (120, 1200, 60, 5, 2).

8. Step 5 — Activate ATO and save

You have filled out all three cards. Now:

Step 1: activate the toggle

In the top right of the "Configuration" section, you'll find the "ATO active" toggle. Click it to activate (it becomes green).

Step 2: save

At the top of the page, next to the "Automatic ATO" title, is the "Save settings" button. Click it.

A green confirmation banner appears below: "ATO settings saved and sent to controllers."

In a few seconds, the controller receives the new configuration and starts monitoring the sensor. From this moment, the system is operational 24/7.

📷 PLACEHOLDER-ATO-SAVED

🖼️ Image to insert here (ATO saved): screenshot of the ATO page immediately after saving, with the green "Active" toggle at the top, the real-time monitor visible, and the green confirmation banner.

Step 3: verify the real-time monitor

Immediately after saving, a new section "Real-time status" appears with 4-5 boxes:

If you see a large green dot next to "DOSING IN PROGRESS" or blue next to "WAITING (Standby)," the system is working. ✅

If you see a red dot with "FAULT: ..." on first start, go to the "If something goes wrong" section further down.

9. Step 6 (optional) — Create advanced automations

Under the "Operational notes" card, you'll find an "Advanced automations" section with a "Create automations" button.

What it does: generates a series of ready-to-use routines (visible in the Automations page) that handle:

Do you have to do it? No, it's optional. The ATO pump works perfectly without them. Create the automations only if you want the extra behaviors above.

For now, you can skip this step and create them in the future when you are more familiar. You will always find them here.

💡 The created automations are editable. Once you click "Create automations," you can find the routines on the Automations page and adapt them as you like (change email recipients, thresholds, etc.). They are not "carved in stone."

10. Verify that it really works

Settings are saved, the monitor says "Operational." But does it really work? Let's do an active test.

Test 1: manual sensor simulation

  1. Temporarily remove the minimum float switch from its bracket in the sump (carefully, without turning anything off)
  2. Hold it up (= dry sensor = "low" state = ATO trigger)
  3. Wait 5-10 seconds (the "activation delay" + controller cycle time)

  4. You should hear the pump start, and in the portal monitor see "DOSING IN PROGRESS" + green dot

  5. Lower the float switch back to the operating position

  6. The pump stops after 1-2 seconds (the "stop delay")
  7. In the monitor you see "WAITING (Standby)" and total seconds in the "Today used" box

If this test works, the ATO is operational. ✅

Test 2 (if you have the maximum sensor): failsafe test

  1. Remove the minimum float switch and hold it up (the pump starts)
  2. Immediately after, also remove the maximum one and hold it up (= simulates "water too high")
  3. The pump stops immediately, and the system goes into "FAULT: MAX LEVEL"

  4. In the monitor, the orange banner "Top-off is locked for safety" appears with the "Unlock now" button

  5. Lower both float switches back to operating positions

  6. Click "Unlock now"
  7. The system returns to "WAITING." ✅

You have just verified that the safety net really works. It's worth ten minutes of your time.

⚠️ After the test, recheck that the float switches are in the correct operating position and that the system sees the water. If you have doubts, follow the sensor in real-time from the Sensors page for a few minutes.

11. If something goes wrong

The pump starts immediately and doesn't stop (with full sensor)

The minimum condition is inverted: the system thinks "high" is "low" or vice versa.

Go back to the ATO page "Levels" section and change "Minimum condition" (if it was "Low," set it to "High" and vice versa). Save. Try again.

It never starts, even when moving the float switch

Possible causes, in order of probability:

  1. ATO is not active → check the "ATO active" toggle above the configuration (must be green)
  2. The sensor is not sending data to the controller → go to Sensors, see if the float switch value changes when you move it by hand. If it doesn't, it's a wiring problem (see guide 04)
  3. You are looking at the wrong sensor → check in the "Levels" card which sensor you selected as minimum
  4. The controller is offline → look at the status dot in the "Real-time status" section. If red → controller offline, go to Devices

"FAULT: DOSING TIMEOUT" on first activation

max_dose set too low, or the pump can't recover the level in that time.

Diagnosis:

"FAULT: MAX LEVEL" immediately

The upper safety sensor sees "high water" from the start. Possible causes:

"FAULT: SENSOR ABSENT"

The controller doesn't receive data from the minimum sensor for more than a few minutes.

"FAULT: DAILY LIMIT"

In 24 hours, the pump has worked more than allowed. Almost always means a leak or minimum sensor stuck "low".

Real-time monitor says "Controller offline"

Go to guide 04, controller troubleshooting. ATO cannot function if the controller doesn't talk to the portal (worse: it will continue to run locally on the controller, but you won't see states and won't be able to unlock faults).

12. Next step

Do you have the ATO operational and tested? Perfect. Your tank now tops itself off.

The next natural automations to tackle are:

➡️ Guide 07 — Temperature control (heater + fan, hysteresis, alerts)

➡️ Guide 08 — Automatic water change (drain pump + fill pump, weekly scheduling)

Both follow the same conceptual logic as the ATO: sensor → threshold → actuator → safety. Once you understand ATO, the others are faster.

💡 Let the ATO run for a few days before moving on to something else. Verify in the event timeline (Events menu) that it starts every 6-12 hours with short doses (30-60 sec). If you see continuous doses or strange cycles, return to the configuration and recalibrate before adding other automations.