Skip to content

Commit 8a07b34

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

File tree

4 files changed

+147
-35
lines changed

4 files changed

+147
-35
lines changed

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

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
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}
75+
:skipif: True
76+
info = esp32.chip_info()
77+
print(f"Connected to {info['chip_revision']}")
78+
print(f"MAC Address: {info['mac_address']}")
79+
print(f"Chip ID: {info['chip_id']}")
80+
```
81+
82+
### Flashing firmware
83+
84+
```{testcode}
85+
:skipif: True
86+
# Flash firmware from a local file
87+
result = esp32.flash_firmware_file("firmware.bin", address=0x10000)
88+
print(result)
89+
```
90+
91+
### Reading flash contents
92+
93+
```{testcode}
94+
:skipif: True
95+
# Read 1024 bytes from address 0x0
96+
data = esp32.read_flash(address=0x0, size=1024)
97+
print(f"Read {len(data)} bytes from flash")
98+
```
99+
100+
### Device control
101+
102+
```{testcode}
103+
:skipif: True
104+
# Reset the device
105+
result = esp32.reset()
106+
107+
# Enter bootloader mode
108+
result = esp32.enter_bootloader()
109+
110+
# Erase entire flash
111+
result = esp32.erase_flash()
112+
```
113+
114+
### CLI Examples
115+
116+
```{code-block} console
117+
# Get device information
118+
$ j esp32 info
119+
120+
# Flash firmware to default app partition (0x10000)
121+
$ j esp32 flash firmware.bin
122+
123+
# Flash firmware to specific address
124+
$ j esp32 flash firmware.bin --address 0x1000
125+
126+
# Read flash contents
127+
$ j esp32 read-flash 0x0 1024
128+
129+
# Save flash contents to file
130+
$ j esp32 read-flash 0x0 1024 --output flash_dump.bin
131+
132+
# Reset the device
133+
$ j esp32 reset
134+
135+
# Erase the entire flash
136+
$ j esp32 erase
137+
```

‎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)