Skip to content

Chapter 8 — Firmware

Chapter 8 of 10  ·  Choose your path below

The V4 PCB runs two separate firmware images: one for the STM32 control chip and one for the ESP32 web interface. Both need to be current.

Choose your path:

Good news: you may already be done.

Peak Coffee ships the V4 PCB and HMI screen with the latest firmware pre-installed. If you purchased the Complete Kit and haven't done anything to the firmware, it's ready.

What you need to do:

  1. Proceed to STEP 1 — Verify firmware version below
  2. If the version is current, skip to Chapter 9 — First Run
  3. If an update is available, the ESP32 supports OTA (Over-The-Air) updates via Wi-Fi — no programmer needed

STEP 1B — Verify firmware version (Path B)

  1. Power on the machine (plug in, press switch)
  2. The HMI screen will show the Gaggiuino boot screen
  3. Navigate to Settings → System → About on the touchscreen
  4. Note the firmware version displayed

Check the current release at github.com/Zer0-bit/gaggiuino/releases.

If your installed version matches the current release, you're done with this chapter.

OTA update (if needed)

  1. On the HMI, go to Settings → System → Wi-Fi
  2. Connect to your home network
  3. Go to Settings → System → Firmware Update
  4. The ESP32 will download and install the latest UI firmware automatically
  5. For STM32 core updates: connect via USB-C (see the official Gaggiuino docs)

Skip to Chapter 9 — First Run.

Manual firmware flashing

You will flash the STM32 core via USB and the ST-Link programmer, and the ESP32 UI via OTA over Wi-Fi.

For this path, prepare:

  • ST-Link programmer (1×) — from your kit
  • USB-A to USB-mini cable (1×) — for ST-Link
  • USB-C cable (1×) — for PCB power
  • A laptop or desktop computer with USB ports
  • STM32CubeProgrammer (free download from ST) — install before starting

Install STM32CubeProgrammer before your build session

STM32CubeProgrammer is a 500MB download from ST's website. Install it on your computer before starting this chapter.

Download: st.com/en/development-tools/stm32cubeprog.html

STEP 1A — Download the firmware

Go to github.com/Zer0-bit/gaggiuino/releases.

Download the latest release. It contains two files: - gaggiuino-stm32.bin — the STM32 core firmware - gaggiuino-esp32.bin — the ESP32 UI firmware (flashed via OTA later)

Breaking update — check release notes

If upgrading from a firmware version released before February 2025, you must flash an intermediate version first. The release notes will tell you if this applies. Read them before flashing.

The ST-Link programmer connects between your computer (USB-A port) and the V4 PCB (4-pin SWD header).

  1. Connect the ST-Link to your computer via USB-mini cable.
  2. Connect the ST-Link to the PCB's SWD header. The header is labelled SWD and has 4 pins: SWDIO, SWCLK, GND, 3.3V.
  3. Power the PCB via USB-C (connect to a phone charger or computer USB port).

ST-Link connected to PCB SWD header

PIN 1 orientation

The SWD connector is not keyed. Pin 1 is marked on the PCB silkscreen with a square pad or a dot. Connecting the ST-Link backwards will not damage the board, but it will not connect. Verify orientation.

STEP 3A — Flash the STM32 firmware

  1. Open STM32CubeProgrammer.
  2. Select ST-LINK from the connection type dropdown (top right).
  3. Click Connect. The status bar should show the detected STM32U585.

If it does not connect: - Verify the SWD cable orientation - Try a different USB port - Check that the PCB is powered

  1. Click Open File and select gaggiuino-stm32.bin.
  2. Click Download (the blue button).
  3. Wait for the progress bar to complete. You should see "File download complete".
  4. Click Disconnect.

STEP 4A — Flash the ESP32 via OTA

The ESP32 does not use the ST-Link. It updates over Wi-Fi.

  1. Power the PCB on (USB-C only, machine does not need to be running).
  2. On the HMI screen, go to Settings → System → Wi-Fi.
  3. Connect to your home network.
  4. Go to Settings → System → Firmware Update.
  5. If prompted for the ESP32 binary, you can serve it from a local web server or use the Gaggiuino update server.
  6. Follow the on-screen prompts. The ESP32 will reboot automatically when done.

STEP 5A — Verify

After both flashes:

  1. Power-cycle the PCB (disconnect and reconnect USB-C).
  2. The HMI should boot to the Gaggiuino home screen.
  3. Go to Settings → System → About and verify the version matches the release you downloaded.

Both paths converge here

Whether you used Path A or Path B, you now have a PCB running current firmware and a screen that shows the Gaggiuino interface.

Before you close up the machine and power it on from the mains, verify the bench test in Chapter 7 STEP 8 passed — screen boots, thermocouple reads room temperature.

Next: Chapter 9 — First Run & Calibration