|
1 | 1 | # espflasher |
2 | 2 |
|
3 | | -[](https://github.com/tinygo-org/espflasher/actions/workflows/test.yml) |
| 3 | +[](https://pkg.go.dev/tinygo.org/x/espflasher) [](https://github.com/tinygo-org/espflasher/actions/workflows/test.yml) |
4 | 4 |
|
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. |
6 | 6 |
|
7 | 7 | ## Supported Chips |
8 | 8 |
|
@@ -38,6 +38,9 @@ espflasher -port /dev/ttyUSB0 firmware.bin |
38 | 38 | # Flash with specific offset and chip |
39 | 39 | espflasher -port /dev/ttyUSB0 -offset 0x10000 -chip esp32s3 app.bin |
40 | 40 |
|
| 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 | + |
41 | 44 | # Flash multiple images (bootloader + partitions + app) |
42 | 45 | espflasher -port /dev/ttyUSB0 \ |
43 | 46 | -bootloader bootloader.bin \ |
@@ -71,7 +74,7 @@ import ( |
71 | 74 |
|
72 | 75 | func main() { |
73 | 76 | // Connect to the ESP device |
74 | | - flasher, err := espflasher.NewFlasher("/dev/ttyUSB0", nil) |
| 77 | + flasher, err := espflasher.New("/dev/ttyUSB0", nil) |
75 | 78 | if err != nil { |
76 | 79 | log.Fatal(err) |
77 | 80 | } |
@@ -109,22 +112,35 @@ func main() { |
109 | 112 | - **Progress callbacks**: Monitor flash progress in real-time |
110 | 113 | - **MD5 verification**: Verifies written data integrity after flashing |
111 | 114 | - **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) |
112 | 116 | - **Stubs**: Use stubs for higher-speed downloads and other advanced processor features |
113 | 117 |
|
| 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 | + |
114 | 126 | ## API Overview |
115 | 127 |
|
116 | 128 | ### Creating a Flasher |
117 | 129 |
|
118 | 130 | ```go |
119 | 131 | // With default options (115200 baud, auto-detect, compressed) |
120 | | -flasher, err := espflasher.NewFlasher("/dev/ttyUSB0", nil) |
| 132 | +flasher, err := espflasher.New("/dev/ttyUSB0", nil) |
121 | 133 |
|
122 | 134 | // With custom options |
123 | 135 | opts := espflasher.DefaultOptions() |
124 | 136 | opts.FlashBaudRate = 921600 |
125 | 137 | opts.ChipType = espflasher.ChipESP32S3 |
126 | 138 | 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) |
128 | 144 | ``` |
129 | 145 |
|
130 | 146 | ### Flashing a Single Binary |
|
0 commit comments