ESP32 & Hardware
ESP32 firmware, select-once hardware presets, display and touch, networking, storage, sensors, and runtime budgets.
The ESP32 backend emits an Arduino-ESP32 C++ sketch and builds it with arduino-cli. Use use native esp32; for GPIO, serial, math, memory, buses, interrupts, and realtime telemetry, plus ESP32-specific peripherals. Optional headers are included only when a matching call is lowered; a program without Wi-Fi calls does not include the Wi-Fi library.
Select hardware once
hardware setup installs the selected core/libraries and requires arduino-cli. build compiles without uploading. run builds, uploads, resets, and starts the board; monitoring is opt-in. Replace the port with your connected device. Artifacts live under build/firmware/.
Generic boards use --board esp32, esp32s2, esp32s3, esp32c3, or esp32c6. They have no display by default. --preset hw950 selects the measured integrated display/touch configuration. Board-specific pins/peripherals still depend on the selected chip and wiring.
Precedence is CLI overrides → hardware.toml → preset defaults. vynec hardware list lists bundled labels; hardware show prints resolved TOML. Use --hardware-set display.rotation=2 for a repeatable typed override. Changed hardware definitions trigger a clean object rebuild to prevent stale firmware. See Projects & Tooling for validation and configuration details.
Minimal serial program
Inside a configured project, run vynec run hello-esp32.vy --monitor. For standalone source, the lower-level workflow is:
Runtime and memory
The generated sketch dispatches Arduino setup() / loop() into the Vyne program. The default static arena is 64 KB, with checkpoint/rewind semantics shared with desktop. This leaves space for the original ESP32 linker layout; Wi-Fi and display drivers consume additional heap outside the Vyne arena. Float64 remains double precision on ESP32, unlike AVR's 32-bit double.
@bounded, @zeroed, @deterministic, and @realtime use the MCU runtime; contracts and telemetry have feature-gated headers. scratch uses stack space. Avoid large scratch buffers and repeatedly growing arrays without a region. Heap/sprite usage is separate from esp32.arena_used() and a region budget. Desktop device/commit/streamed policies are not an ESP32 acceleration mechanism.
Peripheral map
All names below are called as esp32.<name>(...). Consult the linked example for exact argument order and wiring; the runtime headers are the signature source.
| Area | Representative bindings | Example |
|---|---|---|
| GPIO and ADC | pin_mode, digital_write, digital_read, analog_read, analog_write, analog_reference | analog |
| DAC/capacitive touch | dac_write, dac_write_mv, touch_pin_read | runtime map |
| Serial | serial_begin, serial_println, serial_available, serial_read, serial1_begin, serial1_read | serial |
| Math/bits/memory | shared math, bit helpers, arena_used, arena_peak, heap_largest_free | math |
| I2C/SPI | i2c_begin, i2c_write, shared register/transfer helpers | I2C scan |
| Interrupts/watchdog | attach_interrupt, interrupt_count, interrupt_reset, watchdog_* | interrupts |
| NVS storage | nvs_open, nvs_set_int, nvs_get_int, float/string variants, nvs_exists, nvs_erase_key, nvs_close | NVS |
| Wi-Fi | wifi_connect, wifi_status, wifi_local_ip, wifi_rssi, wifi_scan, wifi_disconnect | Wi-Fi scan |
| Wi-Fi capture | wifi_sniff_start, wifi_sniff_sample, counter/time getters, wifi_sniff_stop | Live packet-rate dashboard |
| HTTP | http_get, http_post, http_post_json, http_status | HTTP |
| Display | display_init, display_width, display_height, display_rotation, drawing and sprite operations | display |
| Screen touch | touch_screen_init, touch_screen_pressed, touch_screen_x, touch_screen_y, touch_screen_calibrate | touch |
| IMU | imu_init, imu_ok, individual acceleration/gyro/temperature accessors, imu_read | MPU6050 |
| Power | power_deep_sleep_us, power_light_sleep_us, power_wake_timer, power_wake_pin, power_wake_cause, power_restart | power |
use native arduino; on ESP32 exposes shared names, but not EEPROM: use NVS. Interrupts are counter-based rather than arbitrary Vyne ISR callbacks. Timer reads use a 64-bit microsecond clock. ADC reference selects attenuation; PWM uses LEDC. wifi_scan() returns tab-separated strings (ssid, RSSI, channel, secure), not maps. imu_read() packs seven 9-bit fields; individual accessors retain precision.
Fixed-channel frame counters
wifi_sniff_start(channel) returns Bool and takes an Int64 channel in 1..14, further restricted by the driver's configured country. It requires Wi-Fi OFF and owns the radio until wifi_sniff_stop(); start never replaces an existing connection. Do not use ordinary Wi-Fi mode/connect/scan/HTTP operations while capture owns it. Initialization failures return false and attempt to release acquired radio resources. Stop returns Bool, disables reception/detaches the callback and turns off its radio; failed shutdown can be retried. Neither call erases credentials nor changes NVS/display configuration.
wifi_sniff_sample() atomically snapshots and clears the pending counters and returns Bool. A stopped sniffer returns false with an invalid-state error; a zero-duration interval returns false without consuming counts. On success, these allocation-free getters describe the same interval until the next successful sample (start clears them):
| Getter | Result |
|---|---|
wifi_sniff_management(), wifi_sniff_data(), wifi_sniff_control() | Int64 counts of driver-classified receive events |
wifi_sniff_elapsed_us() | Int64 actual elapsed microseconds from the ESP32 64-bit timer |
wifi_sniff_saturated() | Bool; a counter reached its UInt32 limit and additional events were not represented |
wifi_sniff_error() | Int64 ESP-IDF error code for the last lifecycle/sample operation, zero for success |
Null/MISC receive buffers, reception-error metadata and undersized frames are ignored. Packet payloads are not stored; counters include retries and driver-delivered aggregates, not unique IP packets or lossless all-channel traffic. The Wi-Fi callback does no allocation/printing/plotting or Vyne evaluation and updates counters under a short critical section. Lifecycle, sampling/getters and display calls belong to the application's single task. Divide counts by actual elapsed seconds, not a requested delay. Driver initialization uses additional heap; opt-in chart rendering reuses bounded series/band buffers. See the project README for measured hardware costs and reception limitations.
HW-950 display and touch
The measured preset uses ST7796-compatible initialization, native 240×320 RGB geometry (320×240 landscape), vertical mirror correction, GPIO21 backlight, GPIO27 panel enable, and XPT2046 touch sharing HSPI data/clock pins. This describes the tested board configuration, not every CYD variant or detected panel identity.
esp32.display_init() uses resolved rotation; display_init(0..3) overrides it explicitly. The initialized starter shows geometry/color markers and continuously polls touch. touch_screen_configured() and touch_screen_calibrated() distinguish driver configuration from saved calibration. Send C through the monitor for explicit four-corner calibration; existing NVS calibration is otherwise preserved. A missing touch configuration reports no contact.
Sprites and live charts
display_sprite_create(w,h) returns an off-screen sprite handle (up to four). Select it with display_sprite_select(handle), draw using the normal display calls, and push it with display_sprite_push. Select -1 for direct panel drawing and delete sprites when finished. A 16-bit 240×320 sprite needs about 150 KB of heap; allocate after Wi-Fi initialization and budget separately from the arena.
For a managed chart starter:
vplot supplies colorful charts, bounded live-series storage, and automatic timestamp/redraw management. The plotter project includes the HW-950 dashboard and touch examples.
Verification
Per-peripheral sketches carry their hardware requirements in comments. See runtime details and hardware acceptance.