prremote 0.1.7 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b55c090d4bddcdac18b7a1166429af025eeecc0416e31dedf51f248b4d2cd975
-  data.tar.gz: c81096a50e22d31064a8f721daca2de89dcfc5ccbb6e6c9d2d3fb58973c85ac0
+  metadata.gz: 5c315e2104e35b23c87d7565249c2695f0bc8b9f7d0075564dda98b8fcc11491
+  data.tar.gz: 3e8ae2b89ca93b33f7830d45413dadef6f7c2d1d0a19d51499649214d626f1a6
 SHA512:
-  metadata.gz: 8d959c616f0205f2e63f9ba8eba7d96f66943822e1e59be4dc41cb58aed070fabe816ff1473a6cbee7057bdc19533274dbf8c0c2a5e04924d354bcaae54653db
-  data.tar.gz: 9a1fd33542e02a7a97f0e0a9d9626e3f688d80cf3027ff975de58e2159defc90fa3880a9611cb35b125359c7fc8d36ed3708e517673e16795ac3e8cb6a1d566a
+  metadata.gz: 8bc5946b3d296fd7cfac88817b7e212f9713b13fa4a1f1748cacf84e278b0e269b0552f46b9eb0804e2ca319e50fd9e1bb48a4d81583c96f21bbcf468aa9d735
+  data.tar.gz: 8a467d706edf4600859d7563ab4dae1a29efd3eaaeff7d4f274d0be57412129eb44777fe099620733d0e773b0d17517751c7cb41e76714655803e038e8c5629a

data/README.md

@@ -2,7 +2,7 @@
 
 > ⚠️ This project is in early development. APIs and commands are subject to change.
 
-**prremote** is a command-line tool for deploying and running Ruby scripts on a Raspberry Pi Pico W over USB serial. It ships a minimal [mruby/c](https://github.com/mrubyc/mrubyc) runtime firmware and lets you compile and send `.rb` files from your Mac or Linux machine directly to the device.
+**prremote** is a command-line tool for deploying and running Ruby scripts on a Raspberry Pi Pico W or ESP32 (e.g. M5Stack) over USB serial. It ships a minimal [mruby/c](https://github.com/mrubyc/mrubyc) runtime firmware and lets you compile and send `.rb` files from your Mac or Linux machine directly to the device.
 
 Inspired by [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html) for MicroPython.
 
@@ -17,7 +17,10 @@ Inspired by [mpremote](https://docs.micropython.org/en/latest/reference/mpremote
 ## Requirements
 
 - Ruby 3.4 or later
-- Raspberry Pi Pico W
+- Supported boards:
+  - Raspberry Pi Pico W / Pico
+  - ESP32 (classic) — e.g. M5GO / M5Stack Core gen1, generic dev boards
+  - ESP32-C6 (RISC-V) — e.g. Seeed Studio XIAO ESP32C6
 - `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)
@@ -54,18 +57,24 @@ prremote run app.rb
 
 ### `install`
 
-Flash the prremote runtime firmware to a Pico W or Pico.
+Flash the prremote runtime firmware to a supported board.
 
 ```bash
-prremote install                          # Pico W (default)
-prremote install --board pico             # Pico (no wireless)
-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.
 
-Put the device into BOOTSEL mode (hold BOOTSEL, connect USB, release) when prompted.
+Pico boards: put the device into BOOTSEL mode (hold BOOTSEL, connect USB, release) when prompted.
+
+ESP32 / ESP32-C6 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.
 
 ---
 
@@ -86,7 +95,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/).
 
 ---
 
@@ -163,8 +172,8 @@ Show the gem version, mrbc version, and the connected device's runtime version.
 
 ```bash
 prremote version
-# prremote: 0.1.7
-# runtime:  0.1.7 (/dev/tty.usbmodem101)
+# prremote: 0.2.1
+# runtime:  0.2.1 (/dev/tty.usbmodem101)
 # mrbc: mruby 4.0.0 (2026-04-20) (/opt/homebrew/bin/mrbc)
 ```
 
@@ -175,7 +184,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`) |
 
 ---
 
@@ -183,7 +192,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)
@@ -209,7 +218,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 and WiFi (CYW43) C bindings are available in Ruby code running on the device.
+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.
 
 ---
 
@@ -232,11 +241,29 @@ git submodule update --init --recursive
 
 ### Build the runtime firmware
 
-Requires the ARM cross-compiler (`arm-none-eabi-gcc`) and CMake.
+Pico boards require the ARM cross-compiler (`arm-none-eabi-gcc`) and CMake.
+
+```bash
+cd runtime/
+rake build   # UF2 for pico and picow
+```
+
+The ESP32 runtime requires ESP-IDF v5.3, which is not vendored (it is several
+GB and installs its own toolchains). One-time setup:
+
+```bash
+mkdir -p ~/sources/esp
+git clone -b v5.3.2 --recursive --shallow-submodules \
+    https://github.com/espressif/esp-idf.git ~/sources/esp/esp-idf
+cd ~/sources/esp/esp-idf && ./install.sh esp32
+```
+
+Then (set `IDF_PATH` if you installed somewhere else):
 
 ```bash
 cd runtime/
-rake cache   # build UF2 for pico and picow → ~/.prremote/runtime/
+rake build:esp32   # merged .bin for esp32
+rake cache         # build all boards → ~/.prremote/runtime/
 ```
 
 ### Run the tests
@@ -258,3 +285,7 @@ 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)
+
+https://wiki.seeedstudio.com/ja/xiao_esp32c6_getting_started/
+
+brew install esptool

data/VERSION

@@ -1 +1 @@
-0.1.7
+0.2.1

data/lib/prremote/cli.rb

@@ -3,6 +3,7 @@ require 'rubyserial'
 require_relative 'version'
 require_relative 'detector'
 require_relative 'mrbc'
+require_relative 'esp_flasher'
 require_relative 'runtime_manager'
 require_relative 'commands/install'
 require_relative 'commands/deploy'
@@ -15,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
@@ -23,17 +24,30 @@ module Prremote
 
     remove_command :tree
 
-    desc 'install', 'Flash prremote runtime firmware to Pico W or Pico'
+    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: pico or picow (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).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,12 +3,16 @@ require 'fileutils'
 module Prremote
   module Commands
     class Install
-      def initialize(version: VERSION, board: 'picow')
+      def initialize(version: VERSION, board: 'picow', port: nil, verbose: false)
         @version = version
-        @board = board
+        @board   = board
+        @port    = port
+        @verbose = verbose
       end
 
       def call
+        return install_esp32 if RuntimeManager::ESP32_BOARDS.include?(@board)
+
         uf2_path = RuntimeManager.fetch(@version, @board)
 
         device_label = @board == 'picow' ? 'Pico W' : 'Pico'
@@ -31,6 +35,18 @@ module Prremote
 
       private
 
+      # No BOOTSEL dance on ESP32: the flasher toggles DTR/RTS to enter the
+      # boot ROM by itself, so flashing works over the normal serial port.
+      def install_esp32
+        image = RuntimeManager.fetch(@version, @board)
+        port  = @port || Detector.find_device
+        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, board: @board, verbose: @verbose)
+        puts "Done. Runtime #{@version} installed."
+      end
+
       def volume_paths
         [
           '/Volumes/RPI-RP2',

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

@@ -5,11 +5,15 @@ module Prremote
         # On macOS, USB CDC TX buffers can be dropped when the host reopens the port,
         # leaving the device stuck in getchar() without re-sending READY.
         # Sending Ctrl+C forces the device to restart its READY loop.
+        # Resent every second: ESP32 boards reset when the port opens (DTR/RTS
+        # auto-reset circuit) and a Ctrl+C sent while they are still booting
+        # is lost. Harmless on Pico — 0x03 while idle just re-prints READY.
         sleep 0.1
         serial.write("\x03") rescue nil
 
         buf = +''
-        deadline = Time.now + 10
+        deadline  = Time.now + 10
+        next_ctrl = Time.now + 1
         loop do
           buf << normalize(safe_read(serial, 256))
           if buf.include?('READY ')
@@ -18,6 +22,10 @@ module Prremote
           end
           raise 'Timeout waiting for device. Run `prremote reset` if a script is running.' if Time.now > deadline
 
+          if Time.now > next_ctrl
+            serial.write("\x03") rescue nil
+            next_ctrl = Time.now + 1
+          end
           sleep 0.05
         end
       end
@@ -26,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/detector.rb

@@ -2,7 +2,16 @@ require 'rbconfig'
 
 module Prremote
   class Detector
-    R2P2_VENDOR_IDS = %w[2e8a].freeze # Raspberry Pi USB VID
+    # Known USB vendor IDs → device label and the macOS port-name pattern.
+    # Pico exposes native USB CDC (usbmodem); ESP32 boards sit behind a
+    # USB-UART bridge (usbserial): CP210x on M5GO/M5Stack, CH910x on newer
+    # revisions.
+    KNOWN_VENDORS = {
+      '2e8a' => { label: 'Pico (prremote/R2P2)', macos: /usbmodem/ },
+      '10c4' => { label: 'ESP32 (CP210x)',       macos: /usbserial/ },
+      '1a86' => { label: 'ESP32 (CH910x)',       macos: /usbserial/ }
+    }.freeze
+    R2P2_VENDOR_IDS = %w[2e8a].freeze # Raspberry Pi USB VID (kept for compat)
 
     def self.find_device
       new.find_device
@@ -12,14 +21,13 @@ module Prremote
       candidates = serial_ports
       return candidates.first if candidates.size == 1
 
-      r2p2 = candidates.select { |p| r2p2_port?(p) }
-      r2p2.first || candidates.first
+      known = candidates.select { |p| known_port?(p) }
+      known.first || candidates.first
     end
 
     def list_devices
       serial_ports.map do |port|
-        label = r2p2_port?(port) ? 'R2P2/PicoRuby' : 'unknown'
-        { port: port, label: label }
+        { port: port, label: port_label(port) || 'unknown' }
       end
     end
 
@@ -45,23 +53,37 @@ module Prremote
       end
     end
 
-    def r2p2_port?(port)
-      # On macOS/Linux, check sysfs or ioreg for the Raspberry Pi VID
+    def known_port?(port)
+      !port_label(port).nil?
+    end
+
+    def port_label(port)
+      # On macOS/Linux, check ioreg or sysfs for a known vendor ID
       case RbConfig::CONFIG['host_os']
       when /darwin/
-        ioreg_output = `ioreg -p IOUSB -l 2>/dev/null`
-        R2P2_VENDOR_IDS.any? { |vid| ioreg_output.include?(vid) } &&
-          port.match?(/usbmodem/)
+        KNOWN_VENDORS.each do |vid, info|
+          return info[:label] if usb_vendor_ids.include?(vid) && port.match?(info[:macos])
+        end
+        nil
       when /linux/
         port_name = File.basename(port)
         vid_path = "/sys/class/tty/#{port_name}/device/../../../idVendor"
-        return false unless File.exist?(vid_path)
+        return nil unless File.exist?(vid_path)
 
         vid = File.read(vid_path).strip.downcase
-        R2P2_VENDOR_IDS.include?(vid)
-      else
-        false
+        KNOWN_VENDORS.dig(vid, :label)
       end
     end
+
+    # Vendor IDs of all connected USB devices as 4-digit hex strings.
+    # ioreg prints idVendor in decimal (e.g. 4292 for 0x10c4).
+    def usb_vendor_ids
+      @usb_vendor_ids ||= ioreg_usb.scan(/"idVendor" = (\d+)/)
+                                   .map { |(dec)| format('%04x', dec.to_i) }
+    end
+
+    def ioreg_usb
+      @ioreg_usb ||= `ioreg -p IOUSB -l 2>/dev/null`
+    end
   end
 end

data/lib/prremote/esp_flasher.rb

@@ -0,0 +1,336 @@
+require 'rubyserial'
+require 'digest'
+require 'rbconfig'
+
+module Prremote
+  # 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
+  class EspFlasher
+    # Command opcodes
+    FLASH_BEGIN    = 0x02
+    FLASH_DATA     = 0x03
+    FLASH_END      = 0x04
+    SYNC           = 0x08
+    SPI_SET_PARAMS = 0x0B
+    SPI_ATTACH     = 0x0D
+    CHANGE_BAUD    = 0x0F
+    SPI_FLASH_MD5  = 0x13
+
+    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 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
+    TIOCMBIS  = DARWIN ? 0x8004746E : 0x5416
+    TIOCMBIC  = DARWIN ? 0x8004746F : 0x5417
+
+    class Error < RuntimeError; end
+
+    # 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 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
+
+    def self.baud_supported?(baud)
+      RubySerial::Posix::BAUDE_RATES.key?(baud)
+    rescue NameError
+      false
+    end
+
+    # 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
+
+      warn ''
+      warn 'Put the board in bootloader mode while "Connecting..." is shown:'
+      warn '  XIAO ESP32C6: hold BOOT, press RST, release both.'
+
+      cmd = [*esptool,
+             '--chip', board, '--port', port,
+             '--before', 'no-reset', '--after', 'no-reset',
+             'write-flash', '0x0', image_path]
+      warn "[flash] #{cmd.join(' ')}" if verbose
+      system(*cmd) or raise Error, 'esptool exited with an error'
+
+      warn ''
+      warn 'Flash complete. Press RST to start the firmware.'
+    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
+      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
+
+    def hard_reset
+      set_lines(dtr: false, rts: true)
+      sleep 0.1
+      set_lines(dtr: false, rts: false)
+    end
+
+    # ── protocol steps ─────────────────────────────────────────────────────
+
+    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
+
+    # 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
+      @fd     = serial.instance_variable_get(:@fd)
+      @rxbuf.clear
+      serial
+    end
+
+    def write_flash(image, offset: 0)
+      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
+
+    # 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'))
+    rescue Error
+      nil
+    end
+
+    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
+
+    # ── request/response plumbing ──────────────────────────────────────────
+
+    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
+
+    def checksum(data)
+      data.bytes.reduce(CHECKSUM_SEED) { |acc, b| acc ^ b }
+    end
+
+    def slip_encode(packet)
+      escaped = packet.gsub("\xDB".b, "\xDB\xDD".b).gsub("\xC0".b, "\xDB\xDC".b)
+      "\xC0".b + escaped + "\xC0".b
+    end
+
+    def slip_decode(frame)
+      frame.gsub("\xDB\xDC".b, "\xC0".b).gsub("\xDB\xDD".b, "\xDB".b)
+    end
+
+    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)
+        block += "\xFF".b * (FLASH_WRITE_SIZE - block.bytesize)
+        command(FLASH_DATA,
+                [block.bytesize, seq, 0, 0].pack('V4') + block,
+                checksum: checksum(block), timeout: 5)
+        progress(seq + 1, blocks)
+      end
+      $stderr.print "\n"
+    end
+
+    def parse_response(frame, op)
+      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)
+      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)]
+    end
+
+    def read_frame(deadline)
+      loop do
+        start = @rxbuf.index("\xC0".b)
+        if start
+          stop = @rxbuf.index("\xC0".b, start + 1)
+          if stop
+            frame = @rxbuf.byteslice((start + 1)...stop)
+            @rxbuf = @rxbuf.byteslice((stop + 1)..) || +''.b
+            next if frame.empty?
+
+            return slip_decode(frame)
+          end
+        end
+        return nil if Time.now > deadline
+
+        chunk = @serial.read(256) || ''
+        chunk.empty? ? sleep(0.01) : @rxbuf << chunk.b
+      end
+    end
+
+    def drain_responses
+      deadline = Time.now + 0.3
+      loop { break if read_frame(deadline).nil? }
+    end
+
+    def set_lines(dtr:, rts:)
+      return if @fd.nil?
+
+      io = IO.for_fd(@fd, autoclose: false)
+      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)
+      pct = done * 100 / total
+      return if pct == @last_pct
+
+      @last_pct = pct
+      $stderr.print format("\rWriting %<pct>3d%% (%<done>d/%<total>d)",
+                           pct: pct, done: done, total: total)
+    end
+  end
+end

data/lib/prremote/runtime_manager.rb

@@ -4,14 +4,19 @@ require 'fileutils'
 
 module Prremote
   module RuntimeManager
-    BOARDS = %w[pico picow].freeze
-
-    def self.uf2_filename(version, board)
-      "prremote-#{board}-runtime-#{version}.uf2"
+    BOARDS = %w[pico picow esp32 esp32c6].freeze
+    ESP32_BOARDS = %w[esp32 esp32c6].freeze
+
+    # 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 = ESP32_BOARDS.include?(board) ? 'bin' : 'uf2'
+      "prremote-#{board}-runtime-#{version}.#{ext}"
     end
 
     def self.release_url(version, board)
-      "https://github.com/lumbermill/prremote/releases/download/runtime-#{version}/#{uf2_filename(version, board)}"
+      "https://github.com/lumbermill/prremote/releases/download/runtime-#{version}/#{artifact_filename(version, board)}"
     end
 
     def self.cache_dir
@@ -19,7 +24,7 @@ module Prremote
     end
 
     def self.cached_path(version, board)
-      File.join(cache_dir, uf2_filename(version, board))
+      File.join(cache_dir, artifact_filename(version, board))
     end
 
     def self.fetch(version, board)
@@ -27,7 +32,7 @@ module Prremote
       return path if File.exist?(path)
 
       FileUtils.mkdir_p(cache_dir)
-      $stderr.print "Downloading #{uf2_filename(version, board)}..."
+      $stderr.print "Downloading #{artifact_filename(version, board)}..."
       $stderr.flush
       download(release_url(version, board), path)
       warn ' done.'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prremote
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.2.1
 platform: ruby
 authors:
 - ITO Yosei
@@ -116,6 +116,7 @@ files:
 - lib/prremote/commands/undeploy.rb
 - lib/prremote/commands/watch.rb
 - lib/prremote/detector.rb
+- lib/prremote/esp_flasher.rb
 - lib/prremote/mrbc.rb
 - lib/prremote/runtime_manager.rb
 - lib/prremote/version.rb
@@ -138,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