🛠️ Development & structure

A neutral, technical overview of how the cocktail machine’s controller is structured.

The firmware runs on an ESP32 and is written in Rust (based on the ESP-IDF framework, i.e. with the standard library). It performs two very different tasks at the same time: serving a web interface and clocking the stepper motors precisely. So that the two do not interfere with each other, the tasks are split across the ESP32’s two processor cores.

Architecture at a glance

Core 0 takes care of Wi-Fi and the web server, core 1 exclusively of the motors. This keeps the step pulses evenly timed, even while someone is loading the web interface.

How the two cores talk to each other

The web server and the motor control do not share any memory directly; they communicate via two clearly separated paths:

• Commands travel via a channel (a “mailbox”): the web server puts commands in (Sender), the motor control takes them out (Receiver) and processes them in order. A slow web page can therefore never disturb the motor timing.
• Status (positions, “homed”, “busy”) flows back via shared memory protected by a mutex that the web server reads for the display.

The web interface

The entire interface is a single HTML file with embedded CSS and JavaScript. It is baked into the firmware at compile time (include_str!) and served when / is requested – so there is no separate web space and no build pipeline for the front end. The JavaScript talks exclusively to the firmware’s small HTTP interface, e.g.:

Configuration & storage

Everything that is taught in – slot positions, heights, times and the drinks – is serialised as JSON (with serde) and stored in the NVS flash of the ESP32. It therefore survives power cuts and restarts and is identical from every device on the Wi-Fi. Received values are checked against fixed limits and clamped before saving, so that no faulty input can create dangerous states.

From recipe to movement

A drink is a list of steps “slot × portions”. When it is triggered, the firmware turns this into a concrete command sequence for the two axes – roughly:

The Syncpoints make sure that the axes wait for each other at the right moments – for example, so that nothing is ever dispensed while the carriage is still moving.

Built-in safety

• Emergency stop immediately stops both motors and the pump and empties all queues.
• Software end limits and speed limits restrict every movement.
• Homing abort: if the limit switch is not reached after a maximum number of steps, the axis stops (protection against a defective switch).
• Debounced limit switch against electrical interference pulses.
• Limited queues protect the ESP32’s scarce working memory.

Technology stack

Rust (Edition 2021) ESP-IDF (std) esp-idf-svc embedded-svc serde / serde_json anyhow HTML / CSS / vanilla JS

Project structure