Ezo pmp controller

Electrical and PCB prototype v0.3

This directory contains the native KiCad schematic and routed four-layer PCB for the four-channel Atlas Scientific EZO-PMP controller. It implements the power input, logic rails, Feather carrier, per-pump I2C isolation, and four unswitched pump supply taps inside the frozen 195 x 58 mm mechanical envelope.

Open ezo-pmp-controller.kicad_pro in KiCad. The project manager shows both editors: Schematic Editor opens the hierarchical circuit and PCB Editor opens the placed and routed board in ezo-pmp-controller.kicad_pcb. In PCB Editor, press Home to fit the board, B to refill copper zones, and Alt+3 for the 3D Viewer. A board-only STEP is also checked in under exports/pcb; component models shown by KiCad depend on the optional KiCad 3D package libraries installed on the workstation.

The root schematic links these functional sheets:

PCB layout

• 195 x 58 mm rounded four-layer board; 1.6 mm FR-4 is the intended stack.
• Four 3.4 mm non-plated M3 mounting holes on the frozen 185 x 48 mm pattern.
• Feather/TFT at the left with its antenna and USB end at the board edge.
• Four repeated pump control headers and supply terminals along the service edge, ordered pump 1 through pump 4.
• 12 V input, fuse, protection, and regulators grouped on the right; the mux and its reset barrier sit between the Feather and power.
• Ground planes on In1 and the back, protected-12 V and 5 V planes on In2, and 1.0 mm input, 0.50 mm logic power, and 0.20 mm minimum signal routing.
• 84 footprints, including 57 top-side JLCPCB SMT placements and the hand-soldered connectors, jumper, and Feather socket/module parts.

The placement drawing is exports/pcb/ezo-pmp-controller-assembly.png, and the copper/silkscreen overview is exports/pcb/ezo-pmp-controller-top.png. These files make the physical arrangement reviewable without KiCad, but the .kicad_pcb file remains the editable source of truth.

The Feather pad map was checked against Adafruit's PID 5483 PrettyPins drawing, including its two 3.3 V header pins, bottom TXD0 debug pad, and reverse-numbered right header row. The onboard TFT shares the Feather's SCK/GPIO36 and MOSI/GPIO35 header pins, so both are intentionally left unconnected on this carrier.

Pump connections

Each pump uses two separate connectors on this controller:

Every pump ships in UART mode and must be switched to I2C once before installation; see commissioning.md. The switch sets the factory address 0x67, which is what the mux design expects, so all four pumps stay identical and a replacement needs no address assignment.

The INT pin is wired only to its ESD clamp; it does not reach the MCU. Atlas asserts INT while a pump is dispensing, and dispensing state is polled over I2C instead, so the pin exists to keep the five-wire cable mating correctly. Atlas's own hydroponics kit lands the pump on a four-wire I2C terminal for the same reason.

The control footprint is a horizontal 1-by-5 2.54 mm header selected to mate with the Atlas cable's Molex 2695 controller-end housing. The prototype gate is to test the real cable on the selected C138801 header and confirm pitch, friction-lock engagement, pin-1 orientation, and service clearance before PCB release. The board silkscreen must include both pin numbers and wire colors.

Safety behavior

Dosing is stopped in firmware, not in hardware. Each EZO-PMP contains its own motor controller and dispenses by volume: the carrier tells a pump to move a number of millilitres and the pump decides when to stop. Earlier revisions put a quad high-side switch, a watchdog, and an arm gate between the supply and the pumps so the carrier could cut a pump off mid-dose. That was removed in v0.3. These pumps are normally deployed straight off a wall brick with no such hardware anywhere in the path, so the failure it guarded against -- a pump that will not stop -- is one the pump's own firmware has to handle. Adding a cutoff here would have protected this one carrier and nothing else.

What remains:

• The 12 V input is fused, reverse-polarity protected by a P-channel pass FET, and clamped by a 13 V TVS. Supply the board from 12 V only; at 24 V the TVS conducts continuously rather than protecting anything.
• The TCA9548A reset is pulled up only by the EZO rail and asserted through an open-drain MOSFET, so a USB-powered Feather GPIO can never drive the unpowered pump-logic rail. The gate is pulled down, so the mux releases itself at power-on and needs no firmware co-operation to be reachable.
• The I2C trunk pull-ups reference EZO_3V3, not the Feather rail, so the bus is only driven when both domains are up.
• The Feather VBUS header and its USB-C connector are the same net inside the module. Remove the Feather from its socket to flash it. D4 makes an attached host harmless rather than merely forbidden: the host's 5.0 V exceeds the 4.6 V the carrier offers, so the diode turns off and USB powers the Feather alone.

None of this is an emergency-stop-rated safety system, and there is no hardware path that can interrupt a dose in progress. Wet energized use remains prohibited until the mechanical and powered electrical gates pass.

Regenerate and validate

The checked-in KiCad files and BOMs are generated from the explicit component and connectivity model in tools/generate_kicad.py. Dependencies are declared in the repository's pyproject.toml and managed with uv:

uv venv --system-site-packages
uv sync --inexact

--system-site-packages is required because the PCB scripts import KiCad's pcbnew, which ships with KiCad rather than from PyPI; --inexact stops uv from removing packages it did not install itself.

Routing needs Freerouting on PATH. nix profile install nixpkgs#freerouting pins 2.2.4 and brings its own JRE; route_pcb.py passes --gui.enabled=false and clears DISPLAY, so it routes and exits without opening a window.

Then, using .venv/bin/python:

python3 electrical/tools/generate_kicad.py
python3 electrical/tools/validate_kicad.py
python3 electrical/tools/create_pcb.py --force
python3 electrical/tools/route_pcb.py
python3 electrical/tools/finalize_pcb.py electrical/ezo-pmp-controller.kicad_pcb
python3 electrical/tools/validate_pcb.py
python3 electrical/tools/generate_fabrication.py

route_pcb.py exports the Specctra DSN, checks its net-class membership, runs Freerouting, and imports the session back onto the board. It prints whatever the router could not finish, though that list overstates the problem — the router does not credit the locked escape copper it is handed, and the planes do not exist yet. validate_pcb.py is the gate that decides whether the board is fabricable.

Everything through routing is byte-reproducible: two rebuilds give identical bootstrap boards, identical Specctra exports and an identical routing session. That relies on tools/canonical_board.py, which every script that writes the board calls. pcbnew assigns random UUIDs to the items it creates and KiCad orders and writes items by UUID, so without canonicalising, each rebuild emitted the same geometry in a different order and the autorouter followed it to a different result.

The final zone fill is the one step that is not bit-identical. KiCad's filler is multithreaded and lands a point or two differently between runs, so the copper is electrically the same while the file churns slightly. Everything that decides the design is stable; only the computed fill polygons move. The session is checked in under routing/, so when the netlist has not changed route_pcb.py --reuse-session skips the router and reproduces identical copper. Re-run without that flag whenever the netlist changes — a session routed against a stale netlist will attach copper to the wrong pads.

The generator also owns the schematic presentation, split across four modules:

Component symbols come from KiCad's own libraries, so a capacitor looks like a capacitor and a diode shows its polarity. Rails and grounds are power ports. Series elements are drawn horizontally and shunt elements vertically, which is what tells a reader at a glance who is in the signal path and who is parallel. Visible wires show connections inside a functional block; named local/global ports are reserved for connections that would otherwise cross blocks or sheets.

See tools/layouts/README.md for the layout API. Edit those layout definitions rather than moving generated symbols by hand in KiCad; regeneration intentionally replaces the child sheets. To iterate on one sheet, python3 electrical/tools/preview_sheet.py <sheet_name> renders it on its own and reports any netlist mismatch.

Test points are PCB features and therefore do not carry KiCad's red DNP cross; crosses that remain mark intentionally unpopulated options.

Connectivity rides on drawn wires, so a placement mistake is a wiring mistake. The generator checks the drawn geometry against the model before writing each sheet — nets that split, nets shorted together, and nets left unnamed all fail the build — and validate_kicad.py re-derives the whole netlist through kicad-cli afterwards.

The schematic validator invokes KiCad's own parser/exporter, resolves every footprint and pad, compares every exported pin/net pair with the source model, and checks both BOMs. It also runs kicad-cli sch erc, which KiCad 10 provides, so ERC is part of the automated gate rather than a manual step.

The PCB validator checks the 195 x 58 mm outline, four-layer stack, mounting pattern, footprints, power copper, routes, JLCPCB placements, and KiCad DRC. It fails on any DRC error or unconnected pad. The complete board-rebuild sequence intentionally overwrites hand edits; capture deliberate layout changes in the PCB scripts before using it.

The validator discovers standard footprints from KiCad's footprint environment variables and the kicad-cli installation prefix. For a custom installation, override the location explicitly:

DOSING_PUMP_KICAD_FOOTPRINT_DIR=/path/to/kicad/footprints \
  python3 electrical/tools/validate_kicad.py

The generated sourcing files are:

• bom/full-bom.csv: all parts, hand-solder items, test points, and DNP options.
• bom/jlcpcb-smt-bom.csv: populated SMT parts only, grouped by value, footprint, and LCSC/JLCPCB part number.
• bom/sourcing-status.md: availability snapshot and purchasing caveats.

The generated JLCPCB package is under fabrication/jlcpcb: Gerber ZIP, separate PTH/NPTH drills, grouped BOM, and a 57-row top-side CPL. See fabrication/manufacturing-notes.md for the order settings and upload checklist. These files are prototype-review outputs, not authorization to order boards before the gates below pass.

Gates before PCB fabrication

1. Verify the Atlas cable/header mechanical fit and pin-1 orientation using the real cable and the supplied carrier-board STEP reference.
2. Measure pump startup and stall current at 12 V; confirm the 3 A input fuse tolerates four pumps starting together without nuisance opening.
3. Bench-check USB-only with the Feather out of its socket, 12 V with it seated, and USB attached while seated, using a current-limited sacrificial setup. Confirm D4 isolates SYS_5V in the last case.
4. Compile and exercise four ESPHome ezo_pmp instances through explicit TCA9548A virtual-bus IDs; test a stuck bus and hot replacement.
5. Confirm reverse polarity on the input terminal does not power the board and does not damage Q2, and that brownout and MCU reset leave the pumps in a known state.
6. Review the completed placement against a printed 1:1 board and the real enclosure/deck, inspect every Gerber and check the ten corrected JLC placement rotations against JLCPCB's preview, run GUI ERC, and obtain an independent schematic/layout review before ordering.

The board carries four pumps and nothing more. To run more, build a second board: it brings its own regulation, its own MCU and its own current budget. There is no expansion header and no inter-enclosure I2C -- ordinary I2C must not be routed between enclosures.