OpenBoat Flush

A button at the helm that flushes the engine's raw-water circuit with fresh water, and then writes it into the boat's service log.

Press it when you tie up. A solenoid opens the fresh-water line into the engine's flush port, a timer runs it for as long as your engine's manual says, the valve closes, and the flush is recorded against the engine hours that earned it. No muffs, no hose wrestling, no trying to remember on Tuesday whether you did it on Sunday.

This is a companion to OpenBoat OS. It is a separate repository on purpose: OpenBoat OS never writes to the boat, and this opens a valve. Installing it is a decision you make deliberately, not something that arrives with an update.

---

Read this part before the rest

This device plumbs a pressurised water supply into a circuit that is open to the sea. Done wrong, it can flood your boat while you are not on it, or siphon sea water into your drinking-water tank. That is the actual engineering problem here. The software is the easy half.

Four things carry the safety, and none of them is software:

1. A normally-closed solenoid valve. No power means no flow. A blown fuse, a dead Pi, a flat battery, a crashed process, a cut wire — every one of those failure modes ends with the valve shut. Never use a normally-open or a latching valve for this. This single choice does more than everything else on this list combined.
2. A check valve between the fresh-water supply and the tee into the engine, so nothing can ever flow back toward the tank or the dock connection.
3. A vacuum breaker / anti-siphon loop, mounted above the waterline, so a hose that fails downstream cannot start a siphon out of the sea.
4. A fuse, and a mechanical limit. The software timeout is a convenience. An inline timer relay or a simple spring-return valve is the thing that stops a stuck output from running the dock's water into your bilge overnight.

The controller in this repository refuses to open the valve unless it can confirm the interlocks you configured. That is a useful second line. It is not the first one.

Use your engine's flush port if it has one. Most modern sterndrives and outboards have one, and it is designed for exactly this — correct entry point, correct flow path. If your engine has no flush port, this project has nothing to plumb into and muffs remain the answer. Do not invent a tee into a hose you have not traced end to end.

Whether the engine runs during a flush depends entirely on your engine. Some manufacturers say run at idle; some say engine off; some say off, and never run it dry. This project ships no default and refuses to start until you have set engine_state in the configuration from your own manual. Getting this wrong destroys an impeller in under a minute, and can cook a riser.

---

What it does, precisely

  idle ──button──▶ checking ──all interlocks pass──▶ running ──timer──▶ closing ──▶ idle
                      │                                 │
                      └── any check fails ──▶ refused   └── button again, or any
                                                            interlock drops ──▶ closing

• The valve is open only while the state machine is in running, and running has a hard maximum duration that cannot be extended by anything, including another button press.
• Every state change is written to a journal, with the reason. A refused flush records which check failed.
• The valve closes on: the timer expiring, a second button press, any interlock dropping, the process exiting, a signal, an unhandled exception, and power loss.
• On completion it records a flush in the OpenBoat maintenance log, so python3 -m openboat.maintenance shows the engine no longer owes one.

The interlocks

Each is optional and each is off until you configure it. The controller tells you at startup which ones are armed, because an interlock you think is on and is not is worse than none.

Interlock	What it reads	Why
seacock_closed	a reed switch on the seacock handle	Many flush procedures require the raw-water seacock shut. Without a sensor the controller cannot know, and it will not assume
engine_state	rpm from Signal K	Your manual says running or stopped. No default: the controller refuses to start until you have said which
at_berth	position from Signal K	A flush under way makes no sense and a valve opening under way is a hazard
not_moving	speed over ground	Same, and it works without a berth position configured
shore_water	a pressure switch on the supply	Opening a valve onto no supply just runs a dry pump

Hardware

Part	What to get	Note
Solenoid valve	12 V DC, normally closed, brass or composite, sized to the flush hose	The whole safety case rests on normally-closed
Check valve	inline, on the fresh side of the tee	Non-negotiable
Vacuum breaker	above the waterline	Non-negotiable
Relay	opto-isolated relay module, 3.3 V logic input	A GPIO pin cannot drive a solenoid. It drives the relay, the relay drives the valve
Flyback diode	across the solenoid coil	A coil switching off produces a spike that kills relays and, through them, Pis
Button	momentary, panel-mount, ideally illuminated	The illumination is the state display
Flow sensor	optional, hall-effect inline	Confirms water is actually moving, so a closed supply valve is reported rather than silently doing nothing
Fuse	inline, sized to the solenoid	Ordinary good practice, and the last line

Wiring, GPIO assignment and a diagram are in docs/WIRING.md.

The Pi's own pins are fine for this. Driving an opto-isolated relay is one of the things the GPIO header is genuinely for — unlike reading an engine sender, which it cannot do at all. See OpenBoat OS's hardware notes for that distinction.

Try it with no hardware

python3 -m flush.controller --simulate

Runs the whole state machine against a simulated valve, button and sensors, printing every transition. This is how you check your configuration and your timings before anything is plumbed in. Press enter to simulate the button.

Install

git clone https://github.com/drxlr/openboat-flush
cd openboat-flush
cp flush.example.toml flush.toml
$EDITOR flush.toml          # engine_state has no default; you must set it
python3 -m flush.controller --check     # reports what is armed, opens nothing

Only when --check reports what you expect should you run it for real. It installs as a systemd unit; see docs/INSTALL.md.

What this is not

Not a certified marine system. Not a substitute for reading your engine's manual. Not tested on every engine — it has been built and bench-run by its authors, and that is all. There is no warranty; see LICENSE.

Tell your insurer what you have installed. A home-built device that connects a water supply to a through-hull is a material change to the boat, and the time to discuss it is before it runs unattended, not after.

Apache-2.0.