Skip to content

FAQ — common questions & fixes

Over 100 real questions from Gaggiuino builders, with the fixes that actually worked — mined from thousands of community threads and cross-checked against the maintainers' own answers.

How to use this page

It's long on purpose. Use your browser's find (Ctrl / ⌘ + F) or the search box at the top of the page. Entries are grouped by subsystem below. If your exact symptom isn't here, the Troubleshooting chapter walks the big categories step by step.

Jump to: Power & Startup · Display · Wi-Fi & Network · Temperature Reading · Thermocouple · Temperature Calibration · Boiler & Heating · Boiler Element Wiring · Steam Mode · Boiler Leaks · Pressure Sensor · Pump & Dimmer · OPV / Pressure · Firmware Flashing · OTA & UI Updates · Flashing Recovery · Wiring & Harness · SSR · E24-Specific · Kit & Sourcing · Scales · Water Level · Profiles · Descaling

Power & Startup

My machine was working, I flipped the power switch off then straight back on, and now it's totally dead — no lights, black screen. What happened?

This rapid off/on-kills-the-machine pattern is known but has no single fix — it's a diagnostic hunt. Check the power cable is fully seated in the back of the machine (and any power strip is on), then verify mains actually reaches the switch. Post clear photos of your wiring and switch in a help thread; this usually needs eyes on your specific harness.

Warning

A live voltage test at the back of the power switch means probing exposed mains. If you're not confident doing it safely, stop and get help — 120/240 V will hurt you.

Why won't my machine stay on when I let go of the power switch?

If it only powers on while you hold the switch, you've fitted a momentary/spring-loaded switch — the wrong part. Fit the latching switch from the BOM. When doing the mod, remove, insulate, and label connectors separately before you start (especially on stock-wiring integrations).

My power lamp glows dimly even with the switch off. Problem?

Yes — that "phantom" glow points to a lamp/harness bridge that shouldn't be there (the stock lamps sit between the power switch and the boiler/SSR harnesses). Post photos of your switch wiring; it's diagnosed per-install, not with a universal fix.

I test-fired my SSR / had it wired backwards and now the board seems dead. Did I fry it?

Very likely. Feeding AC (or backfed DC) into the DC side of the board commonly toasts K1 and possibly the whole DC section. K1 is replaceable (desolder, fit the BOM part). Critically: find and fix the miswire first, or it happens again.

Warning

An AC wire landing on the DC side is the classic board-killer and a genuine shock/fire risk. Double-check every AC vs LV line against the schematic before applying power. Never power the PCB unless it's inside its 3D-printed enclosure — a loose energised board is dangerous.

I found melted leads at the power switch. What now?

Cut the damaged section back and re-crimp properly. Melted leads mean a high-resistance/loose crimp was heating up — that connection must be remade cleanly, not taped over. Inspect the switch terminals and nearby harness for heat damage while you're in there.

HMI / Display

My screen is completely black, but the Web UI works. Is the screen dead?

Isolate it: power the screen alone with a USB-A to USB-C cable directly (a straight USB-C source won't work — you must go through a USB-A port or adapter). If it still won't light (often after a knock), the screen is the fault — reflash it, and replace if that fails. If it does light on USB, the problem is the cable/comms to the PCB, not the screen.

My screen shows "TEXT" for pressure, "0000"/"000C", or NaN instead of real readings.

The screen and PCB aren't communicating — the UI draws fine (its own firmware) but no data arrives from the board. Two canonical causes: (1) Cable — reseat the screen cable at both ends, confirm RX↔TX and 5 V/GND on the right pins, try a spare cable. (2) Firmware mismatch — reflash so ui-embedded and the PCB are in sync. On Gen3, no PCB↔screen comms means it won't boot or heat — fix this first.

After an OTA update my screen went solid white, but the Web UI still works.

Incomplete/bad screen flash. Reflash the screen with the latest release files (the dark-then-reboot is the success indicator for ui-web). If a plain reflash won't take, re-flash the screen via the UI firmware reset tool / STM32CubeProgrammer. You do not need to re-flash the core again.

The screen version number doesn't match what I flashed / shows blank. Did it fail?

Probably not — the version reported on the screen has a known display bug. Trust the Web UI's version numbers. If the Web UI shows the correct build, you're good.

Part of my touch area doesn't respond / the screen wobbles. Bad panel?

Usually not. A partially-unresponsive touch area is typically the enclosure/mount pressing on the screen and interfering with the touch layer (edges and corners are the usual dead spots). Reseat the screen in its mount and relieve any pressure before assuming the digitizer is faulty.

My screen freezes after a while, or flickers.

Persistent flicker and mid-use freezes usually trace to the screen cable / a loose connection acting as an antenna — reseat or replace the cable first. If the screen and system cut out with an audible clunk during a shot, that's an AC/install wiring problem, not a display fault.

Wi-Fi & Network

I can't reach gaggiuino.local in my browser. First things to try?

Most often a browser HTTPS issue — many browsers force HTTPS, so http://gaggiuino.local fails. Disable "always use HTTPS" for the site (or try a different browser). Confirm you're on the same network as the screen. If .local still won't resolve, use the device's raw IP (mDNS is flaky on some OSes/routers).

gaggiuino.local won't work no matter what — how do I get in?

Use the built-in access point. Join the "Gaggiuino AP" Wi-Fi (no internet on it — that's expected), then browse to http://192.168.4.1. From there you can re-point the screen at your home Wi-Fi. This is also the standard workflow for headless builds.

The screen won't join my 5 GHz Wi-Fi, or the network list is empty.

The ESP32-S3 screen is 2.4 GHz-only — it can't join a 5 GHz or band-steered SSID and won't list them. Offer a real 2.4 GHz SSID (some mesh systems hide the band). An empty scan list despite nearby 2.4 GHz APs is usually a router quirk (see below).

Yes — a canonical gotcha. The Gaggiuino AP lives on 192.168.4.x and that can't be changed on the screen. If your LAN overlaps that range, routing and NTP break. Fix router-side: move your LAN to another range (e.g. 192.168.2.x) or put the screen on its own VLAN, then renew DHCP leases.

I lose Wi-Fi every time I power-cycle the machine. Normal?

A known nuisance, not something you caused. At startup, if the screen can't quickly rejoin your network it falls back to the AP. Usual causes are weak signal or a flaky AP; re-entering credentials usually reconnects. If it drops repeatedly, treat it as a signal/router issue.

I can ping the IP but can't reach the Web UI on my home Wi-Fi.

Almost always the router, not the Gaggiuino. Disable client/AP isolation (guest-network isolation blocks device-to-device traffic), make sure the screen and your device are on the same 2.4 GHz network (not one on Guest/IoT), and check for MAC filtering (add the screen's MAC to the allowlist if you use it). There's no Gaggiuino-side fix — it's router config.

The screen clings to my old Wi-Fi after I changed routers. How do I reset it?

Known firmware bug. Reliable workaround: temporarily recreate the old SSID and password (e.g. a phone hotspot), let the screen join it, then use the "disconnect" option in settings so it forgets the network — after which you can point it at the new SSID cleanly.

Temperature Reading

Temp reads NaN the moment I connect 230 V, but it's rock-solid on 5 V USB. What's wrong?

Classic HV interference — the thermocouple wire is picking up noise from the mains/boiler wiring. Reroute the TC cable low along the floor of the case, away from all HV, and never parallel to or resting on the boiler connectors. "Fine on USB, garbage on 230 V" is almost always noise pickup, not a dead board.

Note

If your temperature reads perfectly (~95 °C) but you still get an intermittent "Thermocouple fault detected!" popup under heater load, that is a different fault — see Boiler Element Wiring below. Rerouting will not fix that one.

Temperature flickers between NaN and negative numbers / bounces around.

Same root cause as above — noise on the thermocouple. Check routing first (keep it far from HV, use standoffs/kapton to lift it off the chassis and boiler connectors). If routing is clean and it persists, the probe is likely faulty — swap in the C&G BOM thermocouple.

My temperature jumps for the first ~10 minutes after power-on, then settles.

Generally normal warm-up. The reading stabilises once the boiler is fully up to temperature. Only hunt for interference/probe faults if the jitter continues once fully warmed.

Temp reads a solid 0 °C (or "Core 0000") on the bench test and the boiler won't heat.

Isolate probe vs board: with the machine on, remove the two TC wires from the green terminal and short the terminal. If you now get a reading, the fault is the TC or its wires (seating, ferrules, continuity). If you still get nothing shorted, it's the PCB side (terminal block, solder joints, or MAX chip) — reflow the joints or replace the MAX board.

My temp drops to 0 for a split second mid-shot, then recovers. Broken?

Those momentary dropouts are the TC briefly losing signal, usually from HV/LV cables too close or a slightly loose/damaged probe. Performance is unaffected; it just looks ugly on the graph. Improve cable separation; swap the probe if it bothers you.

Temp swings ±6–7 °C while idle but is flat while brewing. Normal?

Note

Yes. At idle the boiler cycles around the setpoint so the wall temperature swings a few degrees; during a shot the incoming water and Brew Delta logic keep it much flatter. A perfectly flat idle reading would need a PID — the swing is expected.

Thermocouple

Does the PCB need a grounded or ungrounded thermocouple?

Warning

The PCB build requires an ungrounded thermocouple. Older LEGO/stock builds could sometimes get away with a grounded probe, but the MAX-based PCB needs the junction electrically isolated from the boiler. A grounded (or degraded, partially-shorting) probe causes intermittent temp read errors and NaN.

How do I test with a multimeter whether my thermocouple is grounded?

Check continuity between the boiler (the brass stud the TC screws into) and each of the two TC wires. An ungrounded TC — what you want — shows no continuity to the boiler body. Continuity to the stud means the probe is grounded (or its insulation broke down) and needs replacing. Do it in place; just remove the two wires from the PCB first.

The insulation looks fine but I still get intermittent errors. Could it still be the probe?

Yes. The junction can touch the housing internally where you can't see it, or the insulation can break down under heat, giving intermittent grounding. The cable is also fragile right where it meets the brass stud. If routing is clean and continuity is borderline, replace it with the C&G ungrounded M4 probe.

Which way round do the thermocouple wires go?

Red is positive (+), white is negative (−). Match those to the +/− labels on the PCB terminal. Reversed polarity can trigger a "thermocouple polarity reversed" message and NaN. Polarity isn't a cure-all — some builders swapped it and still read 0 °C because the real fault was elsewhere, so fix it but keep diagnosing if it doesn't clear.

Should I keep the ferrules crimped on my thermocouple wires?

No — cut them off and clamp bare wire, both wires the exact same length. Ferrules on solid TC wire are a recurring cause of poor contact; they don't seat well in the green terminal, and a bad TC connection can even stop the PCB booting. Suppliers deliberately don't add ferrules — the manufacturer does.

The DIY-EFI kit thermocouple keeps giving temp read errors. Is it a dud?

The DIY-EFI/Finglai probes have less consistent QC and are easier to damage than the C&G part. If you've cleaned up routing (away from HV) and it still throws errors or erratic readings, replace it with a C&G ungrounded thermocouple from the BOM.

How do I test the thermocouple without pulling it out of the boiler?

Test in place — remove the two TC wires from the PCB and do your continuity/grounding checks there; no need to unscrew the probe. Quick sanity check: dunk the tip in ice water (should read ~0 °C) and boiling water (~100 °C).

I get "Thermocouple fault detected!" intermittently, mostly under heat/load, and my routing is clean.

Warning

A major cause is the boiler heating elements wired in parallel instead of series on a 230 V machine — the boiler over-draws and sags the mains, tripping the MAX fault bit. See Boiler Element Wiring and the Troubleshooting chapter. Don't keep running the machine while it faults during heating: an unreliable TC signal risks thermal runaway and a blown fuse.

Is it safe to keep using the machine "briefly" with a faulty probe until the replacement arrives?

Warning

No. A faulty/intermittent thermocouple means the controller can't trust the boiler temperature — risking overheating, thermal runaway and a blown thermal fuse. Wait for the correct C&G replacement rather than running a known-bad probe.

Temperature Calibration

At ambient my temp reads ~20 °C but the room is 23 °C. Fix the offset?

No. There's a default 7 °C offset compensating for the difference between the boiler-wall temperature the probe measures and the water temperature at the grouphead. It isn't meant to match the room — leave it at 7 °C unless a Scace-type measurement tells you otherwise.

My probe reads ~30 °C too high and the boiler overheats during brew. Wrong offset?

Not calibration — a 30 °C error points to a faulty or badly-seated thermocouple, not the offset. Confirm polarity and tight terminals, then check the probe (steam-during-brew is a classic sign of the TC working loose or failing). Fix the hardware before touching the offset.

The temperature shoots well above target during and after a shot. How do I stop it?

Note

That's Brew Delta working as intended — the firmware raises boiler temperature during a shot to offset cool incoming water, and residual heat makes the reading overshoot right after. Well over your delta setting post-shot is expected, not a fault.

Should I turn Brew Delta off for my Classic / Pro / Eco / E24?

Note

No — defaults (Brew Delta on) are recommended for these models; it compensates for the temperature drop during extraction in the small boiler. Leave it at defaults unless you're dialling in with a Scace-type device.

How should I actually measure grouphead temperature to tune the offset?

Measure water exiting the grouphead in near-real-brew conditions — a Scace-type device is the accurate method. Measuring outside a portafilter or past a spout reads low. Only adjust the 7 °C offset from a proper grouphead measurement.

Boiler & Heating

Machine's on, everything works, but the boiler stays stone cold. Where do I start?

Work the heat chain with a multimeter, in order: (1) continuity through the boiler thermal fuse / reset switch (a popped fuse is the #1 cause), (2) 5 VDC at the SSR control pins when sensed temp is below target, (3) mains voltage on the SSR load side, (4) element resistance across the boiler terminals. The first step that reads wrong is your fault location.

The SSR light is solid red but the boiler never heats. Bad SSR?

The red light means the PCB is commanding heat, so the control-side wiring is fine. If you have 5 VDC on the control side and the light on, but no mains on the load side, the SSR is dead — replace it. First confirm the PCB is wired to the SSR control (LV) side, not the load side.

The boiler heats, but only when I flip the STEAM switch — not for brewing.

Classic un-cut expansion-board ground plane — the system reads a control switch as always-on and sits in steam mode. Fix: sever/cut the ground plane on the expansion board as shown in the install instructions (some builders instead direct-wire the steam switch and cut pin C15). Brew-mode heating then works normally.

My boiler overshoots the target by 5–15 °C on heat-up. Broken?

A little overshoot on first heat-up is normal. Excessive/worsening overshoot almost always means a thermocouple problem: probe not seated tightly, not enough thermal paste in the boiler well, or a loose/damaged TC. Re-seat with thermal paste first. Lowering heater power (e.g. HPWR ~550) can tame it, but fix TC seating before changing settings.

My thermal fuse keeps blowing when I steam.

Your steam temperature is too high for the fuse. With the 185 °C resettable fuse and a default 155 °C steam target this can trip during long steam sessions — lower the steam temperature (or fit a higher-rated fuse). A fuse blowing during brewing is a runaway boiler — find the root cause first.

Is the cup-warmer plate supposed to be electrically powered?

No — it's passively warmed by the boiler underneath; its leads are ground only. Never wire mains to it. If it ever gets AC on it, you have a short to the case — stop and investigate.

Boiler Element Wiring

How do I check the boiler elements are wired correctly for my mains voltage?

The boiler is identical for 120 V and 240 V — only the wiring differs. Each element is roughly 20–22 Ω. Measure across the boiler feed:

  • 230/240 V → elements in SERIES → ~40–44 Ω total
  • 120 V → elements in PARALLEL → ~10–11 Ω total

An OL / infinite reading on one side means a dead element — the boiler must be replaced.

Danger

Wiring a 230/240 V machine in the 120 V (parallel) layout roughly quadruples the power into the boiler (≈4800 W, ~20 A): it cooks the boiler, blows fuses, and trips intermittent "Thermocouple fault detected!" errors under load even when the temperature reads perfectly (the mains sag drags the board's supply rail). Confirm your resistance matches your mains before powering on. See the full mains-safety callout in Chapter 5 → Build the Harness.

The diagram shows a diagonal jumper across the boiler terminals. Is that right?

Yes. For a series (230/240 V) boiler, hot enters one corner, a diagonal jumper links the two elements, and neutral exits the opposite corner. If your stock machine has the link on the bottom two poles, either move it to the diagonal to match the schematic or leave it — what matters is that you measure ~40–44 Ω across the correct pair. Probe pairs of terminals to find the ~20 Ω / ~40 Ω sets, and make sure the jumper is tight (a loose jumper is a common intermittent fault).

Steam Mode

I flick the steam switch and nothing happens — no temp rise, no pump.

Almost always a steam-switch connection fault. Re-check the spade/connector on the steam switch and its wiring to the PCB; if you did the combined-connector insulation mod, make sure you didn't create a cold joint. Confirm the target temp jumps to ~155 °C when you flip the switch — if not, the signal isn't reaching the board.

My steam is weak / the boiler won't reach steam temp (stuck ~120–130 °C).

Two common causes: (1) Pressure too high — the system refuses full steam temp if boiler pressure is high, so crack the steam knob to bleed pressure as it heats. (2) A thermocouple lag (loose probe / interference) making the reading crawl. Don't just drop the steam target to force it — that only gives weak steam.

When I switch to steam the pump randomly runs up to ~12 bar. Normal?

In steam mode the system pulses the pump to keep a little pressure, but continuous running to 12 bar isn't right. Check for a stuck/miswired brew switch or an un-cut expansion-board ground plane making it think a control switch is on, and verify the steam switch wiring.

Water comes out of the steam wand whenever the pump runs.

If the steam knob is open, water flows from the wand any time the pump runs — expected; close the valve to stop it. If it pours out with the valve closed, suspect the stock steam valve (prone to leaking past a "closed" seal) or air in the pressure line (run the UT tube-fill profile to purge).

Boiler Leaks

Water leaks from the top of the boiler around the temperature probe.

The thermocouple screws into the old thermostat/steam port; a poor seal there leaks. Tighten the probe properly and seat it with thermal paste (which also fills gaps for accurate readings). If the threads are chewed, chase them with an M4 tap before reseating. Seal with silicone self-amalgamating tape rated for boiler temps — ordinary PTFE near the boiler must be high-temp.

There's a leak where the steam wand meets the boiler.

Separate path from the probe seal — usually the steam wand / steam valve gasket, or the stock valve weeping. Put something dry under the tip at steam temp to confirm valve-seep vs joint. Re-seat/replace the gasket; don't over-tighten trying to stop it, as that distorts the seal.

Could a boiler leak fry my electronics?

Yes — a top-of-boiler or wand leak can drip onto the PCB. Power off immediately, dry everything, and find the source (probe seal or steam-valve gasket) before running again. Keep the LV thermocouple/PCB wiring routed away from and below any drip path.

Pressure Sensor

The transducer reads 0 bar all the time. How do I tell where the fault is?

Disconnect the transducer from the plumbing (leave it wired to the PCB). Open to air it should read ~0.0 bar. If it does, sensor and board are fine and the problem is plumbing/install; if it still reads 0 or wild disconnected, the fault is the transducer, its cable/JST crimp, or the ADS board. Then run a Flush with a blind basket in and watch whether the number climbs.

My transducer reads a static value that never changes with the pump.

A dead-flat reading (e.g. constant 0.4, 1.5, 3 bar) is a wiring/connection fault, not plumbing. Re-crimp or reseat the JST at the transducer, check the A0 solder joint on the ADS1115, and confirm the signal wire reaches the board. A reading that moves but is jumpy is vibration (below).

I'm getting a negative reading like −0.1 or −1.5 bar. OK?

A steady −0.1 is usually harmless. A large −1.5 bar is a fault. Check the transducer isn't resting bare against the metal chassis (that couples electrically) — insulate it with foam. Then recheck the data-wire connection and the ADS board, and confirm you have the 0–1.2 MPa BOM sensor (the wrong-range part reads nonsense).

Which transducer wire is which, and does the order matter?

Common transducer: red = 5 V, black = GND, green = signal. It absolutely matters. You can move wires between the PCB terminal slots (lift the locking tab with a small flathead) to match the silkscreen.

Warning

Never swap the 5 V (VCC) and signal wires — feeding 5 V into the signal line can destroy the transducer or the ADS input. Double-check red→5 V, green→signal against the silkscreen before powering on.

How tight should the transducer be screwed in?

Hand/finger tight only — do not crank it with tools. Over-tightening the plumbing connection deforms the sensor and gives bad readings; several people fixed erratic pressure just by backing it off. Use thread sealant/PTFE on the threads and bleed the system before final install.

My pressure reading is jumpy/noisy and it's stopping shots early.

Pump vibration coupling into the transducer. Wrap the transducer in foam to dampen it (this also buffers it from HV EMI). Route it away from the big HV crossover; noisy readings otherwise trip "Releasing Pressure" and cut shots short.

Pump & Dimmer

The pump runs continuously the moment I power on, before I touch brew.

A wiring mistake, not priming. A brief prime pulse at startup and periodic pressure releases while heating are expected, but continuous running with brew off means the pump line is mis-wired (often pump/3WV lines swapped, or the switch wiring). Fix the wiring before trusting any sensor. If the pump/valve is energised the instant it boots, trace which component is being fed from an always-on line.

The pump won't run when I flip brew. How do I isolate pump vs PCB?

Classic diagnostic: briefly swap the pump wire from the "P" terminal to the "3" terminal (or swap P/N) and flip brew. If the pump now runs, the pump is good and the fault is upstream (dimmer/wiring/firmware). You can also temporarily run the pump straight off mains to confirm the pump is alive, bypassing the PCB.

The pump runs and buzzes but no water comes out.

Almost always an air-locked / dry pump on first run. Prime it: push water through the intake with a syringe, or run Flush / Manual with the flow slider full-right and a blind basket to pull water up. The Ulka self-primes once it gets suction, but an air leak stops it — check for leaks first.

I turn brew on but the dimmer does nothing / no light on the dimmer.

The dimmer LED should light/blink when the pump is driven. No LED = no drive signal reaching the dimmer. Check the brew-switch wire actually goes into the dimmer, check continuity from dimmer output to the pump spade, and verify the signal pin. A dimmer whose LED never lights with a good signal is dead.

The pump fuse / TR1 triac blew, or something smells burnt.

A downstream symptom of a wiring fault — a loose crimp or short. Fix the wiring that caused it before replacing the part, or the new triac blows again. Redo loose crimps, recheck HV wiring, then fit a new fuse/triac.

Warning

Never live-probe or swap HV terminals with the machine plugged in. Unplug before any wiggle test or terminal swap.

OPV / Pressure Calibration

How do I test my max pressure?

Put the blind basket in the portafilter and run a Flush (or Manual full-right) and read the peak on screen. Without resistance you'll just see near-zero — the blind basket lets the pump build to the OPV limit. Flush mode has no pressure cap; the number you see is your OPV ceiling.

What should max pressure read? Mine hits ~12–13 bar — too high?

A blind-basket peak around 10.5–13 bar is fine and expected. It matters more that it gets safely above ~10.5 bar than that it's exactly 12 — the software regulates actual brew pressure down from there. ~13 bar on backflush is within limits.

Why can't I get above 5–6 bar even with the pump flowing hard?

If water pours out the OPV tube, your OPV is set too low and opening early — the pump's effort escapes there. If no water exits the OPV, it's a restriction/channeling issue (grind or capped flow). On a dimmer build you max out at the OPV limit, so raise the OPV.

Why raise the OPV if the software controls pressure anyway?

Because the OPV must be high enough that it never opens while Gaggiuino regulates. If it opens partway during a shot, water leaves via the OPV while the firmware thinks it's going to the cup — so pressure control breaks. OPVs leak open below their rating, which is why you set them well above target.

What OPV spring should I fit? The US Evo spring isn't enough.

Rule of thumb: spring rated ~1.5 bar above your highest target. For 9-bar shots that means a 10.5 bar or higher spring — most fit a 12 bar spring. US Evos ship with a 9-bar spring that opens too early for profiling; swap it.

Can I avoid buying a spring — is the washer mod legit?

Yes. A stack of flat washers (e.g. 3 mm) under the existing OPV spring pre-loads it and raises the opening pressure. Counterintuitive (adding load raises the setpoint) but it works, and plenty run it instead of a new spring.

Firmware Flashing

How do I flash the core firmware to the PCB for the first time?

Follow the "Wired — STM32 / Blackpill" section of the MCU Flashing guide. You need an ST-Link V2 and STM32CubeProgrammer: connect ST-Link over SWD to the PCB debug header, connect in the app, then full chip erase + program the correct .bin. Power the board from the ST-Link's 3.3 V during flashing — don't also feed USB-C.

Which core .bin file do I flash?

For a PCB v4, performance-pcb-pca.bin (not the older pcb-pca.bin). For a Lego + STM32U585, performance-lego-pca.bin. Only flash -ncp instead of -pca if you're certain your ToFnLED uses the NCP LED driver — "when in doubt, use -pca." Grab all files from the same release tag.

Wire ST-Link V2 to the PCB SWD header (J27 on PCBv4): GND→GND, SWCLK→SWCLK, SWDIO→SWDIO, 3.3 V→3V3. A common mistake is landing on the wrong row of the header — check the diagram on the MCU Flashing page.

PCB v4 (STM32U585) supports OTA core updates over Wi-Fi. PCB v3 with a blackpill (STM32F411) cannot — core must be flashed wired with ST-Link + CubeProgrammer. UI files (ui-embedded, ui-web) are always OTA, never via CubeProgrammer.

Install the CP210x USB-UART driver (some units need alternate PIDs via Windows Update). Use Edge or Chrome for the browser flasher. Confirm your cable is a data cable, not power-only. For screen restore you must use a USB-A-to-USB-C cable — a direct USB-C-to-USB-C will not work.

OTA & UI Updates

How does the OTA / "update all" process work?

On the LCD: Settings → About → "Update", or the update button on the WebUI settings page. The screen (ui-embedded + ui-web) auto-updates over the Internet; PCB core updates the same way only on v4/U585. First: disable Bluetooth scales and make sure the screen is on Wi-Fi with a strong signal and real Internet so it can pull the binaries.

Which UI files do I flash — there are a lot?

Flash strictly ui-embedded.bin (LCD builds) or ui-headless.bin (headless), plus ui-web.bin. Disregard the ui-embedded_s3xxxxxxxx / _p43x variants — do not hand-pick those. Follow the latest release page's own STEP 1–4, not old threads.

Do I flash ui-headless if I have an LCD screen?

No. LCD → ui-embedded + ui-web. Flash ui-headless only if you actually have a headless module. The wrong UI type is a common self-inflicted brick.

When I flash ui-web the screen goes dark — did it fail?

No — expected. When ui-web starts the screen goes dark; when it comes back / reboots, that's the success indicator. Refresh your browser and check the versions.

I'm on an old build — can I jump straight to the latest release?

No. Upgrading a pre-2025-02-16 build: flash the breaking release 616ea70 first, get everything working (temp, pressure, uptime all showing), then update to latest — all three components, not just core. .../releases/latest always points to the true latest.

Flashing Failures & Recovery

Core shows 0000 (or blank) and temp reads 0/NaN after updating.

Core 0000/blank means the screen and PCB aren't communicating — a version mismatch or wiring problem, and OTA can't fix core in that state. Reflash core performance-pcb-pca.bin wired via ST-Link + CubeProgrammer (matching the mbed/web version shown), reboot, confirm temp + pressure. Also verify the thermocouple is plugged in — the PCB won't boot without it.

"Core firmware update has failed" — OTA keeps failing quietly on core.

On PCB v3/blackpill the "update all" path only flashes UI/Web and silently fails on core — flash core wired. On v4, if it still fails, make sure BT scales are off and Wi-Fi is solid, then fall back to the Emergency Firmware Restore tool or a wired ST-Link flash.

My screen is white / garbled / stuck after an OTA update.

First just flash the latest release files again — OTA sometimes doesn't take on the first try. If that fails, use the Emergency Firmware Restore tool (browser-based): it wipes the screen and rewrites the bins with a correct memory layout, which fixes most white/garbled/stuck cases.

What is the Emergency Firmware Restore tool and when do I use it?

A browser recovery (Edge/Chrome) that fast-forwards the screen to a recent release and rewrites its firmware. Remove the screen, connect it directly with a USB-A-to-USB-C cable, select LCD (or headless), Connect, follow the steps. It fully wipes the screen — first back up settings, custom profiles, PZ, and load-cell factors. After restore, flash core to match the version it landed on.

I got a "watchdog restarted" message during flashing — did I brick it?

No — "watchdog restarted" commonly happens right after flashing. Reboot, refresh, check the version. (It can also trigger with a Bluetooth scale connected — disable BT scales if it recurs.)

After a failed update the PCB and screen won't talk at all — where do I start?

Confirm it's software, not wiring (if it passed bench test earlier, wiring is likely fine). Reseat both ribbon connectors on the screen and the one on the PCB (power off). Then get everything onto one matching version — flash core wired to 616ea70 first if you were pre-breaking, confirm temp/pressure/uptime, then OTA the rest to latest. Verify final versions from the WebUI.

Wiring & Harness

A wire at my power switch got burnt/melted — what happened?

Danger

A burnt spade is a high-resistance connection, not a "bad switch" — a loose or poorly-crimped spade heats up under load and melts (and can start a fire). Cut off the old connectors on both sides, crimp fresh spades (bare wire fully inside the barrel, nothing sticking out), then insulate. Don't just re-seat it. If the female spade on the switch body is damaged, replace the switch.

Should I use the kit's stock harness or build a custom one?

Both are supported. Stock integration reuses the Gaggia loom + kit HV wires (easiest, fewest tools) — best for lower DIY comfort. Custom wiring cuts out the stock loom and the Eco board and you make your own connections (neater, but needs crimping/soldering tools and extra connectors). With the Peak kit you can still go custom — you just don't use Peak's HV wires and follow the custom schematic.

Do I put the ferrules that came on the thermocouple wires into the terminal block?

No — remove them. Ferrules on the thermocouple are a mistake (poor clamp, bad readings, added failure point). Clip them off, cut both wires to the exact same length, and clamp bare wire in the screw terminal.

Can I crimp the thermocouple / solid-core wire, or clamp bare?

Clamp bare. "Most people end up clipping the crimps and clamping bare wire." Crimping doesn't work well on solid core and just adds a failure point on the TC.

How do I route wires to avoid temperature errors?

Canonical layout: HV on the LEFT, LV on the RIGHT. Route the thermocouple down and below the switches, as low as possible, then up the right side with the rest of the LV. If the TC runs past HV wiring or the SSR it picks up interference (NaN/temp errors). One builder fixed instant NaNs just by moving the TC out from behind the SSR.

My spades are the nylon insulated type — fine everywhere?

Warning

Nylon spades are fine at the plug, PCB, pump, and switches, but nylon melts near the boiler. For anything touching the boiler (e.g. the resettable thermal fuse), use bare/uninsulated spades covered with high-temp silicone self-fusing tape or heat-shrink rated ≥ 155 °C.

There's bare metal / exposed spade showing after I crimped — a problem?

Warning

Yes — exposed switch terminals and bare spade shanks can arc against the metal case. Ensure bare wire is entirely inside the crimp barrel, and wrap any exposed HV metal (e.g. an empty switch terminal) with silicone tape.

SSR

Screen boots but the SSR just clicks once, no heating. Bad SSR?

Confirm mains reaches the SSR, then measure across it. With the machine calling for heat, measure voltage on the boiler (output) side of the SSR — line voltage there but no heat = the element is suspect; nothing on the output side = the SSR isn't switching (check the DC control side and its 5 V signal). Reseat the connections and verify the control wires are on the right terminals.

My orange/black control wires — which SSR terminals?

The DC control wires go on the terminals labelled 3–32 VDC (the pair on a Fotek-style SSR), not the HV side. If it won't switch, confirm with a meter that the PCB is sending ~5 V to those control pins.

The AC and DC sides of my SSR are next to each other and I'm getting temp errors. Does orientation matter?

Yes. Rotate the SSR so the HV AC connections are on the left and the LV DC control on the right, away from the thermocouple/LV wiring. Control/TC wires next to the AC side pick up interference and cause temp errors.

My SSR says "FOTEH" — is that fine?

Warning

No — "FOTEH" is a counterfeit (the real brand is FOTEK). Buy the SSR in the BOM. Counterfeit SSRs are a known failure/fire risk. Replace it.

E24-Specific

My E24 turns itself off after ~15–20 minutes. How do I stop it?

That's the Eco board (auto-off timer), standard on Eco/E24. The only officially-supported fix is custom wiring, which removes the Eco board entirely. Modifying the Eco board to defeat the timer is unsupported. A machine that runs 40 min without shutting off doesn't have an Eco board.

Can I just remove the spring to make the momentary switch a rocker?

The spring-removal converts momentary to bistable (many builds do this). On the E24 it interacts with the Eco timer — the clean supported path is custom wiring with the Eco board removed. If you drive power from a smart relay (Shelly/Sonoff), configure it to treat the SW signal as a push button so each press toggles; otherwise the machine only stays on while you hold it.

My brew switch has extra/unused terminals — how do I wire it?

Only piggy-back the DC/LV signal wires — never route HV through the extra poles. Bridging unused terminals is fine when it just parallels the switch (connecting #4/#5 to #1/#2 is safe; you only lose the independent pole). Leave empty HV terminals insulated, and match the schematic exactly.

After every shot my E24 shows "Releasing Pressure!" and gets stuck.

Troubleshooting order: (1) update to latest firmware; (2) check the pressure transducer — unscrew, inspect the flat white gasket, re-seat, screw back hand-tight only (a bad/loose transducer reads false high pressure so the machine thinks it never released). Test whether it clears when you remove the portafilter. If the 3WV clicks but pressure stays ~12 bar, suspect the 3WV not venting.

Kit & Sourcing

Peak Coffee kit vs DIY-EFI kit — do I need to buy extra parts?

Both ship the PCB + core components. Cross-reference kit contents against the BOM on gaggiuino.github.io and buy only the leftovers (often AliExpress). Custom wiring has a separate "alternate components" BOM; how much extra you buy depends on how much stock loom you reuse. Nobody sells a finished custom harness. Double-check you selected the right options (e.g. dualScaleBoard) so parts match.

The Blackpill is the STM32F411CEU6 MCU; the ST-Link is the separate debugger to flash it. What's included depends on the pack (Premium/Complete include more). Counterfeit ST-Links exist — if CubeProgrammer recognises the device but freezes at 0%, suspect a fake. Buy the versions currently in the BOM (the recommended chip changes over time).

Can I add a smart switch (Shelly/Sonoff) for scheduling instead of the Eco timer?

Yes — the popular alternative to the Eco board (Shelly 1 Plus PM, Sonoff MiniR4). Configure "detach relay" so it toggles power independently of the physical switch, and set it to read a momentary SW input as a push button. Note: unlike the stock IEC switch (which breaks both live and neutral), in this setup neutral stays connected — a tradeoff to be aware of. Check the relay's amp rating.

Gen2 or Gen3, and kit vs full DIY/Lego?

Starting from scratch with no specific reason, choose Gen3 — actively developed, gets the 4.3" screen. Lego (breadboard) looks cheaper but usually costs similar or more (parts come in larger lots, extra tools). Get the correct machine variant — "Classic" vs "Classic Pro" kits differ in plumbing.

Scales & Load Cells

One of my load cells reads negative / goes down when I add weight. Broken?

No, by design. One load cell is mounted "upside down" so the tray sits level, so its calibration factor must go negative. During calibration, drive that cell's factor negative until the reading goes positive and tracks weight — don't try to make both cells positive.

My hardware scales are jumpy and don't respond to weight.

First confirm the build is enabled: on Gen2/PCB v3.1 you must add extra_defines.ini and reflash with the all-pcb-stlink firmware — HW scales are a compile-time option. If enabled and still jumpy, it's usually wiring: stray strands shorting the load-cell pads, swapped wires (white = CLK, red = VCC), bent FPC pins, or a nicked cable. Reflow the joints and check continuity to the PCB header.

The scale drifts steadily after I tare, even with no load.

Steady one-direction drift right after tare usually means a bad load cell — swap in the spare cell(s) from your kit. Before replacing, route the scale cable away from HV, reseat it off the 3D prints, and stabilise the drip tray. Small ±0.1–0.2 g fluctuation is normal.

My shot weights come out several grams over target.

The pump stops on the profile's exit conditions, not just the global weight. Lower the profile's target/yield weight so actual output lands right, or set per-phase weight exit conditions to 0 to disable competing stops. Also verify PZ is calibrated (0.28 is usually too high).

How do I run load-cell calibration correctly?

Don't just press on the tray. SETTINGS → SCALES → CALIBRATE, unscrew both load plates, and insert the 3D-printed calibration plate before adjusting factors. Skipping the plate is the most common reason numbers won't dial in.

My Acaia/Bookoo/DiFluid Bluetooth scale won't stay connected.

Only Bluetooth scales should be enabled — turn OFF hardware and predictive scales, enable BT scales, Save, then reboot. The screen uses BLE and auto-discovers (no manual pairing); make sure the scale isn't already connected to your phone. Reconnect-on-boot and the BT-enable setting resetting after power-off are known bugs — update to the latest release.

Water Level Sensor

My water level is always 100% and won't drop as the tank empties.

The ToF sensor has a minimum reading distance, and a full tank's surface often sits inside that dead zone — so it reads 100% until the level drops far enough. Expected; readings become accurate once the tank is roughly half to three-quarters full. Confirm the sensor works by waving your hand in front of it.

The "Fill water tank" warning is always wrong and blocks the screen.

Fix the offset values (distances in mm from the sensor): Empty must be greater than Full (the surface is farther away when empty). A reversed or too-close pair is the usual cause. 6 (full) and 130 (empty) get most builds close — adjust and reboot.

The reading is erratic / only lands on values like 30% or 69%.

Clear tank and water are hard ToF targets, and ambient light and the tank's finger-pull cutout throw it off. Push the ToFnLED board slightly back so the cutout isn't in view, block stray light, and re-check the housing seating. Most builders just tune the endpoints and ignore the noisy middle.

The ToFnLED lights up but the screen shows no water level.

Powered but not communicating. Check the header/connector on the ToFnLED board and the data pins on the cable (try the other end if reversible), and verify wiring against the guide. Confirm the sensor didn't get water-damaged.

Profiles & Pressure Profiling

Why does my shot stop several grams before the target weight?

Stop-on-weight intentionally stops short: when the pump cuts, water already in the group keeps dripping, so the system compensates to hit target. With predictive scales the preview can read up to ~15 g high — tare exactly when the first drops hit the cup. If it stops far too early, check for a conflicting global stop condition (below), not the scale.

My shot suddenly stops mid-extraction and jumps to puck-drying.

The profile likely has a global "Stop on total water pumped" limit hit before your weight target. Competing stop conditions are bad profile design — check the profile's global stops and remove/align the water-pumped limit.

I edited a profile in the WebUI, now it errors / won't save / disappears after reboot.

Known finicky bug on some screens: edits fail to save, the profile can't be selected/deleted, and profiles can vanish after reboot. Workarounds: always duplicate a profile before editing (there's no "reset to default" for a modified one), and if persistent, update to latest and re-flash the screen.

How do I upload or create custom profiles?

Open the WebUI and go to the Profiles page — upload/download buttons are there. Download community profiles (they appear as a group). To reset a stock profile you changed: long-press the profile → Default → long-press → OK. There's no reset for a modified profile, so copy before editing.

My pre-infusion is flow-based but the shot doesn't match the preview.

Correct behaviour: pre-infusion often runs as a flow phase, then the main phase switches to pressure. In a pressure phase the system targets pressure (e.g. 9 bar) and uses whatever flow is needed — so the flow line won't match the preview, only the pressure target will. For a weak/variable pump, start with no-preinfusion flat-bar pulls; they still beat a stock machine thanks to temperature control.

How do I make a downloaded profile the default on startup?

Switch to any non-default profile, then press the Save icon. Reordering profiles alone does not change which loads on boot.

Descaling & Maintenance

How do I run the built-in descale program?

Fill the tank with descale solution (citric acid, ~100 g per 2 L), fit a blind basket, and start descale from the home screen. Run the full tank of solution out, then a full tank of clean water to rinse. Finish: turn off the brew switch, return Home, and select any profile to re-enable brew mode. Skipping the blind basket is a common mistake.

The descale (or flush) button does nothing / won't start.

Usually HV interference on the brew switch. Toggling the brew switch can jog it, but the real fix is separating the brew-switch wiring from HV lines. If flush/descale still won't trigger the 3WV while normal brewing builds pressure, re-check the brew-switch and 3WV wiring.

How often should I backflush and descale?

Backflush with plain water daily and with Cafiza weekly (a puck screen lets you stretch the water backflushes). Descale intervals depend on water hardness, boiler type, and usage — no fixed schedule. Don't over-descale or over-concentrate the solution.

My machine hits 12 bar and the pressure-hose bursts during backflushing.

Against a blind basket the OPV opens and pressure spikes (>12 bar), stressing the transducer hose. If it only spikes on the first flush and you haven't descaled recently, descale first and confirm the OPV is reassembled correctly. Use the reinforced hose, not the thin BOM hose, on the pressure tap.

After descaling I see flakes/particles in the group. Did I damage the boiler?

On non-coated boilers, white/calcium flakes after descaling are just dislodged scale, not damage. Rinse thoroughly and clean the shower screen and dispersion plate. Only worry about pitting/corrosion on coated ("gated") boilers.

Something unclear? Something missing?

This guide is a living document — one real E24 build plus the community's hard-won knowledge. If a step tripped you up, an answer looks wrong, or something should be here and isn't, I want to know.

  • Report it or request an addition: open an issue on GitLab — the surest way it won't get lost.
  • Fix it directly: every page has an edit pencil (top-right) that opens a suggestion straight from the source.
  • Just reach me: djieno.com.

If this guide saved your build — or your boiler — pay it forward: when you crack something new, drop it back in the Gaggiuino Discord so the next person finds it too.

Why this FAQ exists

Most of these answers were dug out of the community the hard way — one thread, one multimeter reading, one "wtf" at a time. This page exists so you spend less time in that hole than I did. That's the whole point.