Class: Prremote::EspFlasher

Inherits:
Object
  • Object
show all
Defined in:
lib/prremote/esp_flasher.rb

Overview

Pure-Ruby flasher for classic ESP32 (Xtensa) boards. Speaks the Espressif serial bootloader protocol directly so install --board esp32 needs no external tools.

For ESP32-C6 and other USB-JTAG/Serial chips the ROM does not support direct flash write/erase (FLASH_BEGIN returns error 0x38 regardless of parameters). esptool uploads a RAM stub before writing; we delegate those boards to the esptool CLI instead of reimplementing the stub protocol.

Protocol reference: https://docs.espressif.com/projects/esptool/en/latest/esp32/advanced-topics/serial-protocol.html

Defined Under Namespace

Classes: Error

Constant Summary collapse

FLASH_BEGIN =

Command opcodes

0x02
FLASH_DATA = 
0x03
FLASH_END = 
0x04
SYNC = 
0x08
READ_REG = 
0x0A
SPI_SET_PARAMS = 
0x0B
SPI_ATTACH = 
0x0D
CHANGE_BAUD = 
0x0F
SPI_FLASH_MD5 = 
0x13
FLASH_WRITE_SIZE =

max data per FLASH_DATA packet

0x400
CHECKSUM_SEED = 
0xEF
ROM_BAUD = 
115_200
USB_JTAG_SERIAL_BOARDS =

Boards with built-in USB Serial/JTAG — flashed via esptool subprocess.

%w[esp32c6].freeze
EFUSE_RD_REG_BASE =

Classic ESP32 ROM only auto-attaches flash on modules with pads wired to the default HSPI pins. SiP packages with in-package flash (e.g. ESP32-PICO-D4, used on M5StickC/PLUS) route flash through pins burned into eFuse instead, and FLASH_BEGIN silently hangs forever (no error response) if SPI_ATTACH(0) is sent on those. Mirrors esptool's attach_flash()/get_chip_spi_pads() (cmds.py / targets/esp32.py).

0x3FF5A000
EFUSE_BLK0_RDATA3_REG_OFFS = 
EFUSE_RD_REG_BASE + 0x00C
EFUSE_BLK0_RDATA5_REG_OFFS = 
EFUSE_RD_REG_BASE + 0x014
STATUS_BYTES_BY_BOARD =

ROM status-byte count: classic ESP32 appends 4 bytes, RISC-V chips 2.

Hash.new(4).freeze
SPI_ATTACH_LEGACY_BOARDS =

Classic ESP32 SPI_ATTACH takes [hspi_arg, extended_arg] (8 bytes); newer RISC-V chips take only [hspi_arg] (4 bytes).

%w[esp32].freeze
MD5_HEX_LENGTH = 
32
MD5_RAW_LENGTH = 
16
TIOCM_DTR =

ioctl modem-control constants

0x0002
TIOCM_RTS = 
0x0004
DARWIN = 
RbConfig::CONFIG['host_os'] =~ /darwin/ ? true : false
TIOCMGET = 
DARWIN ? 0x4004746A : 0x5415
TIOCMSET = 
DARWIN ? 0x8004746D : 0x5418

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(serial, fd: nil, status_bytes: 4, board: nil, verbose: false) ⇒ EspFlasher

serial needs #read/#write; fd enables DTR/RTS control.



170
171
172
173
174
175
176
177
 
# File 'lib/prremote/esp_flasher.rb', line 170

def initialize(serial, fd: nil, status_bytes: 4, board: nil, verbose: false)
  @serial       = serial
  @fd           = fd
  @rxbuf        = +''.b
  @status_bytes = status_bytes
  @board        = board.to_s
  @verbose      = verbose
end

Class Method Details

.baud_supported?(baud) ⇒ Boolean

Returns:

  • (Boolean) 


98
99
100
101
102
 
# File 'lib/prremote/esp_flasher.rb', line 98

def self.baud_supported?(baud)
  RubySerial::Posix::BAUDE_RATES.key?(baud)
rescue NameError
  false
end

.esptool_write(ctx, before:, after:, connect_attempts:) ⇒ Object

Runs one esptool write-flash 0x0 <image> pass, returning esptool's success boolean. connect_attempts 0 = retry the connect forever. ctx carries the fixed invocation context (esptool/port/image_path/board/verbose).



143
144
145
146
147
148
149
150
151
 
# File 'lib/prremote/esp_flasher.rb', line 143

def self.esptool_write(ctx, before:, after:, connect_attempts:)
  cmd = [*ctx[:esptool],
         '--chip', ctx[:board], '--port', ctx[:port],
         '--connect-attempts', connect_attempts.to_s,
         '--before', before, '--after', after,
         'write-flash', '0x0', ctx[:image_path]]
  warn "[flash] #{cmd.join(' ')}" if ctx[:verbose]
  system(*cmd)
end

.find_esptool ⇒ Object 



153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/prremote/esp_flasher.rb', line 153

def self.find_esptool
  dirs = ENV.fetch('PATH', '').split(File::PATH_SEPARATOR)
  %w[esptool esptool.py].each do |exe|
    return [exe] if dirs.any? { |d| (f = File.join(d, exe)) && File.executable?(f) && !File.directory?(f) }
  end
  # python3 -m esptool fallback: must actually import the module to verify
  return ['python3', '-m', 'esptool'] if
    system('python3', '-c', 'import esptool', out: File::NULL, err: File::NULL)

  nil
rescue StandardError
  nil
end

.flash(port:, image_path:, baud: ROM_BAUD, board: nil, verbose: false) ⇒ Object

Entry point. Routes USB-JTAG/Serial boards through esptool; handles classic ESP32 with the pure-Ruby protocol implementation.



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/prremote/esp_flasher.rb', line 67

def self.flash(port:, image_path:, baud: ROM_BAUD, board: nil, verbose: false)
  if USB_JTAG_SERIAL_BOARDS.include?(board)
    return flash_via_esptool(port: port, image_path: image_path, board: board,
                             verbose: verbose)
  end

  unless RbConfig::CONFIG['host_os'] =~ /darwin|linux/
    raise Error, 'pure-Ruby flashing supports macOS/Linux only; ' \
                 'on other systems use esptool: ' \
                 "esptool write-flash 0x0 #{image_path}"
  end

  image        = File.binread(image_path)
  status_bytes = STATUS_BYTES_BY_BOARD[board]
  serial       = Serial.new(port, ROM_BAUD)
  flasher      = new(serial, fd: serial.instance_variable_get(:@fd),
                             status_bytes: status_bytes, board: board, verbose: verbose)
  begin
    flasher.enter_bootloader
    flasher.sync!
    upgrade = baud != ROM_BAUD && baud_supported?(baud)
    serial = flasher.upgrade_baud(port, baud) if upgrade
    flasher.write_flash(image, offset: 0)
    flasher.verify_md5(image, offset: 0)
    flasher.finish_flash
    flasher.hard_reset
  ensure
    serial.close
  end
end

.flash_via_esptool(port:, image_path:, board:, verbose:) ⇒ Object

Flash via the esptool CLI (required for USB-JTAG/Serial boards whose ROM does not support direct write). esptool handles stub upload internally; we just need it installed.



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/prremote/esp_flasher.rb', line 107

def self.flash_via_esptool(port:, image_path:, board:, verbose:)
  esptool = find_esptool
  unless esptool
    raise Error, <<~MSG.strip
      Flashing #{board} requires esptool.
      Install:  brew install esptool
          or:  pip3 install esptool
    MSG
  end

  ctx = { esptool: esptool, port: port, image_path: image_path, board: board, verbose: verbose }

  # USB-Serial/JTAG chips (e.g. XIAO ESP32C6) can be dropped into the
  # download ROM over USB, so esptool's usb-reset flashes hands-free — no
  # BOOT/RST button dance. --after hard-reset then reboots straight into the
  # freshly flashed firmware. Verified on a physical XIAO ESP32C6.
  return if esptool_write(ctx, before: 'usb-reset', after: 'hard-reset', connect_attempts: 7)

  # Fallback for hosts/boards where usb-reset doesn't take: enter the
  # bootloader by hand and let esptool retry forever. --before no-reset never
  # resets the chip, so each attempt just re-sends SYNC until the manual
  # BOOT/RST lands the board in download mode — no timeout to race against.
  warn ''
  warn "Couldn't reset #{board} automatically. Put it in bootloader mode by hand:"
  warn '  XIAO ESP32C6: hold BOOT, press RST, release both.'
  warn 'No rush — esptool keeps retrying the SYNC handshake until it connects.'
  esptool_write(ctx, before: 'no-reset', after: 'no-reset', connect_attempts: 0) or
    raise Error, 'esptool exited with an error'

  warn ''
  warn 'Flash complete. Press RST to start the firmware.'
end

Instance Method Details

#checksum(data) ⇒ Object 



302
303
304
 
# File 'lib/prremote/esp_flasher.rb', line 302

def checksum(data)
  data.bytes.reduce(CHECKSUM_SEED) { |acc, b| acc ^ b }
end

#command(op, payload, checksum: 0, timeout: 3) ⇒ Object

── request/response plumbing ──────────────────────────────────────────



287
288
289
290
291
292
293
294
295
296
297
298
299
300
 
# File 'lib/prremote/esp_flasher.rb', line 287

def command(op, payload, checksum: 0, timeout: 3)
  packet = [0x00, op, payload.bytesize].pack('CCv') +
           [checksum].pack('V') + payload
  @serial.write(slip_encode(packet))

  deadline = Time.now + timeout
  loop do
    frame = read_frame(deadline)
    raise Error, format('timeout waiting for response to 0x%<op>02x', op: op) if frame.nil?

    result = parse_response(frame, op)
    return result if result
  end
end

#efuse_spi_attach_arg ⇒ Object

SPI_ATTACH(0) only works for modules with flash on the default HSPI pins. In-package flash (ESP32-PICO-D4/V3, e.g. M5StickC/PLUS) needs its actual pin numbers, burned into eFuse, packed into SPI_ATTACH's arg. Returns 0 (the "use default pins" value) when eFuse has nothing burned.



265
266
267
268
269
270
271
272
273
274
275
276
277
278
 
# File 'lib/prremote/esp_flasher.rb', line 265

def efuse_spi_attach_arg
  rdata5 = read_reg(EFUSE_BLK0_RDATA5_REG_OFFS)
  clk    = rdata5 & 0x1F
  q      = (rdata5 >> 5) & 0x1F
  d      = (rdata5 >> 10) & 0x1F
  cs     = (rdata5 >> 15) & 0x1F
  hd     = (read_reg(EFUSE_BLK0_RDATA3_REG_OFFS) >> 4) & 0x1F

  return 0 if [clk, q, d, hd, cs].all?(&:zero?)

  vlog format('in-package flash detected (CLK:%<clk>d Q:%<q>d D:%<d>d HD:%<hd>d CS:%<cs>d)',
              clk: clk, q: q, d: d, hd: hd, cs: cs)
  (hd << 24) | (cs << 18) | (d << 12) | (q << 6) | clk
end

#enter_bootloader ⇒ Object

Classic auto-reset: RTS→EN, DTR→IO0 (via external UART bridge).



180
181
182
183
184
185
186
 
# File 'lib/prremote/esp_flasher.rb', line 180

def enter_bootloader
  set_lines(dtr: false, rts: true)
  sleep 0.1
  set_lines(dtr: true, rts: false)
  sleep 0.05
  set_lines(dtr: false, rts: false)
end

#finish_flash ⇒ Object

FLASH_END is a courtesy; hard_reset resets the chip anyway. The ROM has been seen returning error 0x06 here — ignore it.



243
244
245
246
247
 
# File 'lib/prremote/esp_flasher.rb', line 243

def finish_flash
  command(FLASH_END, [1].pack('V'))
rescue Error
  nil
end

#hard_reset ⇒ Object 



188
189
190
191
192
 
# File 'lib/prremote/esp_flasher.rb', line 188

def hard_reset
  set_lines(dtr: false, rts: true)
  sleep 0.1
  set_lines(dtr: false, rts: false)
end

#read_reg(addr) ⇒ Object 



280
281
282
283
 
# File 'lib/prremote/esp_flasher.rb', line 280

def read_reg(addr)
  value, = command(READ_REG, [addr].pack('V'))
  value
end

#slip_decode(frame) ⇒ Object 



311
312
313
 
# File 'lib/prremote/esp_flasher.rb', line 311

def slip_decode(frame)
  frame.gsub("\xDB\xDC".b, "\xC0".b).gsub("\xDB\xDD".b, "\xDB".b)
end

#slip_encode(packet) ⇒ Object 



306
307
308
309
 
# File 'lib/prremote/esp_flasher.rb', line 306

def slip_encode(packet)
  escaped = packet.gsub("\xDB".b, "\xDB\xDD".b).gsub("\xC0".b, "\xDB\xDC".b)
  "\xC0".b + escaped + "\xC0".b
end

#sync! ⇒ Object

── protocol steps ─────────────────────────────────────────────────────

Raises:



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/prremote/esp_flasher.rb', line 196

def sync!
  payload = [0x07, 0x07, 0x12, 0x20].pack('C4') + ([0x55] * 32).pack('C32')
  synced = 8.times.any? do |i|
    @rxbuf.clear
    begin
      vlog format('sync: attempt %<n>d/8 (status_bytes=%<sb>d)', n: i + 1, sb: @status_bytes)
      command(SYNC, payload, timeout: 0.5)
      drain_responses
      vlog 'sync: success'
      true
    rescue Error => e
      vlog format('sync: attempt %<n>d failed (%<msg>s)', n: i + 1, msg: e.message)
      false
    end
  end
  raise Error, 'could not sync with the ESP boot ROM' unless synced
end

#upgrade_baud(port, baud) ⇒ Object

CHANGE_BAUDRATE, then reopen the port at the new speed.



215
216
217
218
219
220
221
222
223
224
 
# File 'lib/prremote/esp_flasher.rb', line 215

def upgrade_baud(port, baud)
  command(CHANGE_BAUD, [baud, 0].pack('V2'))
  @serial.close
  sleep 0.05
  serial  = Serial.new(port, baud)
  @serial = serial
  @fd     = serial.instance_variable_get(:@fd)
  @rxbuf.clear
  serial
end

#verify_md5(image, offset: 0) ⇒ Object

Raises:



249
250
251
252
253
254
255
256
257
258
259
 
# File 'lib/prremote/esp_flasher.rb', line 249

def verify_md5(image, offset: 0)
  timeout    = 8 * (1 + (image.bytesize / (1024 * 1024)))
  _v, data   = command(SPI_FLASH_MD5, [offset, image.bytesize, 0, 0].pack('V4'),
                       timeout: timeout)
  # Classic ESP32 ROM returns 32 hex ASCII chars; detect by length.
  device_md5 = data.bytesize >= MD5_HEX_LENGTH ? data[0, MD5_HEX_LENGTH] : data[0, MD5_RAW_LENGTH].unpack1('H*')
  local_md5  = Digest::MD5.hexdigest(image)
  return if device_md5 == local_md5

  raise Error, "MD5 mismatch after flashing (device #{device_md5}, local #{local_md5})"
end

#write_flash(image, offset: 0) ⇒ Object 



226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/prremote/esp_flasher.rb', line 226

def write_flash(image, offset: 0)
  hspi_arg = SPI_ATTACH_LEGACY_BOARDS.include?(@board) ? efuse_spi_attach_arg : 0
  spi_attach_payload = SPI_ATTACH_LEGACY_BOARDS.include?(@board) ? [hspi_arg, 0].pack('V2') : [hspi_arg].pack('V')
  command(SPI_ATTACH, spi_attach_payload)
  # id, total_size, block_size, sector_size, page_size, status_mask
  command(SPI_SET_PARAMS, [0, 4 * 1024 * 1024, 64 * 1024, 4096, 256, 0xFFFF].pack('V6'))

  blocks        = (image.bytesize + FLASH_WRITE_SIZE - 1) / FLASH_WRITE_SIZE
  erase_size    = blocks * FLASH_WRITE_SIZE
  erase_timeout = 30 * (1 + (erase_size / (1024 * 1024)))
  command(FLASH_BEGIN, [erase_size, blocks, FLASH_WRITE_SIZE, offset].pack('V4'),
          timeout: erase_timeout)
  stream_blocks(image, blocks)
end