Use this page when you know the word you want and need its signature, one-line purpose, and a small example.
Syntax and semantic rules live in Language . Hardware pages link back here for canonical word entries.
Language Forms
Creates or rebinds a top-level slot.
Example
counter is 0
counter is counter + 1
to (language) to name with params [ body ]
Binds a top-level word to a Code value.
Example
to double with n [ n * 2 ]
double: 21
fn (language) fn with params [ body ]
Creates an anonymous Code value.
Example
adder is fn with x, y [ x + y ]
adder: 20, 22
here (language) here name is expr
Declares a lexical local in the current block.
Example
to demo [ here speed is 10; speed ]
set (language) set place to expr
Mutates an existing name, cells element, or record field.
Example
set counter to counter + 1
set readings[0] to 11
set point -> x to 30
if (language) if cond [ then ] else [ fallback ]
Chooses between blocks and yields the chosen block’s value.
Example
if n < 2 [ n ] else [ fib: n - 1 + fib: n - 2 ]
when (language) when cond [ body ]
Runs a one-sided conditional block and yields nil when the condition is false.
Example
when adc.percent: $a0 > 50 [ led.on: ]
unless (language) unless cond [ body ]
Runs a one-sided conditional block when the condition is false.
Example
unless ready [ led.off: ]
while (language) while cond [ body ]
Repeats a block while the condition stays truthy.
Example
while x > 0 [ set x to x - 1 ]
repeat (language) repeat count as i [ body ]
Repeats a block a fixed number of times, optionally binding a zero-based index.
Example
repeat 10 as i [ set total to total + i ]
forever (language) forever [ body ]
Repeats a block until interrupted or until the body errors.
Example
forever [ led.toggle:; ms: 100 ]
cells (language) cells(length) -> Cells
Creates fixed-size mutable indexed storage.
Example
readings is cells(3)
set readings[0] to 11
record (language) record Name [ fields ]
Declares a top-level record shape and constructor.
Example
record pt [ x, y ]
p is pt: 3, 4
attempt (language) attempt [ body ] rescue [ fallback ]
Runs fallback code after a catchable runtime error and yields the fallback value.
Example
1 + attempt [ 2 / 0 ] rescue [ 9 ]
error.code (language) error.code -> Int
Reads the caught runtime error code inside a rescue block.
Example
attempt [ 2 / 0 ] rescue [ error.code ]
error.name (language) error.name -> Text
Reads the caught runtime error name inside a rescue block.
Example
attempt [ missing: ] rescue [ error.name ]
on (events) on source edge [ body ]
Registers a GPIO or Wi-Fi event body from inside a definition.
Example
to arm-button [ on $boot_button falling [ led.toggle: ] ]
every (events) every millis [ body ]
Registers a repeating timer event from inside a definition.
Example
to start-ticking [ every 1000 [ print: "tick" ] ]
after (events) after millis [ body ]
Registers a one-shot timer event from inside a definition.
Example
to once [ after 500 [ led.off: ] ]
Cancels a GPIO, timer, or Wi-Fi event by its event source identity.
Example
cancel every 1000
cancel $boot_button
Values And Image
Represents no value and takes the false branch.
Example
if nil [ 1 ] else [ 2 ]
Represents boolean truth.
Example
if true [ led.on: ]
Represents boolean falsehood and takes the false branch.
Example
if false [ 1 ] else [ 2 ]
Runs after restore when the top-level slot holds Code.
Example
boot is fn [ led.on: ]
save
Base-image literal for the integer 1.
Example
one + 41
save (persistence) save -> nil
Writes the current overlay image to persistent storage.
Example
save
restore (persistence) restore -> nil
Replaces the live overlay with the saved overlay.
Example
restore
dangerous.wipe (persistence) dangerous.wipe -> nil
Clears the live and saved overlay and returns to the base image.
Example
dangerous.wipe
Lists visible names at the prompt.
Example
words
Renders the source form for a binding.
Example
see boot
Reports session and runtime status at the prompt.
Example
status
print (io) (Text|Bytes) -> nil
Writes raw text or bytes to the console output.
Example
print: "hello"
GPIO, ADC, And LED
Names the board’s built-in LED pin.
Example
gpio.output: $led_builtin
Names the board’s default ADC input pin.
Example
adc.read: $a0
Names the board boot button pin.
Example
gpio.read: $boot_button
gpio.mode (gpio) (pin, mode) -> nil
Configures a GPIO pin direction with 1 for output and 0 for input.
Example
gpio.mode: $led_builtin, 1
gpio.write (gpio) (pin, level) -> nil
Writes a GPIO output level.
Example
gpio.write: $led_builtin, 1
Reads a GPIO input level.
Example
gpio.read: $boot_button
gpio.high (gpio helper) (pin) -> nil
Writes level 1 to a GPIO pin.
Example
gpio.high: $led_builtin
gpio.low (gpio helper) (pin) -> nil
Writes level 0 to a GPIO pin.
Example
gpio.low: $led_builtin
gpio.toggle (gpio helper) (pin) -> nil
Writes the opposite of the pin’s current GPIO level.
Example
gpio.toggle: $led_builtin
gpio.output (gpio helper) (pin) -> nil
Configures a GPIO pin as output.
Example
gpio.output: $led_builtin
gpio.input (gpio helper) (pin) -> nil
Configures a GPIO pin as input.
Example
gpio.input: $boot_button
Turns on the board’s default LED.
Example
led.on:
led.off (led helper) () -> nil
Turns off the board’s default LED.
Example
led.off:
led.toggle (led helper) () -> nil
Toggles the board’s default LED.
Example
led.toggle:
blink (led helper) (pin, count, wait) -> nil
Blinks a pin by alternating high, sleep, low, sleep.
Example
blink: $led_builtin, 3, 75
led.blink (led helper) (count, wait) -> nil
Blinks the board’s default LED.
Example
led.blink: 3, 75
Reads a raw ADC value from a pin.
Example
adc.read: $a0
adc.above (adc) (pin, threshold) -> Bool
Returns true when a raw ADC reading is above a threshold.
Example
adc.above: $a0, 2000
adc.percent (adc helper) (pin) -> Int
Maps a raw 0 to 4095 ADC reading to 0 to 100.
Example
adc.percent: $a0
Timing, Math, And Random
Sleeps for a nonnegative number of milliseconds while still polling interrupts.
Example
ms: 75
Reads milliseconds since boot, wrapped to the tagged integer range.
Example
millis:
Reads microseconds since boot, wrapped to the tagged integer range.
Example
micros:
Returns the absolute value of an integer.
Example
abs: -5
Returns the smaller of two integers.
Example
min: 3, 9
Returns the larger of two integers.
Example
max: 3, 9
clamp (math) (x, lo, hi) -> Int
Clamps an integer to an inclusive range.
Example
clamp: 120, 0, 100
map (math) (x, in_lo, in_hi, out_lo, out_hi) -> Int
Linearly maps an integer from one range to another.
Example
map: 2048, 0, 4095, 0, 100
Returns a modulo b with the runtime’s integer semantics.
Example
mod: 37, 10
wrap (math helper) (value, size) -> Int
Returns 0 for nonpositive sizes, otherwise mod: value, size.
Example
wrap: 37, 10
Clamps an integer to -1, 0, or 1.
Example
sign: -20
random.next (random) () -> Int
Returns the next pseudo-random nonnegative integer.
Example
random.next:
random.below (random) (limit) -> Int
Returns a pseudo-random integer in [0, limit).
Example
random.below: 10
random.seed (random) (seed) -> nil
Seeds the pseudo-random generator.
Example
random.seed: 123
random.chance? (random helper) (numer, denom) -> Bool
Returns true when a random draw falls inside a numerator over denominator chance.
Example
random.chance?: 1, 4
random.percent? (random helper) (percent) -> Bool
Returns true for a percentage chance from 0 to 100.
Example
random.percent?: 25
UART, I2C, And PWM
$baud_9600 (uart constant) Int
Names the UART baud-rate code for 9600 baud.
Example
uart.open: 1, $baud_9600
$baud_19200 (uart constant) Int
Names the UART baud-rate code for 19200 baud.
Example
uart.open: 1, $baud_19200
$baud_38400 (uart constant) Int
Names the UART baud-rate code for 38400 baud.
Example
uart.open: 1, $baud_38400
$baud_57600 (uart constant) Int
Names the UART baud-rate code for 57600 baud.
Example
uart.open: 1, $baud_57600
$baud_115200 (uart constant) Int
Names the UART baud-rate code for 115200 baud.
Example
uart.open: 1, $baud_115200
uart.open (uart) (port, baud) -> Handle
Opens an auxiliary UART with platform default pins.
Example
aux is uart.open: 1, $baud_115200
uart.open-on (uart) (port, tx, rx, baud) -> Handle
Opens an auxiliary UART on caller-picked TX and RX pins.
Example
aux is uart.open-on: 1, 17, 16, $baud_115200
uart.write-byte (uart) (handle, byte) -> nil
Writes one byte to an auxiliary UART.
Example
uart.write-byte: aux, 65
uart.read-byte (uart) (handle) -> Int
Reads one byte from an auxiliary UART, or -1 when none is ready.
Example
uart.read-byte: aux
uart.available (uart) (handle) -> Int
Returns the count of bytes waiting on an auxiliary UART.
Example
uart.available: aux
uart.close (uart) (handle) -> nil
Closes an auxiliary UART and releases its handle.
Example
uart.close: aux
i2c.open (i2c) (port, sda, scl, freq) -> Handle
Opens an I2C bus on a port with selected pins and frequency.
Example
bus is i2c.open: 0, $sda, $scl, 400000
i2c.write (i2c) (bus, addr, bytes) -> nil
Writes bytes to a 7-bit I2C address.
Example
i2c.write: bus, 104, "AT"
i2c.read (i2c) (bus, addr, count) -> Bytes
Reads count bytes from a 7-bit I2C address.
Example
i2c.read: bus, 104, 2
Closes an I2C bus and releases its handle.
Example
i2c.close: bus
i2c.read-reg (i2c) (bus, addr, reg) -> Int
Reads one byte from a register at a 7-bit I2C address.
Example
i2c.read-reg: bus, 104, 117
i2c.read-reg16 (i2c) (bus, addr, reg) -> Int
Reads a big-endian 16-bit register at a 7-bit I2C address.
Example
i2c.read-reg16: bus, 104, 117
i2c.write-reg (i2c) (bus, addr, reg, value) -> nil
Writes one byte to a register at a 7-bit I2C address.
Example
i2c.write-reg: bus, 104, 107, 0
i2c.write-reg16 (i2c) (bus, addr, reg, value) -> nil
Writes a big-endian 16-bit register at a 7-bit I2C address.
Example
i2c.write-reg16: bus, 104, 107, 0
pwm.open (pwm) (pin, freq) -> Handle
Opens a PWM channel on a pin at a frequency in Hz.
Example
led is pwm.open: $led_builtin, 1000
pwm.write (pwm) (handle, duty) -> nil
Sets PWM duty in the inclusive range 0 to 10000.
Example
pwm.write: led, 512
pwm.close (pwm) (handle) -> nil
Closes a PWM channel and releases its handle.
Example
pwm.close: led
Text, Bytes, Network, And Power
text.length (text) (text) -> Int
Returns the byte length of a text value.
Example
text.length: "ready"
text.equals? (text) (a, b) -> Bool
Returns true when two text values have equal bytes.
Example
text.equals?: "ok", "ok"
text.concat (text) (a, b) -> Text
Joins two text values into a new text value.
Example
text.concat: "he", "llo"
text.at (text) (text, index) -> Int
Returns the byte at an index in a text value.
Example
text.at: "A", 0
text.from-int (text) (n) -> Text
Renders an integer as decimal text.
Example
text.from-int: 42
bytes.from-text (bytes) (text) -> Bytes
Copies a text value into a transient bytes buffer.
Example
buf is bytes.from-text: "AT"
bytes.from-byte (bytes) (byte) -> Bytes
Creates a one-byte buffer from a 0 to 255 integer.
Example
bytes.from-byte: 65
bytes.from-int (bytes) (n) -> Bytes
Converts an integer to ASCII decimal bytes.
Example
bytes.from-int: 42
bytes.length (bytes) (buf) -> Int
Returns the byte count of a bytes buffer.
Example
bytes.length: buf
bytes.at (bytes) (buf, index) -> Int
Returns the byte at an index as a 0 to 255 integer.
Example
bytes.at: buf, 0
bytes.equals? (bytes) (a, b) -> Bool
Returns true when two bytes buffers have equal contents.
Example
bytes.equals?: buf, bytes.from-text: "AT"
bytes.concat (bytes) (a, b) -> Bytes
Concatenates two bytes buffers into a new buffer.
Example
bytes.concat: bytes.from-text: "A", bytes.from-text: "T"
text.pack (text) (buf) -> Text
Copies a bytes buffer into persistent text storage.
Example
text.pack: buf
wifi.save (network) (ssid, pass) -> nil
Stores Wi-Fi credentials in the Frothy Wi-Fi NVS namespace.
Example
wifi.save: "ssid", "password"
wifi.connect (network) () -> nil
Connects Wi-Fi using stored credentials.
Example
wifi.connect:
wifi.ready? (network) () -> Bool
Returns true when Wi-Fi is connected.
Example
wifi.ready?:
http.get (network) (url) -> Bytes
Fetches a URL and returns the response body up to the HTTP body cap.
Example
http.get: "http://example.com/"
tcp.open (network) (host, port) -> Handle
Opens a TCP connection to a host and port.
Example
sock is tcp.open: "example.com", 80
tcp.read (network) (sock, count) -> Bytes
Reads up to count bytes from a TCP socket.
Example
tcp.read: sock, 64
tcp.write (network) (sock, bytes) -> nil
Sends the raw bytes of a text or bytes value to a TCP socket.
Example
tcp.write: sock, "ping"
tcp.close (network) (sock) -> nil
Closes a TCP socket and releases its handle.
Example
tcp.close: sock
tcp.bytes-ready? (network) (sock) -> Int
Returns the bytes available for immediate tcp.read.
Example
tcp.bytes-ready?: sock
watchdog.arm (power) (timeout_ms) -> nil
Arms the watchdog with a timeout in milliseconds.
Example
watchdog.arm: 5000
watchdog.feed (power) () -> nil
Feeds an already armed watchdog.
Example
watchdog.feed:
sleep.deep (power) (ms) -> nil
Enters deep sleep for a duration; the chip cold-boots on wake.
Example
sleep.deep: 1000
sleep.wake-on-gpio (power) (pin, level) -> nil
Configures GPIO wake for the next deep sleep.
Example
sleep.wake-on-gpio: $boot_button, 0
Pad And Internal Event Support
Clears the transient pad buffer.
Example
pad.reset:
pad.emit-byte (pad) (byte) -> nil
Appends one byte to the transient pad buffer.
Example
pad.emit-byte: 65
Returns the transient pad buffer length.
Example
pad.len:
Writes the transient pad buffer to console output.
Example
pad.type:
pad.peek-byte (pad) (index) -> Int
Reads one byte from the transient pad buffer.
Example
pad.peek-byte: 0
Packs the transient pad bytes into a text value.
Example
pad.pack:
frothy.event-register (internal) (kind, source, debounce, body) -> nil
Internal native used by compiled event registration forms.
Example
to start-ticking [ every 1000 [ print: "tick" ] ]
frothy.event-cancel (internal) (kind, source) -> nil
Internal native used by compiled cancel forms.
Example
cancel every 1000