prremote 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c315e2104e35b23c87d7565249c2695f0bc8b9f7d0075564dda98b8fcc11491
-  data.tar.gz: 3e8ae2b89ca93b33f7830d45413dadef6f7c2d1d0a19d51499649214d626f1a6
+  metadata.gz: ddaba1909af7ae567dda45d75d78c240347062d0e00a5dab966190b22f0b28eb
+  data.tar.gz: e9f933d93ca77aa8324f2502958150370afe8f61b902c4420d06cfeb3edfcabd
 SHA512:
-  metadata.gz: 8bc5946b3d296fd7cfac88817b7e212f9713b13fa4a1f1748cacf84e278b0e269b0552f46b9eb0804e2ca319e50fd9e1bb48a4d81583c96f21bbcf468aa9d735
-  data.tar.gz: 8a467d706edf4600859d7563ab4dae1a29efd3eaaeff7d4f274d0be57412129eb44777fe099620733d0e773b0d17517751c7cb41e76714655803e038e8c5629a
+  metadata.gz: d885014b3034e5bcbb02203f12c994544a147f5d2439af7fd2162f39591104ce220f697732e6a62a455374508f62fa8685eb2a2f4d9e67f8593d83b9ec4676db
+  data.tar.gz: dc99149a4481721d2347f73345684ff1dd780a9ce96e4f861376a3077e0cce5be11a3be6598e4728cf1659bab1403e9678248ab7ffbce2c17091db9e08fd2695

data/README.md

@@ -18,9 +18,9 @@ Inspired by [mpremote](https://docs.micropython.org/en/latest/reference/mpremote
 
 - Ruby 3.4 or later
 - 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
+  - [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)
@@ -74,7 +74,11 @@ The firmware is downloaded from GitHub Releases on first use and cached in `~/.p
 
 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.
+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.
 
 ---
 
@@ -128,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"
 ```
 
 ---
@@ -172,8 +176,8 @@ Show the gem version, mrbc version, and the connected device's runtime version.
 
 ```bash
 prremote version
-# prremote: 0.2.1
-# runtime:  0.2.1 (/dev/tty.usbmodem101)
+# prremote: 0.3.1
+# runtime:  0.3.1 (/dev/tty.usbmodem101)
 # mrbc: mruby 4.0.0 (2026-04-20) (/opt/homebrew/bin/mrbc)
 ```
 
@@ -218,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.
 
 ---
 
@@ -284,8 +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)
-
-https://wiki.seeedstudio.com/ja/xiao_esp32c6_getting_started/
-
-brew install esptool
+- [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html) — MicroPython equivalent (inspiration)

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.3.1

data/lib/prremote/esp_flasher.rb

@@ -20,6 +20,7 @@ module Prremote
     FLASH_DATA     = 0x03
     FLASH_END      = 0x04
     SYNC           = 0x08
+    READ_REG       = 0x0A
     SPI_SET_PARAMS = 0x0B
     SPI_ATTACH     = 0x0D
     CHANGE_BAUD    = 0x0F
@@ -32,6 +33,16 @@ module Prremote
     # Boards with built-in USB Serial/JTAG — flashed via esptool subprocess.
     USB_JTAG_SERIAL_BOARDS = %w[esp32c6].freeze
 
+    # 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).
+    EFUSE_RD_REG_BASE          = 0x3FF5A000
+    EFUSE_BLK0_RDATA3_REG_OFFS = EFUSE_RD_REG_BASE + 0x00C
+    EFUSE_BLK0_RDATA5_REG_OFFS = EFUSE_RD_REG_BASE + 0x014
+
     # ROM status-byte count: classic ESP32 appends 4 bytes, RISC-V chips 2.
     STATUS_BYTES_BY_BOARD = Hash.new(4).freeze
 
@@ -47,14 +58,13 @@ module Prremote
     TIOCM_RTS = 0x0004
     DARWIN    = RbConfig::CONFIG['host_os'] =~ /darwin/ ? true : false
     TIOCMGET  = DARWIN ? 0x4004746A : 0x5415
-    TIOCMBIS  = DARWIN ? 0x8004746E : 0x5416
-    TIOCMBIC  = DARWIN ? 0x8004746F : 0x5417
+    TIOCMSET  = DARWIN ? 0x8004746D : 0x5418
 
     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)
+    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)
@@ -104,21 +114,42 @@ module Prremote
         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 'Put the board in bootloader mode while "Connecting..." is shown:'
+      warn "Couldn't reset #{board} automatically. Put it in bootloader mode by hand:"
       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 '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
 
+    # 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|
@@ -193,7 +224,8 @@ module Prremote
     end
 
     def write_flash(image, offset: 0)
-      spi_attach_payload = SPI_ATTACH_LEGACY_BOARDS.include?(@board) ? [0, 0].pack('V2') : [0].pack('V')
+      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'))
@@ -226,6 +258,30 @@ module Prremote
       raise Error, "MD5 mismatch after flashing (device #{device_md5}, local #{local_md5})"
     end
 
+    # 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.
+    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
+
+    def read_reg(addr)
+      value, = command(READ_REG, [addr].pack('V'))
+      value
+    end
+
     # ── request/response plumbing ──────────────────────────────────────────
 
     def command(op, payload, checksum: 0, timeout: 3)
@@ -314,12 +370,21 @@ module Prremote
       loop { break if read_frame(deadline).nil? }
     end
 
+    # Sets DTR and RTS together via a single TIOCMSET, matching esptool's
+    # UnixTightReset. Two separate TIOCMBIS/TIOCMBIC calls (the classic-reset
+    # approach) send DTR and RTS as separate USB control-line-state requests;
+    # some USB-serial adapters (seen with CP2104 on M5StickC PLUS) glitch the
+    # boot ROM's auto-reset during that gap.
     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'))
+      io  = IO.for_fd(@fd, autoclose: false)
+      buf = [0].pack('L')
+      io.ioctl(TIOCMGET, buf)
+      status = buf.unpack1('L')
+      status = dtr ? (status | TIOCM_DTR) : (status & ~TIOCM_DTR)
+      status = rts ? (status | TIOCM_RTS) : (status & ~TIOCM_RTS)
+      io.ioctl(TIOCMSET, [status].pack('L'))
     rescue StandardError
       nil
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prremote
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 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.10
+rubygems_version: 4.0.19
 specification_version: 4
 summary: CLI tool for deploying and running mruby/c scripts on a Raspberry Pi Pico
   W over USB serial