# ESP32

## 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`:

   ```bash
   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**:

```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.

```bash
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.

```bash
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.

```bash
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://boxlang.ortusbooks.com/getting-started/running-boxlang/esp32.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.