@serialpilot/driver-esp-flasher

ESP32 / ESP8266 / ESP32-S3 ROM-bootloader flasher for SerialPilot.

SLIP-framed binary protocol over serial. Drives the DTR/RTS reset dance to enter the bootloader, syncs, detects the chip variant by magic register, optionally erases flash, writes firmware in 1024-byte blocks with 'progress' events, and resets the chip into application mode.

Install

npm install serialpilot @serialpilot/driver-esp-flasher

Quick start

import { readFile } from 'node:fs/promises'
import { SerialPilot } from 'serialpilot'
import { EspFlasher } from '@serialpilot/driver-esp-flasher'

const port = new SerialPilot({ path: '/dev/ttyUSB0', baudRate: 115200 })
const esp = new EspFlasher({ transport: port })

await esp.open()
await esp.enterBootloader()
await esp.sync()
const chip = await esp.chipDetect()
console.log('Chip:', chip.name)

const firmware = await readFile('app.bin')
esp.on('progress', p => process.stdout.write(`\r${p.written}/${p.total} bytes`))

await esp.flash({ offset: 0x10000, data: firmware })
await esp.reset()
await esp.close()

Events

| Event | Payload | Notes | | --- | --- | --- | | 'progress' | {written, total} | After each ACKed FLASH_DATA block | | 'chip' | {name, magic} | After chipDetect() resolves | | 'error' | Error | Inherited from Device; transport errors | | 'parse-error' | {reason, frame} | Malformed inbound frame that didn't pass parseResponse validation | | Inherited | 'open' \| 'close' \| 'state' \| 'data' | From Device |

Limitations (v0.1)

• Stub-loader stage not implemented. v0.1 talks directly to the ROM bootloader, which is slower than esptool.py's stub but simpler.
• No flash compression. data passed to flash() is sent as-is.
• DTR/RTS sequence assumes the standard "Auto Reset" wiring (RTS→EN, DTR→GPIO0). Boards with inverted or non-standard wiring may need a manual entry into bootloader.
• 115200 baud only. No baud-rate handshake.

License

MIT