Skip to content

Commit 153674a

Browse files
bennyzbennyz
committed
esp32: add documentation
Signed-off-by: Benny Zlotnik <[email protected]>
1 parent 4a20fe4 commit 153674a

File tree

4 files changed

+165
-35
lines changed

4 files changed

+165
-35
lines changed

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

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# ESP32 driver
2+
3+
`jumpstarter-driver-esp32` provides functionality for flashing, monitoring, and controlling ESP32 devices using esptool and serial communication.
4+
5+
## Installation
6+
7+
```{code-block} console
8+
:substitutions:
9+
$ pip3 install --extra-index-url {{index_url}} jumpstarter-driver-esp32
10+
```
11+
12+
## Configuration
13+
14+
Example configuration:
15+
16+
```yaml
17+
export:
18+
esp32:
19+
type: jumpstarter_driver_esp32.driver.ESP32
20+
config:
21+
port: "/dev/ttyUSB0"
22+
baudrate: 115200
23+
chip: "esp32"
24+
# Optional GPIO pins for hardware control
25+
# reset_pin: 2
26+
# boot_pin: 0
27+
```
28+
29+
### Config parameters
30+
31+
| Parameter | Description | Type | Required | Default |
32+
| ------------- | --------------------------------------------------------------------- | ---- | -------- | ------- |
33+
| port | The serial port to connect to the ESP32 | str | yes | |
34+
| baudrate | The baudrate for serial communication | int | no | 115200 |
35+
| chip | The ESP32 chip type (esp32, esp32s2, esp32s3, esp32c3, etc.) | str | no | esp32 |
36+
| reset_pin | GPIO pin number for hardware reset (if connected) | int | no | null |
37+
| boot_pin | GPIO pin number for boot mode control (if connected) | int | no | null |
38+
| check_present | Check if the serial port exists during exporter initialization | bool | no | True |
39+
40+
## API Reference
41+
42+
```{eval-rst}
43+
.. autoclass:: jumpstarter_driver_esp32.client.ESP32Client()
44+
:members: chip_info, reset, erase_flash, flash_firmware, flash_firmware_file, read_flash, enter_bootloader
45+
```
46+
47+
### CLI
48+
49+
The ESP32 driver client comes with a CLI tool that can be used to interact with ESP32 devices:
50+
51+
```
52+
jumpstarter ⚡ local ➤ j esp32
53+
Usage: j esp32 [OPTIONS] COMMAND [ARGS]...
54+
55+
ESP32 client
56+
57+
Options:
58+
--help Show this message and exit.
59+
60+
Commands:
61+
bootloader Enter bootloader mode
62+
chip-id Get chip ID information
63+
erase Erase the entire flash
64+
flash Flash firmware to the device
65+
info Get device information
66+
read-flash Read flash contents
67+
reset Reset the device
68+
```
69+
70+
## Examples
71+
72+
### Getting device information
73+
74+
```{testcode-skip}
75+
info = esp32.chip_info()
76+
print(f"Connected to {info['chip_revision']}")
77+
print(f"MAC Address: {info['mac_address']}")
78+
print(f"Chip ID: {info['chip_id']}")
79+
```
80+
81+
### Flashing firmware
82+
83+
```{testcode-skip}
84+
# Flash firmware from a local file
85+
result = esp32.flash_firmware_file("firmware.bin", address=0x10000)
86+
print(result)
87+
88+
# Flash firmware using OpenDAL operator
89+
from opendal import Operator
90+
operator = Operator("fs", root="/path/to/firmware")
91+
result = esp32.flash_firmware(operator, "firmware.bin", address=0x10000)
92+
print(result)
93+
```
94+
95+
### Reading flash contents
96+
97+
```{testcode-skip}
98+
# Read 1024 bytes from address 0x0
99+
data = esp32.read_flash(address=0x0, size=1024)
100+
print(f"Read {len(data)} bytes from flash")
101+
```
102+
103+
### Device control
104+
105+
```{testcode-skip}
106+
# Reset the device
107+
result = esp32.reset()
108+
print(result)
109+
110+
# Enter bootloader mode
111+
result = esp32.enter_bootloader()
112+
print(result)
113+
114+
# Erase entire flash (use with caution!)
115+
result = esp32.erase_flash()
116+
print(result)
117+
```
118+
119+
### CLI Examples
120+
121+
```{code-block} console
122+
# Get device information
123+
$ j esp32 info
124+
125+
# Flash firmware to default app partition (0x10000)
126+
$ j esp32 flash firmware.bin
127+
128+
# Flash firmware to specific address
129+
$ j esp32 flash firmware.bin --address 0x1000
130+
131+
# Read flash contents
132+
$ j esp32 read-flash 0x0 1024
133+
134+
# Save flash contents to file
135+
$ j esp32 read-flash 0x0 1024 --output flash_dump.bin
136+
137+
# Reset the device
138+
$ j esp32 reset
139+
140+
# Erase the entire flash
141+
$ j esp32 erase
142+
```
143+
144+
```{testsetup} *
145+
from jumpstarter_driver_esp32.driver import ESP32
146+
from jumpstarter.common.utils import serve
147+
148+
instance = serve(ESP32(port="loop://"))
149+
150+
esp32 = instance.__enter__()
151+
```
152+
153+
```{testcleanup} *
154+
instance.__exit__(None, None, None)
155+
```

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ Drivers for debugging and programming devices:
7373
* **[U-Boot](uboot.md)** (`jumpstarter-driver-uboot`) - Universal Bootloader
7474
interface
7575
* **[RideSX](ridesx.md)** (`jumpstarter-driver-ridesx`) - Flashing and power management for Qualcomm RideSX devices
76+
* **[ESP32](esp32.md)** (`jumpstarter-driver-esp32`) - ESP32 development board support
7677

7778
### Utility Drivers
7879

@@ -86,6 +87,7 @@ can.md
8687
corellium.md
8788
dutlink.md
8889
energenie.md
90+
esp32.md
8991
flashers.md
9092
http.md
9193
http-power.md

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

Lines changed: 7 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,11 @@ export:
2121
port: "/dev/ttyUSB0"
2222
baudrate: 115200
2323
chip: "esp32"
24+
serial:
25+
type: jumpstarter_driver_pyserial.driver.PySerial
26+
config:
27+
url: "/dev/ttyUSB0"
28+
baudrate: 115200
2429
```
2530
2631
### Config parameters
@@ -41,37 +46,6 @@ export:
4146
4247
# Examples
4348
44-
```{testcode}
45-
from jumpstarter.common.utils import env
46-
from jumpstarter.config.client import ClientConfigV1Alpha1
47-
48-
def main():
49-
try:
50-
# Try to use existing JUMPSTARTER_HOST environment variable
51-
with env() as client:
52-
run_esp32_example(client)
53-
except RuntimeError:
54-
# Fallback to creating a lease (requires jumpstarter configuration)
55-
config = ClientConfigV1Alpha1.load("default")
56-
with config.lease(selector="driver=esp32") as lease:
57-
with lease.connect() as client:
58-
run_esp32_example(client)
59-
60-
def run_esp32_example(client):
61-
esp32 = client.esp32
62-
63-
# Get chip information
64-
info = esp32.chip_info()
65-
print(f"Connected to {info['chip_revision']}")
66-
print(f"MAC Address: {info['mac_address']}")
67-
68-
# Flash firmware
69-
result = esp32.flash_firmware_file("firmware.bin", address=0x10000)
70-
print(result)
71-
72-
# Reset device to run new firmware
73-
esp32.reset()
74-
75-
if __name__ == "__main__":
76-
main()
49+
```shell
50+
$ j esp32 flash ESP32_GENERIC-20250911-v1.26.1.bin -a 0x1000
7751
```

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
#!/usr/bin/env python3
2-
import os
32
from jumpstarter.common.utils import env
4-
from jumpstarter.config.client import ClientConfigV1Alpha1
3+
54

65
def main():
76
with env() as client:

0 commit comments

Comments
 (0)