GPIO & ADC

Configure pins, read and write digital levels, watch edges, and sample analog inputs.

GPIO is the shortest path from source to a physical result. Start on the built-in LED and boot button, then move to circuit-specific pins.

Blink And Read A Button

gpio.output: $led_builtin
gpio.input: $boot_button

to show-button [
  if (gpio.read: $boot_button) = 0 [
    led.on:
  ] else [
    led.off:
  ]
]

show-button:

The common ESP32 boot button is active-low: pressed reads as 0. Other inputs depend on the circuit, pull resistors, and selected pin.

Digital Word Table

Word	Result	Use
`gpio.mode`	`nil`	Set mode `0` for input or `1` for output
`gpio.write`	`nil`	Write level `0` or `1`
`pin`	`nil`	Alias for `gpio.write`
`gpio.read`	`Int`	Read digital level
`gpio.input`	`nil`	Configure input mode
`gpio.output`	`nil`	Configure output mode
`gpio.high`	`nil`	Write level `1`
`gpio.low`	`nil`	Write level `0`
`gpio.toggle`	`nil`	Read and invert a level

The gpio.* helpers expose logical levels. Board LED helpers additionally use $led_active_level, so led.on: works on both active-high and active-low LEDs.

React To Edges

to arm-button [
  on $boot_button falling debounce 25 [
    led.toggle:
  ]
]

arm-button:

Use rising, falling, or changes. Cancel every GPIO registration for the pin with cancel $boot_button. See Events for identity, output, and capacity rules.

Analog Input

raw is adc.read: $a0
percent is adc.percent: $a0
above-half? is adc.above?: $a0, 2047

Word	Result	Use
`adc.read`	`Int`	Read the platform ADC value
`adc.above?`	`Bool`	Compare one reading with a threshold
`adc.percent`	`Int`	Map the converter’s full range to 0–100

Analog reads accept only pins on the chip’s first ADC unit; any other pin fails with bad value. A second unit, where the chip has one, is not exposed when it shares hardware with the radio — reads there fail or return noise whenever the radio is on. Which pins carry analog input depends on your board (on the classic ESP32 DevKit V1, for example, GPIO 32–39) — the board’s $a0 constant always names a safe analog pin.

An unconnected analog pin floats. A stable application circuit needs the appropriate source impedance, reference, filtering, and calibration; the language helper cannot replace those physical details.