13 Troubleshooting

Something stopped working — start here. The flowchart below picks the right failure-mode section based on the symptom; each section walks the diagnostic and the fix. The multimeter primer at the top is for novices who haven’t used a meter on this build before; intermediate and advanced readers can skip past it straight to the flowchart.

Diagnostic flowchart

Pick the symptom that matches what you’re seeing; jump to the section below for the full fix.

If your symptom is “the last few tomato pots get less water than the first,” that’s flow balance — page 06’s step 4 covers it.

1. Pump runs but no water flows

Symptom: the pump motor runs (you can hear it humming), but water doesn’t reach the emitters.

Walk the line back from emitter to pump:

1. Reservoir level. Is the bucket above the float-switch trigger height? If not, refill. Then check that the float switch is freely moving — a stuck float (debris on top, algae on the cord) can hold the switch in the wrong state.
2. Pump intake clogged? Cut power, pull the pump out of the bucket, check the strainer for algae or sediment. Rinse the strainer, clear any debris from the impeller cover, and re-seat the pump.
3. Airlock in the tubing. Lift the outlet end of the tubing briefly above the pump body, then lower it. Air bubbles can stall small submersible pumps; the lift breaks the airlock and water resumes flowing.
4. Solenoid valve closed? If the valve isn’t actually opening, you’re at section 2 below — relay clicks but valve doesn’t open. The diagnostics there pick up the trail.
5. 12V at the valve terminals? Multimeter on the two valve leads while the relay is energized. You should read 12V; if zero, the relay’s NO contact isn’t passing power, or the float switch is open upstream.

If the pump itself doesn’t run at all, that’s a different failure — check page 08’s first power-on test for the manual GPIO toggle that proves the relay can drive the pump line.

2. Valve clicks but no water through that zone

Symptom: you hear the valve relay click audibly, but no water flows from that zone.

1. Confirm 12V at the valve terminals. Multimeter on the two valve leads while the relay is energized (Pi running, GPIO LOW for an active-low relay). You should read 12V. If you read zero, the relay’s NO terminal isn’t getting power upstream — check the float switch state and the 12V distribution wiring (page 08 §9c).
2. If 12V is present, the valve itself is the failure. Sometimes a solenoid sticks mechanically — hard-water deposits on the plunger, debris in the seat. Apply 12V directly to the valve’s terminals, bypassing the relay entirely (clip leads from the 12V brick straight to the solenoid leads). If it still doesn’t open, the valve is dead and needs replacement.
3. Float switch is sometimes the culprit. If 12V is missing at the valve but present at the 12V adapter output, the float switch is open and cutting power downstream. Disconnect the float switch, set the meter to continuity, and tilt the float up and down — beep in one position and silent in the other means the switch is fine and currently sitting in its open state (refill the bucket). Never beeping means the switch is dead.

3. Sensor reads garbage

Symptom: the sensor reads exactly 0, stays at the maximum value (around 30000 on the ADS1115’s 16-bit range), or jumps wildly between samples.

For both the dead-reading and erratic-reading flavors:

1. Wiring. Capacitive sensors have three wires: VCC, GND, and AOUT. A broken solder joint kills the AOUT signal — usually back to 0 or floating. Wiggle each wire individually while watching the live reading; if the value swings when you wiggle, that wire’s connection is bad. Re-solder or re-crimp.
2. PCB submerged. The electronic strip at the top of the sensor MUST stay above the soil line — there’s a printed water-line marker on the board. If you pushed the whole sensor in, the electronics are now reading their own immersion plus erratic ground references. Pull, dry, and re-position with the line marker visible above the soil.
3. EMI from 12V cables. Running sensor cables parallel to the 12V pump or valve cables induces noise on the AOUT line — you’ll see this as readings that jump 1000+ counts between samples. Separate the cables: route sensor wiring along a different path (one along the railing, the 12V along the ground, or vice-versa).
4. Replace the sensor. Capacitive sensors are cheap and the 5-pack on page 03 was sized to leave you with spares. If the wiring + position checks all pass and the sensor still reads garbage, swap it in — re-calibrate that zone afterward (page 11).
5. Bump SENSOR_SAMPLES. In irrigate.py, raise SENSOR_SAMPLES = 10 to 20. More samples per reading means more averaging and lower noise; the cost is a slightly slower sensor pass during the cron tick.

4. One zone always waters even when soil is moist

Symptom: that zone fires its watering cycle every scheduled run even right after rain — soil is visibly damp, no obvious drought stress on the plants.

1. dry_threshold is set too low. Re-calibrate using page 11’s threshold calculator. The default dry_threshold baked into your initial config (e.g., 18000 for lettuce) was calibrated against Gus’s specific potting mix; your mix probably reads differently. Pull your meter, measure dry and wet on the actual zone, and let the calculator give you the new number.
2. Sensor sits in a dry pocket. The sensor measures one specific point in the pot. If you pushed it in at the edge — where soil dries first because of evaporation off the pot wall — the reading isn’t representative of where the roots actually live. Move it closer to the center, near an emitter dripper, where the irrigation actually wets the soil.
3. Sensor calibration drift. Re-run page 11’s calibration every 2-3 months. Sensors age, soil settles, and the dry/wet endpoints shift over a season. A short re-calibration in spring and again mid-summer keeps the threshold honest.

5. Wrong zone fires when you trigger another

Symptom: you triggered the lettuce zone manually, but the tomato zone got watered instead.

1. Valve wires swapped at the relay. Walk the wires from each relay channel’s NO output (CH2, CH3, CH4) back to the corresponding solenoid valve. The pin map on page 08 is the source of truth: GPIO 27 = CH2 = valve 1 (lettuce); GPIO 22 = CH3 = valve 2 (tomatoes); GPIO 23 = CH4 = valve 3 (raised bed). If the physical wiring doesn’t match, swap the leads at the relay’s NO terminals to match the map.
2. ZONES dict misconfigured. In irrigate.py, each zone’s valve_pin field has to match the physical wiring. If you re-wired the relay outputs without updating the dict, the script trusts its config and fires the wrong GPIO — you fix the dict to match reality. (The other direction — fix the wiring instead of the dict — also works; pick whichever is easier to access.)

6. Pi unreachable / WiFi flake / power outage

Symptom: SSH hangs (“host not found” or it just times out); or the system was off after a power outage and now needs to recover.

For SSH unreachability:

1. Router DHCP page. Most consumer routers have a “connected devices” or “DHCP leases” page. Look for the Pi’s hostname (irrigator) and its current IP address. SSH to the IP directly if irrigator.local is flaky.
2. mDNS not resolving. On macOS, dns-sd -B _ssh._tcp lists every mDNS-advertised SSH server on your LAN. On Linux, avahi-browse -a does the same. Useful when .local lookups silently fail (some routers and DNS configs eat mDNS).
3. Persistent solution: static IP. Configure your router to reserve a specific IP for the Pi’s MAC address. SSH-by-IP becomes reliable and survives router reboots, and you can then put a hostname alias in your local ~/.ssh/config.
4. Pi truly unreachable: connect a monitor and keyboard. Even Pi OS Lite supports a direct console session — boot, log in, and fix wpa_supplicant.conf if WiFi is gone. As a last resort, pull the SD card and edit the file on another machine.

For power outage recovery:

The system self-recovers — no manual intervention needed. The Pi boots automatically when power returns, cron picks up at the next 7am or 6pm slot, and all relays default to OPEN on boot (pump off, valves closed) until cron triggers them. Critically, the solenoid valves are normally-closed: with no power they hold shut, so no water flows during the outage even if the bucket is full. Once power and cron resume, the system carries on with the next scheduled cycle.

Where to get more help

If the flowchart and these six sections don’t cover your symptom: search the Raspberry Pi forums first — both r/raspberry_pi on Reddit and the official forums at raspberrypi.org/forums catch most odd Pi behaviors. For garden-specific or plant-care questions that aren’t really about the hardware, the Garden Stack Exchange (gardening.stackexchange.com) is the right room. The solenoid project archive’s 05-troubleshooting-log.md file goes deeper on the multimeter five-point checklist (Issue 1) and the float-switch continuity test (Issue 3) if you want more background.

Congratulations

The system runs. It waters your plants twice a day, calibrates to your soil, and falls back safely on float-switch hardware when the bucket runs dry. If something breaks in three months, this page is your reference; if it runs for years without breaking, that’s the goal. The planner is open if you want to extend — more zones, a winter greenhouse build, a second balcony — and each addition reuses the same hardware patterns you just wired.

Bookmark this page; you’ll likely come back.