Building for ESP32

matchbox --target esp32 cross-compiles the MatchBox ESP32 runner, flashes it, and writes your application to a flash partition. The standard runner is a small web application server: it starts Wi-Fi, listens for HTTP, and runs BoxLang files in response to requests.

What the runner executes

The runner executes only two things: the Application class (its onApplicationStart method) and the route files in the embedded app. It has no loader for a standalone script, so a file that only calls println and sleep is compiled but the device does not run it.

Routes come from an app/ directory next to your entry script, not from web.server() calls. The entry script is still required on the command line. It is compiled and checked, but the routes are built from the files in app/.

my-device/
├── main.bxs                  entry script passed to matchbox
├── Application.bx            optional, runs onApplicationStart at boot
├── box.json                  optional build settings
└── app/
    ├── index.bxm             GET /
    ├── status.get.bxs        GET /status
    ├── print.post.bxs        POST /print
    └── printer/
        └── [id].bxm          GET /printer/:id

Route rules:

• Only .bxm (template) and .bxs (script) files under app/ become routes.
• index maps to the directory path. Other names map to a path segment, so app/about.bxm is /about.
• A method suffix before the extension sets the method: get, post, put, patch, delete, head or options. The default is GET.
• [name] in a file or directory name captures that segment as name.
• A route matches when the segment count is equal and each literal segment is equal. If several routes match, the first one in alphabetical path order wins.
• Application.bx is found next to the entry script or in src/main/bx/.

Each request runs the route file in a shared VM and responds as follows:

Inside a route the scopes are strings only:

Not available: sessions, cookies, static files, event.setView(), app.listen(), webhooks and WebSockets. Compile-time checks on the entry script reject app.listen(), event.setView() / event.renderTemplate(), app.middleware.buildStaticFiles(), webhook helpers, cookie helpers and session helpers.

Prerequisites

You need these on the development machine:

1. Rust ESP32 toolchain, installed with espup:

   cargo install espup
   espup install
   

2. ESP-IDF, a real checkout activated in your shell. MatchBox builds with ESP_IDF_TOOLS_INSTALL_DIR=fromenv so it uses the tools of the activated environment instead of downloading its own.
3. espflash for flashing.
4. ldproxy, the linker wrapper used by the runner:

   cargo install ldproxy
   

5. A C toolchain, Python, CMake and Ninja, as required by ESP-IDF.
6. A MatchBox source checkout. A build with --esp32-web compiles the runner from crates/matchbox-esp32-runner in the source tree the CLI was built from.

Activate ESP-IDF and switch the Rust toolchain in the shell you run MatchBox from:

source /path/to/esp-idf/export.sh
export RUSTUP_TOOLCHAIN=esp

Do not layer other ESP export scripts on top of that shell. Without these variables the runner build fails.

Check your setup

matchbox esp32-doctor

The command prints [ok], [warning] or [fail] for each of: IDF_PATH, idf.py, RUSTUP_TOOLCHAIN, cargo, cmake, ninja, ldproxy, espflash, LIBCLANG_PATH, ESP_IDF_ESPUP_CLANG_SYMLINK, the bundled esp32, esp32s3 and esp32c3 stubs, a .cargo/config.toml in the current directory that forces an ESP target, and serial devices under /dev. It ends with a summary line and exits normally; read the [fail] lines.

WSL users

Attach the USB device to the Linux instance with usbipd-win, from a Windows Administrator PowerShell:

usbipd list
usbipd attach --busid <BUSID> --auto-attach

Build and flash

matchbox main.bxs --target esp32 --esp32-web --chip esp32s3 --full-flash

A --esp32-web build always compiles the runner locally with cargo build --release --no-default-features --features embedded-web (adding psram when enabled). The route table is compiled into that firmware, and the runner falls back to it when the storage partition holds no valid app. Use --full-flash for the first flash, after changing chip, box.json or MatchBox, and whenever a fast deploy does not change what the device serves.

A fast deploy compiles the routes, then writes a 4-byte little-endian length followed by the serialized route table with espflash write-bin and resets the board. Run it from the shell where espflash can open the serial port.

Serial port permissions

On Linux the build can succeed while flashing fails because your user cannot open the serial device (for example /dev/ttyACM0):

groups
sudo usermod -aG dialout $USER
# or the serial group of your distribution, such as uucp

Log out and back in before retrying. Do not rerun the whole matchbox ... --full-flash command with sudo; that repeats the build as root. Build as your user, then flash the ELF with espflash (see Manual flash).

Watch mode

matchbox main.bxs --target esp32 --esp32-web --chip esp32s3 --watch

1. The first deploy is a full flash.
2. The CLI detects the serial port with espflash board-info, falling back to /dev/ttyACM0, /dev/ttyUSB0, /dev/ttyACM1 or /dev/ttyUSB1, and prints the device output by reading the port with stty and cat.
3. When the entry script file is saved, it stops the reader, recompiles, rediscovers app/, fast-deploys (three attempts) and restarts the reader.

Only saves of the entry script itself trigger a redeploy. Saving a file under app/ does not; touch the entry script afterwards. Watch mode works on Unix-style systems that have stty and cat.

Partitions

The project partition table (crates/matchbox-esp32-runner/partitions.csv, passed to espflash) assumes 8 MB of flash (CONFIG_ESPTOOLPY_FLASHSIZE_8MB).

The runner finds the storage partition by subtype, memory-maps it, and reads the app from it. Core dumps are written to flash (CONFIG_ESP_COREDUMP_ENABLE_TO_FLASH).

Runner internals

• The runner starts a FreeRTOS task named matchbox-runner with a 24 KiB stack (24576 bytes) on core 0. A project with a native/ directory builds a Native Fusion runner instead, whose VM task has a 48 KiB stack.
• The HTTP server task stack is 6144 bytes. The background fiber thread has 8192 bytes.
• Request handling takes a garbage collection before and after each route.
• Standard BIFs such as println write to the serial console.

HTTP server limits

Built-in endpoints

These paths are served by the runner and cannot be used by routes:

Configuration

Wi-Fi and port

The runner's own Wi-Fi connection and its HTTP port are fixed when the firmware is built. Provide them in one of two ways:

box.json in the directory where you run matchbox:

{
  "esp32": {
    "board": "xiao-esp32s3-sense",
    "psram": true,
    "webPort": 80,
    "wifi": {
      "ssid": "my-network",
      "password": "my-password",
      "hostname": "my-device"
    }
  }
}

Environment variables set before running matchbox:

These values are read when the runner is compiled, so they apply to --full-flash builds, not to a fast deploy. box.json values are exported by the CLI for that build. Keep real credentials out of version control.

Alternatively connect from BoxLang in Application.bx. onApplicationStart runs before the runner opens its own connection, and a connection made there is reused:

class {
    function onApplicationStart() {
        esp32WifiStation( "my-network", "my-password", "my-device" );
    }
}

application.esp32.wifi.ssid, .password, .hostname and application.esp32.web.port are filled in before onApplicationStart and can be read in routes. Changing them does not reconnect Wi-Fi or move the HTTP port: the runner only prints them to the boot log.

Features compiled into the runner

The CLI builds the web runner with --no-default-features --features embedded-web, so the BLE and printer functions below are in the firmware only when the runner is built with the platform-bluetooth feature, for example by running cargo build in the runner crate yourself.

ESP32 functions

Wi-Fi

USB HID

These functions make the board act as a USB keyboard and mouse through the ESP-IDF TinyUSB driver. Calls that need the device install the driver first with the product name MatchBox HID; call esp32RegisterAsHID() first to choose another name. Commands go through a queue of eight, and each function returns true once the command is queued. An error is raised if the driver cannot be installed or the host has not mounted the device.

Each name also exists in the spellings esp32UsbMouseMove and esp32usbmousemove.

Camera

The camera functions are compiled in only for the esp32s3 chip, and use the pin presets of the XIAO ESP32-S3 Sense.

photo is the struct returned by esp32CameraCapture() or its numeric id.

BLE printer

Available only in a runner built with platform-bluetooth (see above). The functions send TSPL commands over a BLE characteristic; the default characteristic is 00002af1-0000-1000-8000-00805f9b34fb.

handle is the connection struct or its handleId.

Troubleshooting

Missing ldproxy

If the runner build fails with linker ldproxy not found:

cargo install ldproxy

Stale build artifacts

After changing ESP-IDF version, chip or shell environment, remove the runner build output and retry:

rm -rf crates/matchbox-esp32-runner/target
rm -rf target/esp32_stubs

Manual flash

If the ELF builds but the CLI cannot open the serial device, flash it with espflash:

espflash flash \
  --chip esp32s3 \
  --port /dev/ttyACM0 \
  --partition-table crates/matchbox-esp32-runner/partitions.csv \
  main.elf