esp32: introduce ESP32 driver

Signed-off-by: Benny Zlotnik <bzlotnik@protonmail.com>

Author: bennyz

packages/jumpstarter-driver-esp32/README.md

@@ -0,0 +1,130 @@
+# 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"
+      reset_pin: null
+      boot_pin: null
+```
+
+### 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        |
+
+## Features
+
+- **Firmware Flashing**: Flash binary files to ESP32 using esptool library
+- **Device Control**: Reset, erase, and get device information
+- **ESP-IDF Integration**: Support for ESP-IDF project workflows
+- **Hardware Control**: Optional GPIO control for reset and boot pins
+
+## API Reference
+
+```{eval-rst}
+.. autoclass:: jumpstarter_driver_esp32.client.ESP32Client()
+    :members:
+```
+
+### CLI
+
+The ESP32 driver client comes with a CLI tool that can be used to interact with
+the ESP32 device:
+
+```
+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
+  flash-multiple Flash multiple files
+  info         Get device information
+  read-flash   Read flash contents
+  reset        Reset the device
+```
+
+### Examples
+
+**Flash firmware:**
+```{testcode}
+esp32client.flash_firmware("/path/to/firmware.bin", address=0x10000)
+```
+
+**Get device information:**
+```{testcode}
+info = esp32client.chip_info()
+print(f"Chip: {info['chip_type']}")
+print(f"MAC: {info['mac_address']}")
+```
+
+**Erase flash:**
+```{testcode}
+esp32client.erase_flash()
+```
+
+## Serial Communication
+
+For serial monitoring and communication, use the separate `jumpstarter-driver-pyserial` driver:
+
+```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
+```
+
+This separation allows you to:
+- Use `j esp32` commands for flashing and device management
+- Use `j serial` commands for serial communication and monitoring
+
+```{testsetup} *
+from jumpstarter_driver_esp32.driver import ESP32
+from jumpstarter.common.utils import serve
+
+instance = serve(ESP32(port="/dev/null"))
+esp32client = instance.__enter__()
+```
+
+```{testcleanup} *
+instance.__exit__(None, None, None)
+```

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

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

@@ -0,0 +1,170 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict
+
+import click
+from jumpstarter_driver_opendal.adapter import OpendalAdapter
+from opendal import Operator
+
+from jumpstarter.client import DriverClient
+from jumpstarter.common.exceptions import ArgumentError
+
+
+@dataclass(kw_only=True)
+class ESP32Client(DriverClient):
+    """
+    Client interface for ESP32 driver
+    """
+
+    def chip_info(self) -> Dict[str, Any]:
+        """Get ESP32 chip information"""
+        return self.call("chip_info")
+
+    def reset(self) -> str:
+        """Reset the ESP32 device"""
+        return self.call("reset_device")
+
+    def erase_flash(self) -> str:
+        """Erase the entire flash memory"""
+        self.logger.info("Erasing flash... this may take a while")
+        return self.call("erase_flash")
+
+    def flash_firmware(self, operator: Operator, path: str, address: int = 0x10000) -> str:
+        """Flash firmware to the ESP32
+
+        Args:
+            operator: OpenDAL operator for file access
+            path: Path to firmware file
+            address: Flash address (default: 0x10000 for app partition)
+        """
+        if address < 0:
+            raise ArgumentError("Flash address must be non-negative")
+
+        with OpendalAdapter(client=self, operator=operator, path=path) as handle:
+            return self.call("flash_firmware", handle, address)
+
+    def flash_firmware_file(self, filepath: str, address: int = 0x10000) -> str:
+        """Flash a local firmware file to the ESP32"""
+        absolute = Path(filepath).resolve()
+        if not absolute.exists():
+            raise ArgumentError(f"File not found: {filepath}")
+        return self.flash_firmware(operator=Operator("fs", root="/"), path=str(absolute), address=address)
+
+    def read_flash(self, address: int, size: int) -> bytes:
+        """Read flash contents from specified address
+
+        Args:
+            address: Flash address to read from
+            size: Number of bytes to read
+        """
+        if address < 0:
+            raise ArgumentError("Flash address must be non-negative")
+        if size <= 0:
+            raise ArgumentError("Size must be positive")
+
+        return self.call("read_flash", address, size)
+
+    def enter_bootloader(self) -> str:
+        """Enter bootloader mode"""
+        return self.call("enter_bootloader")
+
+    def cli(self):
+        @click.group()
+        def base():
+            """ESP32 client"""
+            pass
+
+        @base.command()
+        def info():
+            """Get device information"""
+            chip_info = self.chip_info()
+            for key, value in chip_info.items():
+                print(f"{key}: {value}")
+
+        @base.command("chip-id")
+        def chip_id():
+            """Get chip ID information"""
+            info = self.chip_info()
+            print(f"Chip Type: {info.get('chip_type', 'Unknown')}")
+            if 'mac_address' in info:
+                print(f"MAC Address: {info['mac_address']}")
+            if 'chip_revision' in info:
+                print(f"Chip Revision: {info['chip_revision']}")
+
+        @base.command()
+        def reset():
+            """Reset the device"""
+            result = self.reset()
+            print(result)
+
+        @base.command()
+        def erase():
+            """Erase the entire flash"""
+            print("Erasing flash... this may take a while")
+            result = self.erase_flash()
+            print(result)
+
+        @base.command()
+        @click.argument("firmware_file", type=click.Path(exists=True))
+        @click.option("--address", "-a", default="0x10000", type=str,
+                     help="Flash address (hex or decimal)")
+        def flash(firmware_file, address):
+            """Flash firmware to the device"""
+            try:
+                if isinstance(address, str) and address.startswith("0x"):
+                    address = int(address, 16)
+                else:
+                    address = int(float(address))
+            except (ValueError, TypeError):
+                address = 0x10000  # Default fallback
+
+            print(f"Flashing {firmware_file} to address 0x{address:x}...")
+            result = self.flash_firmware_file(firmware_file, address)
+            print(result)
+
+        @base.command("read-flash")
+        @click.argument("address", type=str)
+        @click.argument("size", type=str)
+        @click.option("--output", "-o", type=click.Path(),
+                     help="Output file (default: print hex)")
+        def read_flash_cmd(address, size, output):
+            """Read flash contents"""
+            # Parse address and size
+            try:
+                if address.startswith("0x"):
+                    address = int(address, 16)
+                else:
+                    address = int(float(address))
+            except (ValueError, TypeError):
+                address = 0
+
+            try:
+                if size.startswith("0x"):
+                    size = int(size, 16)
+                else:
+                    size = int(float(size))
+            except (ValueError, TypeError):
+                size = 1024
+
+            print(f"Reading {size} bytes from address 0x{address:x}...")
+            data = self.read_flash(address, size)
+
+            if output:
+                with open(output, 'wb') as f:
+                    f.write(data)
+                print(f"Data written to {output}")
+            else:
+                # Print as hex
+                hex_data = data.hex()
+                for i in range(0, len(hex_data), 32):
+                    addr_offset = address + i // 2
+                    line = hex_data[i:i+32]
+                    print(f"0x{addr_offset:08x}: {line}")
+
+        @base.command()
+        def bootloader():
+            """Enter bootloader mode"""
+            result = self.enter_bootloader()
+            print(result)
+
+        return base