Merge pull request #294 from bennyz/esp32

esp32: introduce esp32 driver

Author: mangelajo

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

@@ -0,0 +1 @@
+../../../../../packages/jumpstarter-driver-esp32/README.md

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

@@ -65,6 +65,8 @@ Drivers that handle media streams:
 
 Drivers for debugging and programming devices:
 
+* **[ESP32](esp32.md)** (`jumpstarter-driver-esp32`) - ESP32 flashing and
+  management via esptool
 * **[Flashers](flashers.md)** (`jumpstarter-driver-flashers`) - Flash memory
   programming tools
 * **[Probe-RS](probe-rs.md)** (`jumpstarter-driver-probe-rs`) - Debugging probe
@@ -91,6 +93,7 @@ can.md
 corellium.md
 dutlink.md
 energenie.md
+esp32.md
 flashers.md
 http.md
 http-power.md

python/packages/jumpstarter-driver-esp32/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+.coverage
+coverage.xml

python/packages/jumpstarter-driver-esp32/README.md

@@ -0,0 +1,129 @@
+# ESP32 driver
+
+`jumpstarter-driver-esp32` provides functionality for flashing and managing
+ESP32 devices using [esptool](https://github.com/espressif/esptool) as a
+library. It implements the `FlasherInterface` from `jumpstarter-driver-opendal`.
+
+## Installation
+
+```{code-block} console
+:substitutions:
+$ pip3 install --extra-index-url {{index_url}} jumpstarter-driver-esp32
+```
+
+## Configuration
+
+Example configuration:
+
+```yaml
+export:
+  storage:
+    type: jumpstarter_driver_esp32.driver.Esp32Flasher
+    config:
+      baudrate: 115200
+      chip: "esp32"
+    children:
+      serial:
+        ref: serial
+  serial:
+    type: jumpstarter_driver_pyserial.driver.PySerial
+    config:
+      url: "/dev/ttyUSB0"
+      baudrate: 115200
+```
+
+### Config parameters
+
+| Parameter | Description                          | Type | Required | Default       |
+| --------- | ------------------------------------ | ---- | -------- | ------------- |
+| baudrate  | Baud rate for esptool communication  | int  | no       | 115200        |
+| chip      | Target chip type                     | str  | no       | esp32         |
+
+The ESP32 driver requires a `serial` child driver (PySerial) for serial port
+access. DTR/RTS control signals and the serial port path are managed through
+the child driver. Use a `ref` proxy to share the serial driver with the
+top-level composite, enabling both `j serial start-console` and
+`j storage flash` to work.
+
+## API Reference
+
+```{eval-rst}
+.. autoclass:: jumpstarter_driver_esp32.client.Esp32FlasherClient()
+    :members: flash, dump, get_chip_info, erase, hard_reset, enter_bootloader
+```
+
+### CLI
+
+```text
+$ j storage
+Usage: j storage [OPTIONS] COMMAND [ARGS]...
+
+Commands:
+  bootloader  Enter download mode
+  chip-info   Get chip info (name, features, MAC)
+  dump        Dump flash content to file
+  erase       Erase entire flash
+  flash       Flash firmware to ESP32
+  reset       Hard reset the chip
+
+$ j serial
+Usage: j serial [OPTIONS] COMMAND [ARGS]...
+
+Commands:
+  start-console  Start serial port console
+  pipe           Pipe serial port data to stdout or file
+```
+
+## Examples
+
+### CLI usage
+
+```bash
+# Flash MicroPython firmware
+j storage flash firmware.bin --address 0x1000
+
+# Get chip info
+j storage chip-info
+
+# Enter download mode
+j storage bootloader
+
+# Erase entire flash
+j storage erase
+
+# Hard reset
+j storage reset
+
+# Open serial console
+j serial start-console
+
+# Read serial output
+j serial pipe
+```
+
+### Python API
+
+```python
+# Get chip information
+info = client.storage.get_chip_info()
+print(info["chip"])      # e.g. "ESP32-D0WD-V3 (revision v3.1)"
+print(info["features"])  # e.g. "Wi-Fi, BT, Dual Core"
+print(info["mac"])       # e.g. "5c:01:3b:68:ab:0c"
+
+# Flash firmware
+client.storage.flash("/path/to/firmware.bin", target="0x1000")
+
+# Enter download mode
+client.storage.enter_bootloader()
+
+# Erase flash
+client.storage.erase()
+
+# Hard reset
+client.storage.hard_reset()
+
+# Serial console via pexpect
+console = client.serial.open()
+console.sendline("import machine")
+console.expect(">>>")
+```

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

@@ -0,0 +1,21 @@
+apiVersion: jumpstarter.dev/v1alpha1
+kind: ExporterConfig
+metadata:
+  namespace: default
+  name: demo
+endpoint: grpc.jumpstarter.192.168.0.203.nip.io:8082
+token: "<token>"
+export:
+  storage:
+    type: jumpstarter_driver_esp32.driver.Esp32Flasher
+    config:
+      baudrate: 115200
+      chip: "esp32"
+    children:
+      serial:
+        ref: serial
+  serial:
+    type: jumpstarter_driver_pyserial.driver.PySerial
+    config:
+      url: "/dev/ttyUSB0"
+      baudrate: 115200

python/packages/jumpstarter-driver-esp32/jumpstarter_driver_esp32/__init__.py

@@ -0,0 +1,69 @@
+from dataclasses import dataclass
+
+import click
+from jumpstarter_driver_opendal.client import FlasherClient
+
+from jumpstarter.streams.encoding import Compression
+
+
+@dataclass(kw_only=True)
+class Esp32FlasherClient(FlasherClient):
+    """Client interface for ESP32 flasher driver."""
+
+    def get_chip_info(self) -> dict[str, str]:
+        """Get chip information including name, features, and MAC address."""
+        return self.call("get_chip_info")
+
+    def erase(self):
+        """Erase the entire flash memory."""
+        return self.call("erase")
+
+    def hard_reset(self):
+        """Hard reset the ESP32 chip."""
+        return self.call("hard_reset")
+
+    def enter_bootloader(self):
+        """Enter ESP32 download mode via DTR/RTS toggle."""
+        return self.call("enter_bootloader")
+
+    def cli(self):
+        base = super().cli()
+
+        # Override the inherited flash command to add --address
+        base.commands.pop("flash", None)
+
+        @base.command()
+        @click.argument("file", type=click.Path(exists=True))
+        @click.option("--address", "-a", default=None, help="Flash address (e.g. 0x1000)")
+        @click.option("--compression", type=click.Choice(Compression, case_sensitive=False))
+        def flash(file, address, compression):
+            """Flash firmware to ESP32"""
+            self.flash(file, target=address, compression=compression)
+            click.echo("done")
+
+        @base.command()
+        def chip_info():
+            """Get chip info (name, features, MAC)"""
+            info = self.get_chip_info()
+            for key, value in info.items():
+                click.echo(f"{key}: {value}")
+
+        @base.command()
+        def erase():
+            """Erase entire flash"""
+            self.erase()
+            click.echo("done")
+
+        @base.command()
+        def reset():
+            """Hard reset the chip"""
+            self.hard_reset()
+            click.echo("done")
+
+        @base.command()
+        def bootloader():
+            """Enter download mode"""
+            self.enter_bootloader()
+            click.echo("done")
+
+        return base