prremote 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c370f33a2cd268d2ab4eba26c7123d195e71fc5a927c386d561e55ad5a2adb0e
-  data.tar.gz: 181302d7b8d2cd6e78f3a76b98171bddd5fb4c9d66f8c0aacd925f4911cb4920
+  metadata.gz: cfce7ce99a7bd04bbfde40aad5c53640f14f1ad90da41998c7399e6366d25198
+  data.tar.gz: d60e5701e6d42baf78a82a6d7d919d3bb5664cd34cb9cb02cdf7a2a749368121
 SHA512:
-  metadata.gz: f411813a2aa5c91a59bb7ce05b74a1bbd6f85bfb4b8329f7a1df146d8a014eb65ee6750643c63d2bdb3d09ec8bd0b3943e28e14d48a459cb3d3f645bf6206a68
-  data.tar.gz: 47f84f1d2277a04b1739f7c72f3565d9c3e8f6ba2700abc38142370d90ef928e577eb931d3ec8a8dafc5019b0ac15bd5da857cc33a1c400f4ca3ae28f59109d4
+  metadata.gz: 5fd70f1266d67f8f41aef2018c102d4827c53cb103f304a16d40f78ee618c99556bc45fbc94447f66ff4e157f5318ff5b62956e8edf5dd1d1acda5a53ac1d94d
+  data.tar.gz: 70372664611e75517b6ea974ff85b222ecb6b53944ffdc345f423e6c15720b4daeedc84cdba20e5338c3c754f6090ac1aeb605ef34f498f1a4a6849236b62c31

data/README.md

@@ -17,9 +17,10 @@ Inspired by [mpremote](https://docs.micropython.org/en/latest/reference/mpremote
 ## Requirements
 
 - Ruby 3.4 or later
-- A supported board:
-  - Raspberry Pi Pico W / Pico
-  - ESP32 (classic) — e.g. M5GO / M5Stack Core gen1, generic dev boards
+- Supported boards:
+  - [Raspberry Pi Pico W](https://www.raspberrypi.com/products/raspberry-pi-pico-w/) / [Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/)
+  - ESP32 (classic) — e.g. [M5GO / M5Stack Core gen1](https://docs.m5stack.com/en/core/m5go), generic [ESP32](https://www.espressif.com/en/products/socs/esp32) dev boards
+  - ESP32-C6 (RISC-V) — e.g. [Seeed Studio XIAO ESP32C6](https://wiki.seeedstudio.com/xiao_esp32c6_getting_started/)
 - `mrbc` (mruby 4.x) for `run`, `deploy`, and `eval`
   - macOS: `brew install mruby`
   - Linux: build from source — [github.com/mruby/mruby/releases](https://github.com/mruby/mruby/releases)
@@ -56,21 +57,28 @@ prremote run app.rb
 
 ### `install`
 
-Flash the prremote runtime firmware to a Pico W, Pico, or ESP32.
+Flash the prremote runtime firmware to a supported board.
 
 ```bash
-prremote install                          # Pico W (default)
-prremote install --board pico             # Pico (no wireless)
-prremote install --board esp32            # ESP32 (M5GO / M5Stack Core, etc.)
-prremote install --version 0.1.1          # specify a runtime version
-prremote install --board pico --version 0.1.1
+prremote install                          # show supported boards
+prremote install -b picow                 # Pico W
+prremote install -b pico                  # Pico (no wireless)
+prremote install -b esp32                 # ESP32 (M5GO / M5Stack Core, etc.)
+prremote install -b esp32c6               # ESP32-C6 (e.g. XIAO ESP32C6)
+prremote install -b picow --version 0.1.1 # specify a runtime version
 ```
 
+`-b` / `--board` selects the target board. Running `install` without `--board` prints the list of supported boards.
+
 The firmware is downloaded from GitHub Releases on first use and cached in `~/.prremote/runtime/`. Subsequent installs use the cache.
 
 Pico boards: put the device into BOOTSEL mode (hold BOOTSEL, connect USB, release) when prompted.
 
-ESP32 boards: no button dance and no extra tools needed — the firmware is written over the serial port by prremote's pure-Ruby implementation of the Espressif bootloader protocol (the chip is reset into its boot ROM automatically, and the write is verified with an on-chip MD5). Reflashing the runtime does not erase a deployed script.
+ESP32 (classic): no button dance and no extra tools needed — the firmware is written over the serial port by prremote's pure-Ruby implementation of the Espressif bootloader protocol (the chip is reset into its boot ROM automatically, and the write is verified with an on-chip MD5).
+
+ESP32-C6: flashing is delegated to [esptool](https://docs.espressif.com/projects/esptool/en/latest/), because the C6 boot ROM rejects the direct write the classic ESP32 accepts. Install it first (`brew install esptool`, or `pip3 install esptool`), and put the board into bootloader mode when prompted — on the XIAO ESP32C6, hold **BOOT**, press **RST**, then release both.
+
+Reflashing the runtime does not erase a deployed script on either chip.
 
 ---
 
@@ -91,7 +99,7 @@ prremote run lib.rb main.rb
 
 The device responds with `RUNNING`, streams any output, then `DONE`.
 
-You can find some examples in [test/samples](test/samples/).
+You can find some examples in [examples](examples/).
 
 ---
 
@@ -124,7 +132,7 @@ Evaluate a Ruby one-liner on the device.
 
 ```bash
 prremote eval "puts 1 + 1"
-prremote eval "CYW43.init; CYW43::GPIO.new(CYW43::GPIO::LED_PIN).write 1"
+prremote eval "GPIO.led.write 1"
 ```
 
 ---
@@ -168,8 +176,8 @@ Show the gem version, mrbc version, and the connected device's runtime version.
 
 ```bash
 prremote version
-# prremote: 0.2.0
-# runtime:  0.2.0 (/dev/tty.usbmodem101)
+# prremote: 0.3.0
+# runtime:  0.3.0 (/dev/tty.usbmodem101)
 # mrbc: mruby 4.0.0 (2026-04-20) (/opt/homebrew/bin/mrbc)
 ```
 
@@ -180,7 +188,7 @@ prremote version
 | Option | Description |
 |---|---|
 | `--port`, `-p PORT` | Serial port (default: auto-detect) |
-| `--baud`, `-b N` | Baud rate (default: `115200`) |
+| `--baud N` | Baud rate (default: `115200`) |
 
 ---
 
@@ -188,7 +196,7 @@ prremote version
 
 ```bash
 # First-time setup
-prremote install
+prremote install -b picow     # or: pico / esp32 / esp32c6
 
 # Manual cycle
 prremote run app.rb       # compile + run (one-shot)
@@ -214,7 +222,7 @@ prremote flashes a minimal C firmware (built on mruby/c) onto the Pico W. The fi
    - `DPLY` + `.mrb` bytecode → save to flash and confirm with `DEPLOYED` (`deploy`)
 3. Waits for the next command
 
-Scripts saved via `deploy` are stored in flash and run automatically on every boot. GPIO / ADC / PWM / I2C / SPI bindings are available on all boards; WiFi (CYW43) on the Pico W; an `LCD` class (ILI9342C) on ESP32 / M5Stack.
+Scripts saved via `deploy` are stored in flash and run automatically on every boot. GPIO / ADC / PWM / I2C / SPI bindings are available on all boards; a `WiFi` module on boards with a radio (Pico W and ESP32); an `LCD` class (ILI9342C) on ESP32 / M5Stack.
 
 ---
 
@@ -280,4 +288,4 @@ bundle exec rake test
 
 - [mruby/c](https://github.com/mrubyc/mrubyc) — Lightweight mruby implementation used in the runtime
 - [picotool](https://github.com/raspberrypi/picotool) — Official Raspberry Pi tool for inspecting and managing Pico devices; useful for checking what's on flash or force-rebooting outside of prremote
-- [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html) — MicroPython equivalent (inspiration)
+- [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html) — MicroPython equivalent (inspiration)

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/lib/prremote/cli.rb

@@ -16,7 +16,7 @@ require_relative 'commands/watch'
 module Prremote
   class CLI < Thor
     class_option :port, aliases: '-p', desc: 'Serial port (default: auto-detect)'
-    class_option :baud, aliases: '-b', type: :numeric, default: 115_200, desc: 'Baud rate'
+    class_option :baud, type: :numeric, default: 115_200, desc: 'Baud rate'
 
     def self.exit_on_failure?
       true
@@ -24,17 +24,30 @@ module Prremote
 
     remove_command :tree
 
-    desc 'install', 'Flash prremote runtime firmware to Pico W, Pico, or ESP32'
+    desc 'install', 'Flash prremote runtime firmware to a supported board'
     option :version, type: :string, desc: "Firmware version to install (default: #{VERSION})"
-    option :board, type: :string, desc: 'Board type: picow, pico, or esp32 (default: picow)'
+    option :board, aliases: '-b', type: :string,
+                   desc: "Board type: #{RuntimeManager::BOARDS.join(', ')}"
+    option :verbose, aliases: '-V', type: :boolean, default: false,
+                     desc: 'Print step-by-step flash diagnostics'
     def install
       version = options[:version] || VERSION
-      board = options[:board] || 'picow'
+      board = options[:board]
+
+      unless board
+        puts "Specify a board with --board / -b. Supported boards:"
+        RuntimeManager::BOARDS.each { |b| puts "  #{b}" }
+        puts
+        puts "Example: prremote install -b esp32c6"
+        return
+      end
+
       unless RuntimeManager::BOARDS.include?(board)
-        raise Thor::Error, "Unknown board '#{board}'. Valid values: #{RuntimeManager::BOARDS.join(', ')}"
+        raise Thor::Error, "Unknown board '#{board}'. Supported boards: #{RuntimeManager::BOARDS.join(', ')}"
       end
 
-      Commands::Install.new(version: version, board: board, port: options[:port]).call
+      Commands::Install.new(version: version, board: board, port: options[:port],
+                            verbose: options[:verbose]).call
     rescue StandardError => e
       raise Thor::Error, e.message
     end

data/lib/prremote/commands/deploy.rb

@@ -43,7 +43,7 @@ module Prremote
       def deploy_to_device(mrb_data, rb_paths)
         serial = Serial.new(@port, @baud)
         wait_for_ready(serial)
-        serial.write(DEPLOY_MAGIC + build_meta_packet(rb_paths) + mrb_data)
+        write_chunked(serial, DEPLOY_MAGIC + build_meta_packet(rb_paths) + mrb_data)
         wait_for_deployed(serial)
       ensure
         serial&.close

data/lib/prremote/commands/install.rb

@@ -3,14 +3,15 @@ require 'fileutils'
 module Prremote
   module Commands
     class Install
-      def initialize(version: VERSION, board: 'picow', port: nil)
+      def initialize(version: VERSION, board: 'picow', port: nil, verbose: false)
         @version = version
-        @board = board
-        @port = port
+        @board   = board
+        @port    = port
+        @verbose = verbose
       end
 
       def call
-        return install_esp32 if @board == 'esp32'
+        return install_esp32 if RuntimeManager::ESP32_BOARDS.include?(@board)
 
         uf2_path = RuntimeManager.fetch(@version, @board)
 
@@ -42,7 +43,7 @@ module Prremote
         raise 'No serial device found. Connect the board or pass --port.' unless port
 
         puts "Flashing #{File.basename(image)} to #{port}..."
-        EspFlasher.flash(port: port, image_path: image)
+        EspFlasher.flash(port: port, image_path: image, board: @board, verbose: @verbose)
         puts "Done. Runtime #{@version} installed."
       end
 

data/lib/prremote/commands/run.rb

@@ -42,7 +42,7 @@ module Prremote
         serial = Serial.new(@port, @baud)
         wait_for_ready(serial)
 
-        serial.write(mrb_data)
+        write_chunked(serial, mrb_data)
         debug "sent #{mrb_data.bytesize} bytes (first 4: #{mrb_data[0, 4].inspect})"
 
         post_running = wait_for_running(serial)

data/lib/prremote/commands/serial_helpers.rb

@@ -34,6 +34,25 @@ module Prremote
         str.gsub("\r\n", "\n").gsub("\r", '')
       end
 
+      # ESP32-C6's native USB Serial/JTAG drops bytes when a large payload is
+      # written in a single burst: its 256-byte driver RX ring buffer overflows
+      # faster than the firmware drains it byte-by-byte, and the controller does
+      # not apply USB backpressure. Writing in <=256-byte chunks with a short
+      # gap keeps the device from overrunning. The pacing is negligible on the
+      # baud-limited transports (Pico USB-CDC / ESP32 UART bridge), where a
+      # 256-byte chunk already takes ~22 ms to clock out at 115200 baud.
+      SERIAL_CHUNK_SIZE  = 256
+      SERIAL_CHUNK_DELAY = 0.004
+
+      def write_chunked(serial, data)
+        i = 0
+        while i < data.bytesize
+          serial.write(data.byteslice(i, SERIAL_CHUNK_SIZE))
+          i += SERIAL_CHUNK_SIZE
+          sleep SERIAL_CHUNK_DELAY if i < data.bytesize
+        end
+      end
+
       # Wraps serial.read so that a device disconnect (e.g. ENXIO on macOS when
       # the Pico resets) surfaces as a human-readable error instead of a bare errno name.
       def safe_read(serial, size)

data/lib/prremote/esp_flasher.rb

@@ -3,20 +3,19 @@ require 'digest'
 require 'rbconfig'
 
 module Prremote
-  # Pure-Ruby ESP32 flasher — speaks the Espressif serial bootloader protocol
-  # directly so `install --board esp32` needs no esptool / Python.
+  # 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.
   #
-  # Talks to the ESP32 (classic) ROM loader only (no stub upload): SYNC,
-  # SPI_ATTACH, SPI_SET_PARAMS, CHANGE_BAUDRATE, FLASH_BEGIN/DATA/END and
-  # SPI_FLASH_MD5 — enough to write a merged image at offset 0x0 and verify it.
   # Protocol reference:
   # https://docs.espressif.com/projects/esptool/en/latest/esp32/advanced-topics/serial-protocol.html
-  #
-  # The chip is put into (and out of) the boot ROM by toggling DTR/RTS through
-  # the USB-UART bridge's auto-reset circuit, via ioctl on the serial fd —
-  # macOS and Linux only.
   class EspFlasher
-    # Command opcodes (ROM loader subset)
+    # Command opcodes
     FLASH_BEGIN    = 0x02
     FLASH_DATA     = 0x03
     FLASH_END      = 0x04
@@ -26,41 +25,58 @@ module Prremote
     CHANGE_BAUD    = 0x0F
     SPI_FLASH_MD5  = 0x13
 
-    FLASH_WRITE_SIZE = 0x400 # ROM loader max data per FLASH_DATA packet
-    STATUS_BYTES     = 4     # ESP32 ROM appends 4 status bytes to responses
+    FLASH_WRITE_SIZE = 0x400 # max data per FLASH_DATA packet
     CHECKSUM_SEED    = 0xEF
+    ROM_BAUD         = 115_200
+
+    # Boards with built-in USB Serial/JTAG — flashed via esptool subprocess.
+    USB_JTAG_SERIAL_BOARDS = %w[esp32c6].freeze
 
-    ROM_BAUD = 115_200
+    # ROM status-byte count: classic ESP32 appends 4 bytes, RISC-V chips 2.
+    STATUS_BYTES_BY_BOARD = Hash.new(4).freeze
+
+    # Classic ESP32 SPI_ATTACH takes [hspi_arg, extended_arg] (8 bytes);
+    # newer RISC-V chips take only [hspi_arg] (4 bytes).
+    SPI_ATTACH_LEGACY_BOARDS = %w[esp32].freeze
+
+    MD5_HEX_LENGTH = 32
+    MD5_RAW_LENGTH = 16
 
     # ioctl modem-control constants
     TIOCM_DTR = 0x0002
     TIOCM_RTS = 0x0004
     DARWIN    = RbConfig::CONFIG['host_os'] =~ /darwin/ ? true : false
     TIOCMGET  = DARWIN ? 0x4004746A : 0x5415
-    TIOCMSET  = DARWIN ? 0x8004746D : 0x5418
+    TIOCMBIS  = DARWIN ? 0x8004746E : 0x5416
+    TIOCMBIC  = DARWIN ? 0x8004746F : 0x5417
 
     class Error < RuntimeError; end
 
-    # Flashes `image_path` at offset 0x0 and verifies it with an on-chip MD5.
-    # The transfer runs at `baud` when rubyserial supports it locally
-    # (macOS termios caps out at 230400), otherwise at the ROM's 115200.
-    def self.flash(port:, image_path:, baud: 230_400)
+    # Entry point.  Routes USB-JTAG/Serial boards through esptool; handles
+    # classic ESP32 with the pure-Ruby protocol implementation.
+    def self.flash(port:, image_path:, baud: 230_400, 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 flash with esptool: ' \
-                     "esptool write_flash 0x0 #{image_path}"
+                     'on other systems use esptool: ' \
+                     "esptool write-flash 0x0 #{image_path}"
       end
 
-      image  = File.binread(image_path)
-      serial = Serial.new(port, ROM_BAUD)
-      flasher = new(serial, fd: serial.instance_variable_get(:@fd))
+      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!
-        serial = flasher.upgrade_baud(port, baud) if baud != ROM_BAUD && baud_supported?(baud)
+        upgrade = baud != ROM_BAUD && baud_supported?(baud)
+        serial = flasher.upgrade_baud(port, baud) if upgrade
         flasher.write_flash(image, offset: 0)
-        # Verify before FLASH_END: the ROM loader has been seen going quiet
-        # after that command, while MD5 right after the last block is reliable.
         flasher.verify_md5(image, offset: 0)
         flasher.finish_flash
         flasher.hard_reset
@@ -69,28 +85,89 @@ module Prremote
       end
     end
 
-    # The local termios layer must support the baud before CHANGE_BAUDRATE is
-    # sent to the chip — once the chip switches, there is no way back without
-    # a re-sync, so never request a speed we cannot reopen at.
     def self.baud_supported?(baud)
       RubySerial::Posix::BAUDE_RATES.key?(baud)
     rescue NameError
       false
     end
 
-    # `serial` needs #read/#write; `fd` enables DTR/RTS control and may be
-    # nil in tests.
-    def initialize(serial, fd: nil)
-      @serial = serial
-      @fd     = fd
-      @rxbuf  = +''.b
+    # 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.
+    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
 
-    # ── chip reset control (DTR/RTS via the auto-download circuit) ────────
+    # 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).
+    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
 
+    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
+
+    # ── instance ──────────────────────────────────────────────────────────
+
+    # `serial` needs #read/#write; `fd` enables DTR/RTS control.
+    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
+
+    # Classic auto-reset: RTS→EN, DTR→IO0 (via external UART bridge).
     def enter_bootloader
-      # esptool's "classic reset": hold EN low, release it with IO0 low so
-      # the chip starts the ROM loader, then release IO0.
       set_lines(dtr: false, rts: true)
       sleep 0.1
       set_lines(dtr: true, rts: false)
@@ -108,27 +185,28 @@ module Prremote
 
     def sync!
       payload = [0x07, 0x07, 0x12, 0x20].pack('C4') + ([0x55] * 32).pack('C32')
-      synced = 8.times.any? do
+      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
+        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 ESP32 boot ROM' unless synced
+      raise Error, 'could not sync with the ESP boot ROM' unless synced
     end
 
-    # CHANGE_BAUDRATE, then reopen the port at the new speed. Plain open does
-    # not touch DTR/RTS (verified with rubyserial), so the chip stays in the
-    # bootloader across the reopen.
+    # CHANGE_BAUDRATE, then reopen the port at the new speed.
     def upgrade_baud(port, baud)
       command(CHANGE_BAUD, [baud, 0].pack('V2'))
       @serial.close
       sleep 0.05
-      serial = Serial.new(port, baud)
+      serial  = Serial.new(port, baud)
       @serial = serial
       @fd     = serial.instance_variable_get(:@fd)
       @rxbuf.clear
@@ -136,36 +214,33 @@ module Prremote
     end
 
     def write_flash(image, offset: 0)
-      command(SPI_ATTACH, [0, 0].pack('V2'))
-      # 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
-      # The ROM erases the region inside FLASH_BEGIN; allow ~30 s per MB.
-      erase_timeout = 30 * (1 + (image.bytesize / (1024 * 1024)))
-      command(FLASH_BEGIN,
-              [image.bytesize, blocks, FLASH_WRITE_SIZE, offset].pack('V4'),
+      spi_attach_payload = SPI_ATTACH_LEGACY_BOARDS.include?(@board) ? [0, 0].pack('V2') : [0].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
 
-    # Every block is already committed once its FLASH_DATA is acked, so
-    # FLASH_END is only a courtesy "done" (we leave the loader via hard_reset
-    # anyway). The ESP32 ROM has been seen answering it with error 0x06 —
-    # ignore it; the MD5 check is the source of truth.
+    # FLASH_END is a courtesy; hard_reset resets the chip anyway.
+    # The ROM has been seen returning error 0x06 here — ignore it.
     def finish_flash
-      command(FLASH_END, [1].pack('V')) # 1 = stay in the loader
+      command(FLASH_END, [1].pack('V'))
     rescue Error
       nil
     end
 
     def verify_md5(image, offset: 0)
-      timeout = 8 * (1 + (image.bytesize / (1024 * 1024)))
-      _value, data = command(SPI_FLASH_MD5,
-                             [offset, image.bytesize, 0, 0].pack('V4'),
-                             timeout: timeout)
-      device_md5 = data[0, 32] # the ROM loader answers as 32 hex chars
+      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
 
@@ -174,8 +249,6 @@ module Prremote
 
     # ── request/response plumbing ──────────────────────────────────────────
 
-    # Sends one command packet and waits for its response.
-    # Returns [value, data] from the response (status bytes stripped).
     def command(op, payload, checksum: 0, timeout: 3)
       packet = [0x00, op, payload.bytesize].pack('CCv') +
                [checksum].pack('V') + payload
@@ -206,6 +279,10 @@ module Prremote
 
     private
 
+    def vlog(msg)
+      warn "[flash] #{msg}" if @verbose
+    end
+
     def stream_blocks(image, blocks)
       blocks.times do |seq|
         block = image.byteslice(seq * FLASH_WRITE_SIZE, FLASH_WRITE_SIZE)
@@ -218,25 +295,21 @@ module Prremote
       $stderr.print "\n"
     end
 
-    # Returns [value, data] when the frame is the response to `op`, raises on
-    # an error status, and returns nil for unrelated frames (stale responses).
     def parse_response(frame, op)
-      return nil if frame.bytesize < 8 + STATUS_BYTES || frame.getbyte(0) != 0x01 ||
+      return nil if frame.bytesize < 8 + @status_bytes || frame.getbyte(0) != 0x01 ||
                     frame.getbyte(1) != op
 
       value  = frame.byteslice(4, 4).unpack1('V')
       body   = frame.byteslice(8..)
-      status = body.byteslice(-STATUS_BYTES, STATUS_BYTES)
+      status = body.byteslice(-@status_bytes, @status_bytes)
       if status.getbyte(0) != 0
         raise Error, format('command 0x%<op>02x failed (error 0x%<err>02x)',
                             op: op, err: status.getbyte(1))
       end
 
-      [value, body.byteslice(0...-STATUS_BYTES)]
+      [value, body.byteslice(0...-@status_bytes)]
     end
 
-    # Reads from the serial port until a complete 0xC0 ... 0xC0 frame is
-    # available or the deadline passes. Returns the decoded frame or nil.
     def read_frame(deadline)
       loop do
         start = @rxbuf.index("\xC0".b)
@@ -245,7 +318,7 @@ module Prremote
           if stop
             frame = @rxbuf.byteslice((start + 1)...stop)
             @rxbuf = @rxbuf.byteslice((stop + 1)..) || +''.b
-            next if frame.empty? # back-to-back C0 markers
+            next if frame.empty?
 
             return slip_decode(frame)
           end
@@ -257,8 +330,6 @@ module Prremote
       end
     end
 
-    # The ROM answers a successful SYNC with a burst of identical responses;
-    # swallow them so they are not mistaken for the next command's reply.
     def drain_responses
       deadline = Time.now + 0.3
       loop { break if read_frame(deadline).nil? }
@@ -268,12 +339,10 @@ module Prremote
       return if @fd.nil?
 
       io = IO.for_fd(@fd, autoclose: false)
-      buf = [0].pack('L')
-      io.ioctl(TIOCMGET, buf)
-      bits = buf.unpack1('L')
-      bits = dtr ? (bits | TIOCM_DTR) : (bits & ~TIOCM_DTR)
-      bits = rts ? (bits | TIOCM_RTS) : (bits & ~TIOCM_RTS)
-      io.ioctl(TIOCMSET, [bits].pack('L'))
+      io.ioctl(dtr ? TIOCMBIS : TIOCMBIC, [TIOCM_DTR].pack('L'))
+      io.ioctl(rts ? TIOCMBIS : TIOCMBIC, [TIOCM_RTS].pack('L'))
+    rescue StandardError
+      nil
     end
 
     def progress(done, total)

data/lib/prremote/runtime_manager.rb

@@ -4,13 +4,14 @@ require 'fileutils'
 
 module Prremote
   module RuntimeManager
-    BOARDS = %w[pico picow esp32].freeze
+    BOARDS = %w[pico picow esp32 esp32c6].freeze
+    ESP32_BOARDS = %w[esp32 esp32c6].freeze
 
-    # Pico boards ship as UF2 (copied to the BOOTSEL drive); ESP32 ships as a
-    # single merged .bin (bootloader + partition table + app) flashed at 0x0
-    # with esptool.
+    # Pico boards ship as UF2 (copied to the BOOTSEL drive); ESP32 family ships
+    # as a single merged .bin (bootloader + partition table + app) flashed at
+    # 0x0 with esptool.
     def self.artifact_filename(version, board)
-      ext = board == 'esp32' ? 'bin' : 'uf2'
+      ext = ESP32_BOARDS.include?(board) ? 'bin' : 'uf2'
       "prremote-#{board}-runtime-#{version}.#{ext}"
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prremote
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - ITO Yosei
@@ -139,7 +139,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: CLI tool for deploying and running mruby/c scripts on a Raspberry Pi Pico
   W over USB serial