Writing Frothy is like having a conversation with your device. Ask it to do something, and it replies immediately. Change your mind, and try again. No compiling, no uploading, no black box.
Normally, programming a microcontroller goes like this: you write code on your computer, compile it, upload it to the board, and hope. Once it's on there, the board is a sealed box — you can't ask it what it's doing.
Frothy flips that around. The board itself understands the language, so you just talk to it. Type led.on: and the light comes on. Type a new version of a word and it takes effect instantly.
It feels like p5.js — but the canvas is a real circuit.
Redefine a word and every place that uses it picks up the new version on the spot. No build step, no re-upload — the device never stops to listen.
to blink with n [
repeat n [
led.toggle:; ms: 90
]
]
blink: 3…then change 90 to 30 and run again. Instantly faster.
Ask the device words and it lists everything it knows. Ask it to see any one and it hands back the source — even on a board that was never yours.
frothy> words
led.on led.off blink
frothy> see blink
to blink with pin, count, wait [ ... ]The whole device, readable, out in the open.
Name a word with to, say what it takes with, and put the steps in brackets. Drastically simpler than C, and friendly to beginners.
to pulse with pin, wait [
gpio.high: pin;
ms: wait;
gpio.low: pin
]No headers, no build flags, no datasheet to read first.
frothy> words -- ask what it knows
led.on led.off led.toggle blink
adc.read ms millis boot ...
ok
frothy> see led.toggle -- read any word's source
to led.toggle [ gpio.toggle: $led_builtin ]
ok
frothy> beat is fn [ led.toggle: ] -- teach it a new word
ok
frothy> save -- snapshot it to flash
ok
frothy> restore -- revert to the last save
oksave writes your overlay to flash; restore brings the saved one back; dangerous.wipe clears it to the bare base.to scale with percent, max [
here bounded is clamp: percent, 0, 100;
bounded * max / 100
]
scale: 80, 255to blink with pin, count, wait [
repeat count [
gpio.high: pin; ms: wait;
gpio.low: pin; ms: wait
]
]
blink: $led_builtin, 5, 200to watch.light [
here level is adc.read: $a0;
if level > 2000 [
led.on:
] else [
led.off:
]
]
watch.light:to signal [ led.blink: 2, 120 ]
to warn [ signal: ]
to signal [ led.blink: 8, 40 ]
warn:boot is fn [
on $boot_button falling debounce 30 [
led.toggle:
]
]
saveto doze [
sleep.wake-on-gpio: $boot_button, 0;
sleep.deep: 30000
]
doze:blink.rate is 200
to pulse [ led.blink: 3, blink.rate ]
save -- snapshot the overlay to flash
blink.rate is 40 -- try a faster rate, live...
restore -- ...snap back to the saved 200A word is a name with code behind it — write it with to, run it with a trailing colon. with names its arguments.
here binds a value that's local to the block, so bounded exists only inside scale. A block hands back its last line — here, the scaled number.
The hello-world of hardware — and it already ships in the base image. repeat runs the block a fixed number of times, ms: waits, $led_builtin is the onboard LED.
Arguments follow the colon, comma-separated: a pin, a count, a delay.
Read an analog pin with adc.read:, keep the reading in a local, and branch on it. if … else takes the first block when the test is true.
Sense, decide, act — the whole loop of physical computing, in seven lines.
warn calls signal by name. Redefine signal and every caller picks up the new version on the next call.
No recompile, no re-flash, nothing to restart. This is the thing Frothy is really for: changing a running device one word at a time.
on $boot_button falling debounce 30 [ … ] toggles the LED on a falling edge — a button press — with 30 ms of debounce, so one push registers once. every <ms> [ … ] does the same on a timer.
Handlers fire cooperatively, at safe points between steps — never mid-write. Register them in boot, save, and the device reacts on its own from power-on.
Arm a wake source, then power the core down. sleep.wake-on-gpio: says "come back when this pin goes low"; sleep.deep: sleeps up to that many milliseconds.
The thing a battery project lives or dies on — one line each.
Your top-level names — blink.rate and pulse here — sit in an overlay on top of the base image the board shipped with. save writes that overlay to flash, so it survives a power cycle.
restore snaps the live overlay back to the last save — a cheap undo for a session that wandered. dangerous.wipe erases the saved overlay entirely, back to the bare base. Save a state worth keeping; restore to recover; wipe to start clean.
Frothy is early, but the basic loop is already useful: flash a board, keep it powered, ask pins what they read, and redefine small words until the circuit starts making sense.
The hard part of a physical build is the messy middle — the wiring is half-right, the timing is off, and you're not sure what the sensor even returns. Frothy is good there. Leave the board powered and change it a word at a time.
save what works, and keep goingThere's no package to install yet — you build the frothy CLI from source. It needs Go, and for an ESP32 a one-time toolchain fetch that takes the better part of twenty minutes. After that, flashing and connecting are quick.
$ git clone https://github.com/nikokozak/frothyrewrite $ cd frothyrewrite $ make cli # builds the `frothy` CLI $ frothy bootstrap # one-time: fetch the ESP-IDF toolchain $ frothy flash esp32_devkit_v1 --port /dev/cu.usbserial-0001 $ frothy connect --port /dev/cu.usbserial-0001
Search the docs
Guide, tutorials, reference, install, hardware, and deep content search.
Start typing to search the docs.