docs: expand target and framework API reference

Author: fffonion

README.md

@@ -2,11 +2,13 @@
 
 [![rustscript-embedded on crates.io](https://img.shields.io/crates/v/rustscript-embedded.svg)](https://crates.io/crates/rustscript-embedded)
 
-A directly flashable RustScript runtime for ESP32-C3. One image contains the bootloader,
-partition table, Arduino-ESP32 runtime, `pd-vm-nostd`, framework host API, and a default VMBC
-script partition.
+A portable RustScript VMBC runtime with release targets for ESP32-C3, ESP32-S31 preview hardware,
+and a native Arduino API simulator. Each ESP factory image contains its bootloader, partition table,
+platform runtime, `pd-vm-nostd`, framework host bridge, and a default VMBC program.
 
-## Flash the complete image
+## Flash complete images
+
+### ESP32-C3
 
 Download `micro-rustscript-esp32-c3.factory.bin` from the latest GitHub Release and flash it at
 offset zero:
@@ -16,7 +18,7 @@ python -m esptool --chip esp32c3 erase_flash
 python -m esptool --chip esp32c3 write_flash 0x0 micro-rustscript-esp32-c3.factory.bin
 ```
 
-The boot order is fixed:
+The ESP32-C3 boot order is fixed:
 
 1. `/rustscript/main.vmbc` on an SD card connected with CS on GPIO 7.
 2. The dedicated 64 KiB `rustscript` flash partition at `0x110000`.
@@ -26,18 +28,49 @@ An absent, unreadable, or missing SD script automatically falls through to the f
 The release factory image already contains `esp32-blinky.vmbc` in that partition.
 `RUSTSCRIPT_SD_CS` and `RUSTSCRIPT_SD_PATH` can be overridden with PlatformIO build flags.
 
+### ESP32-S31 preview
+
+Download `micro-rustscript-esp32-s31.factory.bin` and flash the merged image at offset zero:
+
+```bash
+python -m esptool --chip esp32s31 write_flash 0x0 micro-rustscript-esp32-s31.factory.bin
+```
+
+The S31 preview image currently embeds the default VMBC program into the application at build time.
+Its runtime does not yet implement the C3 SD-card lookup, replaceable flash VMBC partition, or serial
+VMBC REPL. The release also includes the S31 ELF for debugging.
+
+## Targets and source layout
+
+| PlatformIO environment | Purpose | Platform integration | Main source |
+|---|---|---|---|
+| `esp32-c3-devkitm-1` | Flashable ESP32-C3 firmware | Official PlatformIO board plus Arduino-ESP32 and selected ESP-IDF APIs | shared `firmware/` sources |
+| `esp32s31` | Flashable ESP32-S31 preview firmware | Pinned ESP-IDF master preview toolchain | `esp32s31/` CMake project |
+| `arduino` | Native host simulation of a small Arduino API subset | PlatformIO `native` plus `firmware/simulator/` | `firmware/arduino/main.cpp` |
+
+Only ESP32-S31 has a top-level target directory because current PlatformIO releases do not provide
+an ESP32-S31 board definition or framework package. Its directory supplies the ESP-IDF project
+files that PlatformIO cannot generate: `CMakeLists.txt`, `sdkconfig.defaults`, partition layout, and
+the pure ESP-IDF application entry point. ESP32-C3 can use PlatformIO's standard
+`esp32-c3-devkitm-1` board and therefore shares the normal `firmware/` project. The `arduino` target
+is a native simulator rather than separate hardware; its target-specific source already lives under
+`firmware/arduino/` and reuses the simulator compatibility layer.
+
+All three are still first-class PlatformIO and release targets. The directory shape reflects their
+different build systems, not a difference in release status.
+
 ## Framework API from RSS
 
-Hardware functions are exposed through RSS modules, keeping board ABI names private. Import only the
-capabilities a script uses:
+Hardware functions are exposed through built-in RSS modules, keeping the C host ABI private. Import
+only the capabilities a script uses:
 
 ```rust
-use framework::gpio as gpio;
-use framework::i2c as i2c;
-use framework::mcu as mcu;
-use framework::serial as serial;
-use framework::wifi as wifi;
-use framework::bluetooth as bluetooth;
+use gpio;
+use i2c;
+use mcu;
+use serial;
+use wifi;
+use bluetooth;
 
 let ok: bool = gpio::configure(8, 1);
 let written: bool = gpio::digital_write(8, true);
@@ -57,48 +90,14 @@ let address: string = wifi::local_ip();
 let ble_ready: bool = bluetooth::enable();
 ```
 
-### GPIO
-
-| Function | Result |
-|---|---|
-| `gpio::configure(pin, mode)` | `bool`; modes: input `0`, output `1`, pull-up `2`, pull-down `3`, open-drain `4` |
-| `gpio::digital_write(pin, high)` | `bool` |
-| `gpio::digital_read(pin)` | `bool` |
-| `gpio::analog_read(pin)` | ADC value as `int` |
-| `gpio::pwm_write(pin, duty, frequency, resolution_bits)` | `bool`; six channels, 1–16 bits |
-
-### I2C
-
-| Function | Result |
-|---|---|
-| `i2c::open(sda, scl, frequency)` | `bool` |
-| `i2c::close()` | `null` |
-| `i2c::transmit(address, data)` | Wire status as `int` |
-| `i2c::transmit_register(address, register, data)` | Wire status as `int` |
-| `i2c::receive(address, length)` | Up to 255 bytes |
-| `i2c::receive_register(address, register, length)` | Up to 255 bytes |
-
-### MCU and serial
-
-`mcu` exports `delay_ms`, `delay_us`, `millis`, `micros`, `cpu_frequency_mhz`, `free_heap`,
-`flash_size`, `random`, `restart`, and `deep_sleep_us`. `serial` exports `write_line`, `available`,
-and `read_bytes`.
-
-### Wi-Fi and Bluetooth LE
-
-The `wifi` API exports `connect`, `disconnect`, `is_connected`, `rssi`, and `local_ip`. `connect`
-returns whether ESP-IDF accepted the asynchronous connection request; poll `is_connected` before
-using `rssi` or `local_ip`. The `bluetooth` API exports BLE-controller lifecycle operations:
-`enable`, `disable`, and `is_enabled`. Both use ESP-IDF APIs and are registered only on supported
-ESP targets.
-
-`wifi` and `bluetooth` are independent Cargo/PlatformIO features. ESP release targets enable both
-by default through `custom_rust_features`; removing either feature also removes its ESP-IDF includes
-and RSS host exports. The host `arduino` target exports neither API.
+API coverage is target-dependent. ESP32-C3 provides GPIO, ADC, PWM, I2C, MCU, serial, Wi-Fi, and BLE
+controller functions. ESP32-S31 currently provides digital GPIO, core MCU timing/status, serial
+output, Wi-Fi, and BLE controller functions. The Arduino host target provides a small GPIO,
+`delay_ms`, and serial-output simulation subset.
 
-The private host ABI lives in `firmware/host_framework.cpp`; the public RSS modules live under
-`programs/framework/`. This keeps script-facing APIs namespaced while allowing the VM to dispatch a
-compact static function table.
+See **[Framework API reference](docs/framework-api.md)** for the complete support matrix, RSS
+signatures, argument limits, return behavior, asynchronous Wi-Fi semantics, BLE scope, and C host
+callback contract.
 
 ## Replace only the VMBC partition
 
@@ -161,15 +160,17 @@ Outputs:
 .pio/build/esp32-c3-devkitm-1/firmware.elf
 .pio/build/esp32-c3-devkitm-1/firmware.bin
 .pio/build/arduino/program
+.pio/build/esp32s31/program
 .pio/generated/esp32-blinky.vmbc
 .pio/generated/rustscript.partition.bin
 dist/micro-rustscript-esp32-c3.factory.bin
 dist/micro-rustscript-esp32-s31.factory.bin
+/mnt/TEMP/micro-rustscript-esp32s31/build/micro_rustscript_esp32s31.elf
 ```
 
-The factory image merges the ESP32 boot components, application, and default script partition. The
-release includes the factory image, ELF, VMBC, packed script partition, flash helpers, partition CSV,
-and SHA-256 checksums.
+Each ESP factory image merges its bootloader, partition table, and application. The C3 factory image
+also includes the packed default script partition. The release includes both factory images, both
+ELFs, the Arduino host executable, VMBC assets and helpers for C3, and SHA-256 checksums.
 
 The `esp32s31` target uses pinned ESP-IDF master preview support. ESP-IDF source, Python environment,
 toolchains, caches, Rust target artifacts, generated files, and build output are all kept under
@@ -179,9 +180,9 @@ The `arduino` environment links `pd-vm-nostd` through an Arduino-compatible GPIO
 and allocator bridge. It runs the bridge and compiled VMBC program on the host before a board is
 connected. A successful simulation ends with `rss:status=0`.
 
-## ESP32 image size
+## ESP32-C3 image size
 
-The ESP32 partition table uses a 1 MiB factory application slot and a 64 KiB VMBC slot. OTA data
+The ESP32-C3 partition table uses a 1 MiB factory application slot and a 64 KiB VMBC slot. OTA data
 and SPIFFS partitions are omitted because this image is flashed directly and script updates use the
 dedicated VMBC partition. With `wifi` and `bluetooth` enabled, the measured factory image is
 1,115,607 bytes, down from 2,164,183 bytes (48.45%), while retaining SD boot, the flash script,

docs/framework-api.md

@@ -0,0 +1,181 @@
+# RustScript framework API
+
+The VM calls platform functions through static host-import names such as `gpio::digital_write`.
+RSS programs import the built-in modules they use:
+
+```rust
+use gpio;
+use mcu;
+use serial;
+use wifi;
+use bluetooth;
+
+let ready: bool = gpio::configure(8, 1);
+let written: bool = gpio::digital_write(8, ready);
+mcu::delay_ms(100);
+serial::write_line("ready");
+```
+
+The compiler knows the module declarations, while each firmware target decides which imports it can
+dispatch. Calling a function that is absent on the selected target fails host dispatch. Use the
+support matrix below when writing a portable program.
+
+## Target support
+
+| Module or function | ESP32-C3 | ESP32-S31 preview | Arduino host simulator |
+|---|:---:|:---:|:---:|
+| `gpio::configure` | yes | yes | yes |
+| `gpio::digital_write` | yes | yes | yes |
+| `gpio::digital_read` | yes | yes | yes |
+| `gpio::analog_read` | yes | — | — |
+| `gpio::pwm_write` | yes | — | — |
+| all `i2c` functions | yes | — | — |
+| `mcu::delay_ms` | yes | yes | yes |
+| `mcu::millis`, `mcu::micros` | yes | yes | — |
+| `mcu::free_heap`, `mcu::random` | yes | yes | — |
+| `mcu::delay_us`, `mcu::cpu_frequency_mhz`, `mcu::flash_size` | yes | — | — |
+| `mcu::restart`, `mcu::deep_sleep_us` | yes | — | — |
+| `serial::write_line` | yes | yes | yes |
+| `serial::available`, `serial::read_bytes` | yes | — | — |
+| all `wifi` functions | feature-gated | feature-gated | — |
+| all `bluetooth` functions | feature-gated | feature-gated | — |
+
+The release ESP targets enable both `wifi` and `bluetooth`. They are independent Cargo and
+PlatformIO features. Removing one from `custom_rust_features` removes that module's host exports
+from the firmware. The Arduino host simulator never registers either module.
+
+## Return and error behavior
+
+The signatures below are RSS signatures. Argument type, arity, and range checks happen in the host
+bridge. A rejected call returns a host-dispatch error to the VM. A `bool` result reports whether the
+underlying platform operation was accepted. Calls documented as `null` are commands whose success
+is represented by normal completion.
+
+## GPIO
+
+```rust
+use gpio;
+
+gpio::configure(pin: int, mode: int) -> bool
+gpio::digital_write(pin: int, high: bool) -> bool
+gpio::digital_read(pin: int) -> bool
+gpio::analog_read(pin: int) -> int
+gpio::pwm_write(pin: int, duty: int, frequency: int, resolution_bits: int) -> bool
+```
+
+`pin` must be inside the SoC GPIO range. ESP32-C3 modes are `0` input, `1` output, `2` input
+pull-up, `3` input pull-down, and `4` open-drain output. ESP32-S31 currently accepts modes `0` and
+`1`. The simulator forwards the integer mode to its Arduino compatibility layer.
+
+ESP32-C3 PWM supports six simultaneously assigned pins. Frequency is `1..40,000,000` Hz,
+resolution is `1..16` bits, and duty must fit the selected resolution.
+
+## I2C
+
+ESP32-C3 only:
+
+```rust
+use i2c;
+
+i2c::open(sda: int, scl: int, frequency: int) -> bool
+i2c::close() -> null
+i2c::transmit(address: int, data: bytes) -> int
+i2c::transmit_register(address: int, register: int, data: bytes) -> int
+i2c::receive(address: int, length: int) -> bytes
+i2c::receive_register(address: int, register: int, length: int) -> bytes
+```
+
+Addresses must be 7-bit device addresses in `0x08..0x77`. Frequency must be
+`1,000..5,000,000` Hz. Register values are `0..255`; payloads and reads are limited to 255 bytes.
+Transmit functions return the Arduino Wire status code. A failed register-address phase returns an
+empty byte sequence.
+
+## MCU
+
+```rust
+use mcu;
+
+mcu::delay_ms(duration: int) -> null
+mcu::delay_us(duration: int) -> null
+mcu::millis() -> int
+mcu::micros() -> int
+mcu::cpu_frequency_mhz() -> int
+mcu::free_heap() -> int
+mcu::flash_size() -> int
+mcu::random() -> int
+mcu::restart() -> null
+mcu::deep_sleep_us(duration: int) -> null
+```
+
+On ESP32-C3, `delay_ms` accepts `0..60,000`, `delay_us` accepts `0..1,000,000`, and deep sleep
+accepts `1..86,400,000,000` microseconds. ESP32-S31 `delay_ms` accepts a non-negative 32-bit
+millisecond value. `millis` and `micros` are monotonic uptime counters. `restart` and
+`deep_sleep_us` do not return after the platform action succeeds.
+
+## Serial
+
+```rust
+use serial;
+
+serial::write_line(value: string) -> null
+serial::available() -> int
+serial::read_bytes(maximum: int) -> bytes
+```
+
+`write_line` appends a newline. ESP32-C3 input uses the 115200-baud primary serial port;
+`read_bytes` is non-blocking and returns at most 255 currently buffered bytes. ESP32-S31 and the
+simulator currently expose output only.
+
+## Wi-Fi
+
+Available on ESP targets when the `wifi` feature is enabled:
+
+```rust
+use wifi;
+
+wifi::connect(ssid: string, password: string) -> bool
+wifi::disconnect() -> bool
+wifi::is_connected() -> bool
+wifi::rssi() -> int
+wifi::local_ip() -> string
+```
+
+SSID length is `1..32` bytes; password length is `0..64` bytes. An empty password requests an open
+network. `connect` initializes the ESP-IDF station stack and returns after ESP-IDF accepts or rejects
+the asynchronous connection request. Poll `is_connected` before using connection-dependent data.
+`rssi` returns `-127` when no access point is available. `local_ip` returns an empty string until a
+non-zero station address exists. `disconnect` returns `false` when Wi-Fi was never initialized or
+ESP-IDF rejects the request.
+
+## Bluetooth LE controller
+
+Available on ESP targets when the `bluetooth` feature is enabled:
+
+```rust
+use bluetooth;
+
+bluetooth::enable() -> bool
+bluetooth::disable() -> bool
+bluetooth::is_enabled() -> bool
+```
+
+This API controls the ESP-IDF BLE controller lifecycle only. `enable` initializes the controller if
+needed and enables BLE mode. `disable` disables and deinitializes it. Both operations are idempotent.
+No GAP, GATT, advertising, scanning, pairing, or characteristic API is exposed yet.
+
+## C host ABI
+
+The Rust static library exports `rustscript_run_vmbc` and value types from
+`include/rustscript_embedded.h`. Platform bridges provide a callback with this logical contract:
+
+```text
+(context, import_name_bytes, arguments, result) -> status
+```
+
+A callback status of `-1` rejects the call, `0` completes a command with `null`, and `1` returns the
+value written to `result`. String and byte results reference bridge-owned storage and are consumed by
+the VM during the call. Platform implementations are located in:
+
+- `firmware/host_framework.cpp` — ESP32-C3 Arduino/ESP-IDF bridge.
+- `esp32s31/main/main.cpp` — ESP32-S31 pure ESP-IDF bridge.
+- `firmware/arduino/main.cpp` — native Arduino compatibility simulator.