Skip to content

Commit d440195

Browse files
committed
docs: add some important README updates
Signed-off-by: deadprogram <ron@hybridgroup.com>
1 parent ae6add1 commit d440195

File tree

1 file changed

+21
-5
lines changed

1 file changed

+21
-5
lines changed

README.md

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# espflasher
22

3-
[![Test](https://github.com/tinygo-org/espflasher/actions/workflows/test.yml/badge.svg)](https://github.com/tinygo-org/espflasher/actions/workflows/test.yml)
3+
[![PkgGoDev](https://pkg.go.dev/badge/pkg.go.dev/tinygo.org/x/espflasher)](https://pkg.go.dev/tinygo.org/x/espflasher) [![Test](https://github.com/tinygo-org/espflasher/actions/workflows/test.yml/badge.svg)](https://github.com/tinygo-org/espflasher/actions/workflows/test.yml)
44

5-
A Go command-line tool and library for flashing firmware to Espressif ESP8266 and ESP32-family microcontrollers over a serial (UART) connection.
5+
A Go command-line tool and library for flashing firmware to Espressif ESP8266 and ESP32-family microcontrollers over serial (UART) or USB-JTAG/Serial connections.
66

77
## Supported Chips
88

@@ -38,6 +38,9 @@ espflasher -port /dev/ttyUSB0 firmware.bin
3838
# Flash with specific offset and chip
3939
espflasher -port /dev/ttyUSB0 -offset 0x10000 -chip esp32s3 app.bin
4040

41+
# Flash via native USB-JTAG/Serial (ESP32-S3, ESP32-C3, etc.)
42+
espflasher -port /dev/ttyACM0 -reset usb-jtag -chip esp32s3 firmware.bin
43+
4144
# Flash multiple images (bootloader + partitions + app)
4245
espflasher -port /dev/ttyUSB0 \
4346
-bootloader bootloader.bin \
@@ -71,7 +74,7 @@ import (
7174

7275
func main() {
7376
// Connect to the ESP device
74-
flasher, err := espflasher.NewFlasher("/dev/ttyUSB0", nil)
77+
flasher, err := espflasher.New("/dev/ttyUSB0", nil)
7578
if err != nil {
7679
log.Fatal(err)
7780
}
@@ -109,22 +112,35 @@ func main() {
109112
- **Progress callbacks**: Monitor flash progress in real-time
110113
- **MD5 verification**: Verifies written data integrity after flashing
111114
- **Configurable**: Customize baud rate, compression, reset mode, and more
115+
- **USB-JTAG/Serial**: Native USB support for boards like ESP32-S3 and ESP32-C3 that expose a built-in USB-JTAG/Serial interface (typically `/dev/ttyACM0` on Linux, `cu.usbmodem*` on macOS)
112116
- **Stubs**: Use stubs for higher-speed downloads and other advanced processor features
113117

118+
## Reset Modes
119+
120+
| CLI Flag | Go Constant | Description |
121+
|----------|-------------|-------------|
122+
| `default` | `ResetDefault` | Classic DTR/RTS reset sequence. Works with most boards using a USB-to-UART bridge (CP2102, CH340, etc.). |
123+
| `usb-jtag` | `ResetUSBJTAG` | Reset sequence for boards with a native USB-JTAG/Serial interface (ESP32-S3, ESP32-C3, ESP32-C6, ESP32-H2). Use this when connected via `/dev/ttyACM0` (Linux) or `cu.usbmodem*` (macOS). |
124+
| `no-reset` | `ResetNoReset` | Skip hardware reset entirely. Useful when the chip is already in bootloader mode or reset is handled externally. |
125+
114126
## API Overview
115127

116128
### Creating a Flasher
117129

118130
```go
119131
// With default options (115200 baud, auto-detect, compressed)
120-
flasher, err := espflasher.NewFlasher("/dev/ttyUSB0", nil)
132+
flasher, err := espflasher.New("/dev/ttyUSB0", nil)
121133

122134
// With custom options
123135
opts := espflasher.DefaultOptions()
124136
opts.FlashBaudRate = 921600
125137
opts.ChipType = espflasher.ChipESP32S3
126138
opts.Logger = &espflasher.StdoutLogger{W: os.Stdout}
127-
flasher, err := espflasher.NewFlasher("/dev/ttyUSB0", opts)
139+
flasher, err := espflasher.New("/dev/ttyUSB0", opts)
140+
141+
// For boards with native USB-JTAG/Serial (ESP32-S3, ESP32-C3, etc.)
142+
opts.ResetMode = espflasher.ResetUSBJTAG
143+
flasher, err := espflasher.New("/dev/ttyACM0", opts)
128144
```
129145

130146
### Flashing a Single Binary

0 commit comments

Comments
 (0)