Guide

Custom GPIO Nodes

Connect external sensors, actuators, and modules using digital, analog, I2C, SPI, and UART nodes.

Reserved pins

These GPIOs are used by onboard hardware. Do not use them for external connections.

GPIO 0BTN_OK

GPIO 35BTN_BACK

GPIO 36BTN_UP

GPIO 37BTN_DOWN

GPIO 38BTN_1

GPIO 39BTN_2

GPIO 8OLED_SDA

GPIO 9OLED_SCL

GPIO 14IR_RX

GPIO 4IR_TX

GPIO 21RF_RX

GPIO 22RF_TX

GPIO 10SD_CS

GPIO 2LED

GPIO 18BUZZER

digital_write

Digital Write

Set a GPIO pin HIGH or LOW. Use for LEDs, relays, buzzers, or any digital output.

Config

pin

GPIO pin number

e.g. 2

value

HIGH or LOW

e.g. HIGH

Notes

Do not use pins reserved for OLED, SD, IR, RF — see pin map above
For PWM dimming use pwm_output instead

Example

// Blink LED on GPIO 2
[start] boot → [digital_write pin=2 value=HIGH]
         → done → [delay 500ms]
         → done → [digital_write pin=2 value=LOW]

digital_read

Digital Read

Read a GPIO pin state. Returns high/low triggers and a boolean state value.

Config

pin

GPIO pin number

e.g. 15

mode

INPUT, INPUT_PULLUP, INPUT_PULLDOWN

e.g. INPUT_PULLUP

Example

// Read a door sensor on GPIO 15
[timer 500ms] tick → [digital_read pin=15]
  high → [show_text "Door open"]
  low  → [show_text "Door closed"]

analog_read

Analog Read

Read a 12-bit ADC value (0–4095) from a GPIO pin. Also outputs the voltage in volts.

Config

pin

ADC-capable GPIO pin

e.g. 34

samples

Averaging samples (1–64)

e.g. 4

Notes

ADC-capable pins on ESP32-S3: 1–10, 11–20
ADC accuracy is ±5% — not suitable for precision measurement

Example

// Read potentiometer → display value
[button_press] pressed → [analog_read pin=34]
  raw  → [show_value]
  voltage → [show_value]

pwm_output

PWM Output

Output a PWM signal on any GPIO. Use for LED dimming, servo control, or motor speed.

Config

pin

GPIO pin number

e.g. 2

frequency

PWM frequency in Hz

e.g. 5000

duty

Duty cycle 0–255

e.g. 128

Example

// Fade LED with encoder
[encoder] value → [pwm_output pin=2 freq=5000]

i2c_rw

I2C Read/Write

Communicate with I2C devices (sensors, displays, DACs). Uses the Wire library internally.

Config

address

I2C device address (hex)

e.g. 0x48

register

e.g. 0x00

mode

read | write | read-write

e.g. read

bytes

Number of bytes to read

e.g. 2

Notes

Default I2C pins: SDA=GPIO8, SCL=GPIO9 (OLED pins — shared bus)
Multiple I2C devices on the same bus is supported as long as addresses differ

Example

// Read temperature from ADS1115 on 0x48
[timer 1000ms] tick → [i2c_rw addr=0x48 reg=0x00 mode=read bytes=2]
  dataOut → [show_value]
  nack    → [show_text "I2C error"]

spi_rw

SPI Read/Write

Communicate with SPI devices (ADCs, flash chips, RF modules). Full-duplex transfer.

Config

csPin

Chip select GPIO pin

e.g. 5

speed

Clock speed in Hz

e.g. 1000000

mode

SPI mode 0–3

e.g. 0

Notes

Default SPI pins on ESP32-S3: MOSI=GPIO11 MISO=GPIO13 CLK=GPIO12
SD card uses SPI on CS=GPIO10 — do not conflict

Example

// Send command to SPI device
[button_press] pressed → [set_variable "0xAB"] vars
  → [spi_rw csPin=5 speed=1MHz mode=0]
  rxData → [show_value]

uart_rw

UART Read/Write

Send and receive data over UART (Serial2). Use for GPS modules, GSM modems, or any serial device.

Config

baud

Baud rate

e.g. 9600

txPin

TX GPIO pin

e.g. 17

rxPin

RX GPIO pin

e.g. 16

Notes

Uses Serial2 — Serial (USB) remains free for debugging
Data input port accepts a String value to transmit — wire set_variable or string_format to it

Example

// Read GPS NMEA sentences
[start] boot → [uart_rw baud=9600 tx=17 rx=16]
  received → [string_format] → [show_text]

encoder

Encoder

Virtual rotary encoder using the UP/DOWN navigation buttons. Tracks a value between min and max with configurable step.

Config

min

Minimum value

e.g. 0

max

Maximum value

e.g. 100

step

Increment per click

e.g. 1

Example

// Volume control 0–100
[start] boot → [encoder min=0 max=100 step=5]
  value → [show_value]
  atMax → [show_text "Max!"]
  atMin → [show_text "Min!"]

← Writing programs OTA updates →

↑