esp32: introduce ESP32 driver

docs/source/reference/package-apis/drivers/esp32.md

@@ -0,0 +1,137 @@
+# ESP32 driver
+
+`jumpstarter-driver-esp32` provides functionality for flashing, monitoring, and controlling ESP32 devices using esptool and serial communication.
+
+## Installation
+
+```{code-block} console
+:substitutions:
+$ pip3 install --extra-index-url {{index_url}} jumpstarter-driver-esp32
+```
+
+## Configuration
+
+Example configuration:
+
+```yaml
+export:
+  esp32:
+    type: jumpstarter_driver_esp32.driver.ESP32
+    config:
+      port: "/dev/ttyUSB0"
+      baudrate: 115200
+      chip: "esp32"
+      # Optional GPIO pins for hardware control
+      # reset_pin: 2
+      # boot_pin: 0
+```
+
+### Config parameters
+
+| Parameter     | Description                                                           | Type | Required | Default |
+| ------------- | --------------------------------------------------------------------- | ---- | -------- | ------- |
+| port          | The serial port to connect to the ESP32                              | str  | yes      |         |
+| baudrate      | The baudrate for serial communication                                | int  | no       | 115200  |
+| chip          | The ESP32 chip type (esp32, esp32s2, esp32s3, esp32c3, etc.)        | str  | no       | esp32   |
+| reset_pin     | GPIO pin number for hardware reset (if connected)                    | int  | no       | null    |
+| boot_pin      | GPIO pin number for boot mode control (if connected)                 | int  | no       | null    |
+| check_present | Check if the serial port exists during exporter initialization       | bool | no       | True    |
+
+## API Reference
+
+```{eval-rst}
+.. autoclass:: jumpstarter_driver_esp32.client.ESP32Client()
+    :members: chip_info, reset, erase_flash, flash_firmware, flash_firmware_file, read_flash, enter_bootloader
+```
+
+### CLI
+
+The ESP32 driver client comes with a CLI tool that can be used to interact with ESP32 devices:
+
+```
+jumpstarter ⚡ local ➤ j esp32
+Usage: j esp32 [OPTIONS] COMMAND [ARGS]...
+
+  ESP32 client
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  bootloader   Enter bootloader mode
+  chip-id      Get chip ID information
+  erase        Erase the entire flash
+  flash        Flash firmware to the device
+  info         Get device information
+  read-flash   Read flash contents
+  reset        Reset the device
+```
+
+## Examples
+
+### Getting device information
+
+```{testcode}
+:skipif: True
+info = esp32.chip_info()
+print(f"Connected to {info['chip_revision']}")
+print(f"MAC Address: {info['mac_address']}")
+print(f"Chip ID: {info['chip_id']}")
+```
+
+### Flashing firmware
+
+```{testcode}
+:skipif: True
+# Flash firmware from a local file
+result = esp32.flash_firmware_file("firmware.bin", address=0x1000)
+print(result)
+```
+
+### Reading flash contents
+
+```{testcode}
+:skipif: True
+# Read 1024 bytes from address 0x0
+data = esp32.read_flash(address=0x0, size=1024)
+print(f"Read {len(data)} bytes from flash")
+```
+
+### Device control
+
+```{testcode}
+:skipif: True
+# Reset the device
+result = esp32.reset()
+
+# Enter bootloader mode
+result = esp32.enter_bootloader()
+
+# Erase entire flash
+result = esp32.erase_flash()
+```
+
+### CLI Examples
+
+```{code-block} console
+# Get device information
+$ j esp32 info
+
+# Flash firmware to default app partition (0x10000)
+$ j esp32 flash firmware.bin
+
+# Flash firmware to specific address
+$ j esp32 flash firmware.bin --address 0x1000
+
+# Read flash contents
+$ j esp32 read-flash 0x0 1024
+
+# Save flash contents to file
+$ j esp32 read-flash 0x0 1024 --output flash_dump.bin
+
+# Reset the device
+$ j esp32 reset
+
+# Erase the entire flash
+$ j esp32 erase
+```

docs/source/reference/package-apis/drivers/index.md

@@ -73,6 +73,7 @@ Drivers for debugging and programming devices:
 * **[U-Boot](uboot.md)** (`jumpstarter-driver-uboot`) - Universal Bootloader
   interface
 * **[RideSX](ridesx.md)** (`jumpstarter-driver-ridesx`) - Flashing and power management for Qualcomm RideSX devices
+* **[ESP32](esp32.md)** (`jumpstarter-driver-esp32`) - ESP32 development board support
 
 ### Utility Drivers
 
@@ -86,6 +87,7 @@ can.md
 corellium.md
 dutlink.md
 energenie.md
+esp32.md
 flashers.md
 http.md
 http-power.md

packages/jumpstarter-all/pyproject.toml

@@ -16,6 +16,7 @@ dependencies = [
   "jumpstarter-driver-composite",
   "jumpstarter-driver-corellium",
   "jumpstarter-driver-dutlink",
+  "jumpstarter-driver-esp32",
   "jumpstarter-driver-flashers",
   "jumpstarter-driver-http",
   "jumpstarter-driver-network",

packages/jumpstarter-driver-esp32/README.md

@@ -0,0 +1,51 @@
+# ESP32 driver
+
+`jumpstarter-driver-esp32` provides functionality for flashing, monitoring, and controlling ESP32 devices using esptool and serial communication.
+
+## Installation
+
+```{code-block} console
+:substitutions:
+$ pip3 install --extra-index-url {{index_url}} jumpstarter-driver-esp32
+```
+
+## Configuration
+
+Example configuration:
+
+```yaml
+export:
+  esp32:
+    type: jumpstarter_driver_esp32.driver.ESP32
+    config:
+      port: "/dev/ttyUSB0"
+      baudrate: 115200
+      chip: "esp32"
+  serial:
+      type: jumpstarter_driver_pyserial.driver.PySerial
+      config:
+        url: "/dev/ttyUSB0"
+        baudrate: 115200
+```
+
+### Config parameters
+
+| Parameter    | Description                                                           | Type | Required | Default     |
+| ------------ | --------------------------------------------------------------------- | ---- | -------- | ----------- |
+| port         | The serial port to connect to the ESP32                              | str  | yes      |             |
+| baudrate     | The baudrate for serial communication                                | int  | no       | 115200      |
+| chip         | The ESP32 chip type (esp32, esp32s2, esp32s3, esp32c3, etc.)        | str  | no       | esp32       |
+| reset_pin    | GPIO pin number for hardware reset (if connected)                    | int  | no       | null        |
+| boot_pin     | GPIO pin number for boot mode control (if connected)                 | int  | no       | null        |
+
+## API Reference
+
+```{autoclass} jumpstarter_driver_esp32.driver.ESP32
+:members:
+```
+
+# Examples
+
+```shell
+$ j esp32 flash ESP32_GENERIC-20250911-v1.26.1.bin -a 0x1000
+```

packages/jumpstarter-driver-esp32/examples/example.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+from jumpstarter.common.utils import env
+
+
+def main():
+    with env() as client:
+        esp32 = client.esp32
+
+        info = esp32.chip_info()
+        print(f"Connected to {info['chip_revision']}")
+        print(f"MAC Address: {info['mac_address']}")
+
+
+if __name__ == "__main__":
+    main()

packages/jumpstarter-driver-esp32/examples/exporter.yaml

@@ -0,0 +1,15 @@
+apiVersion: jumpstarter.dev/v1alpha1
+kind: ExporterConfig
+metadata:
+  name: esp32
+spec:
+  export:
+    esp32:
+      type: jumpstarter_driver_esp32.driver.ESP32
+      config:
+        port: "/dev/ttyUSB0"
+        baudrate: 115200
+        chip: "esp32"
+        # Optional GPIO pins for hardware control
+        # reset_pin: 2
+        # boot_pin: 0