BoxLang on ESP32

BoxLang is the AI-native software productivity platform for building, modernizing and running applications, with developers and AI agents working together.

Overview

MatchBox can compile and deploy BoxLang scripts directly to ESP32 microcontrollers using --target esp32. BoxLang runs on FreeRTOS with a custom task stack, and bytecode is stored in a dedicated flash partition. Full firmware flashing is only needed on first setup; subsequent deploys update only the bytecode (~1 second).

Prerequisites

# Rust ESP32 toolchain
cargo install espup
espup install

# Flashing and linking
cargo install espflash   # 3.3.0 or newer
cargo install ldproxy

# Activate a real ESP-IDF checkout (needs C build tools, Python, CMake, Ninja)
source /path/to/esp-idf/export.sh
export RUSTUP_TOOLCHAIN=esp

Run MatchBox from that same shell. Run matchbox esp32-doctor to check the prerequisites and print fixes. On WSL, attach the USB device with usbipd-win first.

First Flash (Full Firmware)

The first deploy installs the BoxLang firmware onto the device:

matchbox app.bxs --target esp32 --chip esp32s3 --full-flash

• --full-flash installs the full firmware (bootloader, partition table, and ByteCode VM)
• Only needed on first use or firmware upgrades
• Takes 30–60 seconds

Fast Deploy (Bytecode Only)

After the firmware is installed, subsequent deploys update only the bytecode partition:

matchbox app.bxs --target esp32 --chip esp32s3 --flash

• Updates only the storage partition at 0x110000
• Takes ~1 second
• No firmware reinstall needed

Watch Mode (Auto-Recompile + Reflash)

Use --watch for rapid iteration during development:

matchbox app.bxs --target esp32 --chip esp32s3 --flash --watch

• Watches .bxs files for changes
• Automatically recompiles and reflashes on save
• Starts espflash monitor to show serial output

Supported Chips

FreeRTOS Task Constraints

BoxLang runs as a FreeRTOS task with the following constraints:

Keep your BoxLang scripts lean — avoid deep call stacks and large in-memory data structures.

Runtime Detection

Detect ESP32 environment in BoxLang code:

var arch = server.os.arch

if ( arch == "xtensa" ) {
    // ESP32-S3 (Xtensa LX7)
    println( "Running on Xtensa ESP32" )
} else if ( arch == "riscv" ) {
    // ESP32-C3 (RISC-V)
    println( "Running on RISC-V ESP32" )
} else {
    // Running on desktop (JVM BoxLang or MatchBox native)
    println( "Running on: " & arch )
}

Example Script

// hello_esp32.bxs
println( "[BoxLang] Hello from ESP32!" )
println( "[BoxLang] Current Chip Architecture: " & server.os.arch )

for ( i = 1; i <= 10; i++ ) {
    println( "[BoxLang] Loop iteration: #i#" )
    sleep( 1000 )
}

matchbox hello_esp32.bxs --target esp32 --chip esp32s3 --flash

println goes to the serial console. There are no built-in GPIO, I2C or WiFi BIFs. For hardware access use Native Fusion or a module that provides hardware wrappers.

Web apps: web.server() works as a lean subset when you add --esp32-web (routes, middleware, event.renderJson() and event.renderHtml()). app.listen(), views and templates, static file middleware, webhooks, cookies and sessions fail at compile time.

Serial Monitor

View serial output from the device:

# via espflash
espflash monitor

# Or let --watch mode handle it automatically
matchbox app.bxs --target esp32 --chip esp32s3 --flash --watch

Flash Partition Layout

0x000000  Bootloader
0x008000  Partition Table
0x010000  BoxLang Firmware (VM + Rust runtime)
0x110000  Storage Partition (BoxLang Bytecode, 1MB)

The --flash flag targets only 0x110000 — no firmware reinstall.

Development Workflow

1. Write BoxLang script (box.bxs)
2. First-time: matchbox box.bxs --target esp32 --chip esp32s3 --full-flash
3. Iterate:    matchbox box.bxs --target esp32 --chip esp32s3 --flash --watch
4. Monitor serial output in the watch console
5. Test on desktop before deploying: matchbox box.bxs (interpreted)

Checklist

• [ ] Install espup, espflash (3.3.0+) and ldproxy, activate ESP-IDF, set RUSTUP_TOOLCHAIN=esp, and run matchbox esp32-doctor
• [ ] Use --full-flash once per device to install firmware
• [ ] Use --flash (not --full-flash) for all subsequent code updates (~1 second)
• [ ] Use --watch during development for immediate recompile + redeploy cycles
• [ ] Check server.os.arch to detect "xtensa" or "riscv" at runtime
• [ ] Keep scripts within the 48 KB FreeRTOS stack limit (avoid deep recursion)
• [ ] Test logic on desktop with matchbox app.bxs before deploying to hardware