ESP32

Learn how BoxLang can be deployed to ESP32 devices.

Building for ESP32

MatchBox supports building and flashing BoxLang scripts directly to ESP32 microcontrollers. This is achieved by cross-compiling a specialized MatchBox runner for the Xtensa or RISC-V architectures and deploying your compiled bytecode to a dedicated flash partition.

Prerequisites

To build for ESP32, you must have the following installed on your development machine:

1. Rust ESP32 Toolchain: Install using espup:

   cargo install espup
   espup install
   # Follow instructions to source the export-esp.sh script

2. espflash: For flashing the binary to the device. Version 3.3.0+ is required.

3. ESP-IDF Prerequisites: Standard C build tools, Python, and CMake (required for the esp-idf-sys crate).

WSL Users (USB Access)

If you are using Windows Subsystem for Linux (WSL), you must "attach" your USB device to the Linux instance using usbipd-win.

From a Windows Administrator PowerShell:

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

Building and Flashing

Use the --target esp32 flag to trigger an ESP32 build. You should always specify your chip type via --chip (e.g., esp32, esp32s3, esp32c3).

1. Initial Setup (Full Flash)

The first time you flash a device, you must perform a "Full Flash." This installs the MatchBox Runner firmware and the custom partition table required for BoxLang.

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

Note: --full-flash implicitly triggers the flash process.

2. Fast Deployment (Default)

Once the Runner is on the device, you only need to update the BoxLang bytecode. This takes ~1 second and does not require re-flashing the firmware.

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

Watch Mode (Live Coding)

MatchBox features a built-in watch mode that provides a "Hot Reload" experience for physical hardware.

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

What Watch Mode does:

1. Initial Flash: Performs a fast-deploy of your script.

2. Integrated Monitor: Automatically opens espflash monitor and performs a hardware reset.

3. Auto-Update: Watches your directory for .bxs changes. Upon save, it kills the monitor, flashes the new bytecode in 1s, and restarts the monitor/reset cycle.

How it Works

1. Compilation: Your .bxs script is compiled into .bxb bytecode using the Postcard serialization format, ensuring 64-bit to 32-bit architecture compatibility.

2. Partitioning: MatchBox uses a custom partition table (partitions.csv) that reserves a 1MB storage partition at offset 0x110000 for bytecode.

3. Runtime: The ESP32 Runner starts a dedicated FreeRTOS task with a 48KB stack to host the MatchBox VM.

4. Environment Awareness: The BoxLang server scope is automatically populated with hardware information (e.g., server.os.arch will return xtensa or riscv).

Memory and Performance

• SRAM: ESP32 devices have limited memory (usually 520KB). The VM is configured with a large stack to prevent overflows, but you should still be mindful of creating massive arrays.

• Flash: The VM and runtime add roughly 800KB - 1.2MB to the firmware size. The bytecode is stored separately in the 1MB storage partition.

Native Hardware Access

Standard BoxLang BIFs (Built-in Functions) like println are mapped to the ESP32's serial console. To access hardware pins (GPIO, I2C, WiFi), you can use Native Fusion or use a BoxLang module that provides hardware wrappers.