prremote 0.4.1 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa8044b474d22090a340385b2995d1e242b3aa44f820e0f7dbd3486b4b141a77
-  data.tar.gz: 9af86c303d859f714b0f566d1910f200d1e3c70a5e56b8b9e799d61299c10aa6
+  metadata.gz: 27b1b34fbd6bbb46d3adb571005dafe869b286b7bc2babc547af1c72cd7f9cd6
+  data.tar.gz: 6f35395ede42d344d2b5de27502fe20631551a94ba1c6ea115abefccd4cda9d0
 SHA512:
-  metadata.gz: ab718d4431f723ed4af6d17ad744654bf547cf167afa7f1e5bd60aebb96c2d7bd6470a14898a769c7660a5c959331dff5a71527297b4245e9418abe02511c727
-  data.tar.gz: 220d6bf77f25475dd25ecf84ffd09a06ae592469e6c2bc90e4af117086b44a5f408ae90a75666d3cd26a79b38b1fd9832f1470cccd838c9edd4bf54176786ec6
+  metadata.gz: 9097fa9e4df160a9bf2bf4b4667d56a0fc3c8600e359d568b9aa028a9f3affb899b3e7a7ad2f9ae0204b824df378cbaa4f6c2935214807b504d70d59014eeee7
+  data.tar.gz: 0be3d04ce9b4bd1b07cb1d690b4a844d33c9f6e76c6594b270714214eef1c9662a2eb2151d26ee1e1123a8c6ea0c6c8b8b11caf552d1f62901d5cdd394a2038f

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 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.
+**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, Linux or WSL2 machine directly to the device.
 
 Inspired by [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html) for MicroPython.
 
@@ -17,8 +17,10 @@ Inspired by [mpremote](https://docs.micropython.org/en/latest/reference/mpremote
 ## Requirements
 
 - Ruby 3.4 or later
+- Supported hosts: macOS, Linux, and WSL2 — see [WSL](#wsl) for the extra setup WSL needs
 - Supported boards:
   - [Raspberry Pi Pico W](https://www.raspberrypi.com/products/raspberry-pi-pico-w/) / [Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/)
+  - [Raspberry Pi Pico 2](https://www.raspberrypi.com/products/raspberry-pi-pico-2/) (RP2350) — `install` not yet verified on real hardware; reports welcome
   - ESP32 (classic) — e.g. [M5GO / M5Stack Core gen1](https://docs.m5stack.com/en/core/m5go), [M5StickC PLUS](https://docs.m5stack.com/en/core/m5stickc_plus), 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/)
   - Per-board feature status (GPIO / ADC / PWM / I2C / SPI / WiFi / sockets / LCD / IR): [docs/SUPPORT.md](docs/SUPPORT.md)
@@ -64,6 +66,7 @@ Flash the prremote runtime firmware to a supported board.
 prremote install                          # show supported boards
 prremote install -b picow                 # Pico W
 prremote install -b pico                  # Pico (no wireless)
+prremote install -b pico2                 # Pico 2 (RP2350)
 prremote install -b esp32                 # ESP32 (M5GO / M5Stack Core, etc.)
 prremote install -b m5stickc_plus         # M5StickC PLUS (esp32 runtime + board library)
 prremote install -b esp32c6               # ESP32-C6 (e.g. XIAO ESP32C6)
@@ -74,7 +77,7 @@ prremote install -b picow --version 0.1.1 # specify a runtime version
 
 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.
+Pico boards: if the board is already running the prremote runtime, `install` reboots it into BOOTSEL mode by itself (a 1200 bps touch on its serial port). Otherwise — a fresh board, or one running something else — put it into BOOTSEL mode (hold BOOTSEL, connect USB, release) when prompted. The drive appears as `RPI-RP2` on Pico / Pico W and as `RP2350` on Pico 2.
 
 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).
 
@@ -180,13 +183,48 @@ Show the gem version, mrbc version, and the connected device's runtime version.
 
 ```bash
 prremote version
-# prremote: 0.4.1
-# runtime:  0.4.1 board=picow (/dev/tty.usbmodem101)
+# prremote: 0.4.3
+# runtime:  0.4.3 board=picow (/dev/tty.usbmodem101)
 # mrbc: mruby 4.0.0 (2026-04-20) (/opt/homebrew/bin/mrbc)
 ```
 
 ---
 
+## WSL
+
+prremote runs under WSL2, but two things are not automatic there.
+
+**USB serial devices are not forwarded.** WSL2 does not pass USB through to the guest, so a board Windows sees perfectly well has no `/dev/ttyACM*` on the Linux side. Install [usbipd-win](https://github.com/dorssel/usbipd-win) on the Windows side and attach the board:
+
+```powershell
+winget install --exact dorssel.usbipd-win
+usbipd list                              # note the BUSID of your board
+usbipd bind --busid <BUSID>              # once, as Administrator
+usbipd attach --wsl --busid <BUSID>      # after every reconnect
+```
+
+Then, in WSL:
+
+```bash
+prremote list        # /dev/ttyACM0 should now show up
+```
+
+If the port is there but cannot be opened, add yourself to the `dialout` group (`sudo usermod -aG dialout $USER`) and restart WSL with `wsl --shutdown`.
+
+**Removable drives are not mounted.** For Pico boards, the BOOTSEL volume arrives as a Windows drive letter, which WSL does not mount on its own. Mount it before running `install`:
+
+```bash
+sudo mkdir -p /mnt/d
+sudo mount -t drvfs D: /mnt/d    # use the drive letter RPI-RP2 was assigned
+prremote install -b picow
+```
+
+`install` scans `/mnt/d` through `/mnt/z` for the BOOTSEL volume, so the mount point only has to match the drive letter.
+
+ESP32 boards need neither step in WSL beyond the usbipd attach, since they are flashed over the serial port.
+
+---
+
 ## Global Options
 
 | Option | Description |
@@ -200,7 +238,7 @@ prremote version
 
 ```bash
 # First-time setup
-prremote install -b picow     # or: pico / esp32 / esp32c6
+prremote install -b picow     # or: pico / pico2 / esp32 / esp32c6
 
 # Manual cycle
 prremote run app.rb       # compile + run (one-shot)

data/VERSION

@@ -1 +1 @@
-0.4.1
+0.4.3

data/lib/prremote/cli.rb

@@ -112,6 +112,8 @@ module Prremote
       devices = Detector.new.list_devices
       if devices.empty?
         puts 'No serial devices found.'
+        hint = Detector.no_device_hint
+        puts hint if hint
       else
         devices.each { |d| puts "#{d[:port]}  (#{d[:label]})" }
       end

data/lib/prremote/commands/install.rb

@@ -9,6 +9,23 @@ module Prremote
 
       BOARD_MAGIC = 'BORD'.freeze
 
+      DEVICE_LABELS = { 'pico' => 'Pico', 'picow' => 'Pico W', 'pico2' => 'Pico 2' }.freeze
+
+      # The UF2 bootloader exposes this file on the BOOTSEL volume.
+      BOOTSEL_MARKER = 'INFO_UF2.TXT'.freeze
+
+      # pico-sdk's stdio_usb reboots into the BOOTSEL boot ROM when the host
+      # sets this baud rate (PICO_STDIO_USB_RESET_MAGIC_BAUD_RATE), so a board
+      # already running the runtime can be flashed without the button.
+      RESET_BAUD = 1200
+
+      # How long to wait for the BOOTSEL drive after the 1200 bps touch before
+      # falling back to the manual instructions.
+      AUTO_BOOTSEL_TIMEOUT = 10
+
+      # Boards whose install path has not been run on real hardware yet.
+      UNVERIFIED_BOARDS = %w[pico2].freeze
+
       # board may be a runtime image name (esp32) or a board sharing one
       # (m5stickc_plus → esp32 image); see Boards::FIRMWARE.
       def initialize(version: VERSION, board: 'picow', port: nil, verbose: false)
@@ -29,15 +46,8 @@ module Prremote
 
         uf2_path = RuntimeManager.fetch(@version, @board)
 
-        device_label = @board == 'picow' ? 'Pico W' : 'Pico'
-        puts "Put the #{device_label} into BOOTSEL mode:"
-        puts '  1. Hold the BOOTSEL button'
-        puts '  2. Connect USB (or press RUN while holding BOOTSEL)'
-        puts '  3. Release BOOTSEL — RPI-RP2 should appear as a USB drive'
-        puts
-        puts 'Waiting for RPI-RP2...'
-
-        volume = wait_for_volume
+        warn_unverified
+        volume = mounted_volume || auto_bootsel || manual_bootsel
         puts "Copying firmware to #{volume}..."
         FileUtils.cp(uf2_path, File.join(volume, File.basename(uf2_path)))
 
@@ -49,12 +59,65 @@ module Prremote
 
       private
 
+      # A board already sitting in BOOTSEL needs no reboot.
+      def mounted_volume
+        volume = volume_paths.find { |p| mounted?(p) }
+        puts "Found #{volume_name} at #{volume}." if volume
+        volume
+      end
+
+      # Reboots a board running the runtime into BOOTSEL with a 1200 bps
+      # touch. nil when there is no Pico port or the drive never shows up
+      # (no runtime on the board, a wedged runtime, or a WSL drive that still
+      # needs mounting), so the caller falls back to the button.
+      def auto_bootsel
+        port = @port || Detector.find_pico_port
+        return nil unless port
+
+        puts "Rebooting #{device_label} on #{port} into BOOTSEL mode..."
+        touch_reset_baud(port)
+        puts "Waiting for #{volume_name}..."
+        wait_for_volume(timeout: AUTO_BOOTSEL_TIMEOUT)
+      rescue RuntimeError
+        puts "#{volume_name} did not appear; falling back to manual BOOTSEL."
+        puts
+        nil
+      end
+
+      # Opening the port at the magic baud rate is the whole trigger. The board
+      # drops off USB right away, so errors while closing are expected.
+      def touch_reset_baud(port)
+        serial = Serial.new(port, RESET_BAUD)
+      rescue RubySerial::Error, SystemCallError => e
+        puts "Could not open #{port} at #{RESET_BAUD} bps: #{e.message}" if @verbose
+      ensure
+        begin
+          serial&.close
+        rescue RubySerial::Error, SystemCallError
+          nil
+        end
+      end
+
+      def manual_bootsel
+        puts "Put the #{device_label} into BOOTSEL mode:"
+        puts '  1. Hold the BOOTSEL button'
+        puts '  2. Connect USB (or press RUN while holding BOOTSEL)'
+        puts "  3. Release BOOTSEL — #{volume_name} should appear as a USB drive"
+        puts
+        puts "Waiting for #{volume_name}..."
+        wait_for_volume
+      end
+
       # 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, @firmware)
         port  = @port || Detector.find_device
-        raise 'No serial device found. Connect the board or pass --port.' unless port
+        unless port
+          message = 'No serial device found. Connect the board or pass --port.'
+          hint    = Detector.no_device_hint
+          raise [message, hint].compact.join("\n")
+        end
 
         puts "Flashing #{File.basename(image)} to #{port}..."
         EspFlasher.flash(port: port, image_path: image, board: @firmware, verbose: @verbose)
@@ -94,34 +157,87 @@ module Prremote
         end
       end
 
+      def warn_unverified
+        return unless UNVERIFIED_BOARDS.include?(@board)
+
+        warn "NOTE: installing on #{device_label} has not been verified on real hardware yet."
+        warn '      Please report the result at https://github.com/lumbermill/prremote/issues'
+      end
+
+      def device_label
+        DEVICE_LABELS.fetch(@board, 'Pico')
+      end
+
+      # The RP2040 boot ROM mounts its BOOTSEL drive as RPI-RP2; the RP2350
+      # (Pico 2) boot ROM uses RP2350 instead. INFO_UF2.TXT carries the same
+      # name as its Board-ID.
+      def volume_name
+        @board == 'pico2' ? 'RP2350' : 'RPI-RP2'
+      end
+
       def volume_paths
+        user = ENV.fetch('USER', nil)
         [
-          '/Volumes/RPI-RP2',
-          "/run/media/#{ENV.fetch('USER', nil)}/RPI-RP2",
-          "/media/#{ENV.fetch('USER', nil)}/RPI-RP2"
-        ]
+          "/Volumes/#{volume_name}",
+          "/run/media/#{user}/#{volume_name}",
+          "/media/#{user}/#{volume_name}"
+        ] + drive_letter_volume_paths
+      end
+
+      # WSL reaches the Windows drive letter the BOOTSEL volume lands on through
+      # drvfs at /mnt/<letter>. That path carries no volume name, so the
+      # marker file is what identifies the board.
+      def drive_letter_volume_paths
+        drive_letter_roots.select { |root| bootsel_volume?(root) }
+      end
+
+      # /mnt/c is the Windows system drive; the board never lands there, so the
+      # scan starts at D.
+      def drive_letter_roots
+        ('d'..'z').map { |letter| "/mnt/#{letter}" }
+      end
+
+      # Other UF2 bootloaders (and the other RP2 chip) expose INFO_UF2.TXT
+      # too, so the Board-ID line is what tells the target chip apart.
+      def bootsel_volume?(root)
+        marker = File.join(root, BOOTSEL_MARKER)
+        File.file?(marker) && /^Board-ID:\s*#{Regexp.escape(volume_name)}\s*$/.match?(File.read(marker))
+      rescue SystemCallError
+        false
       end
 
+      # The marker, not the directory, is the test: macOS can leave an empty
+      # /Volumes/RPI-RP2 behind after the board reboots off a copy.
       def wait_for_volume(timeout: 60)
         deadline = Time.now + timeout
         loop do
-          path = volume_paths.find { |p| File.directory?(p) }
+          path = volume_paths.find { |p| mounted?(p) }
           return path if path
-          raise "Timed out waiting for RPI-RP2 volume (#{timeout}s)" if Time.now > deadline
+          raise "Timed out waiting for #{volume_name} volume (#{timeout}s)" if Time.now > deadline
 
           sleep 1
         end
       end
 
+      # The board reboots as soon as the UF2 lands, which tears the volume down.
+      # Testing the marker rather than the directory covers the WSL case, where
+      # the /mnt/<letter> mountpoint outlives the drive it pointed at.
       def wait_for_unmount(volume, timeout: 30)
         deadline = Time.now + timeout
         loop do
-          return unless File.directory?(volume)
+          return unless mounted?(volume)
           raise "Timed out waiting for device to reboot (#{timeout}s)" if Time.now > deadline
 
           sleep 1
         end
       end
+
+      def mounted?(volume)
+        File.directory?(volume) && File.file?(File.join(volume, BOOTSEL_MARKER))
+      rescue SystemCallError
+        # A stale drvfs mountpoint raises instead of reporting the drive as gone.
+        false
+      end
     end
   end
 end

data/lib/prremote/detector.rb

@@ -13,10 +13,48 @@ module Prremote
     }.freeze
     R2P2_VENDOR_IDS = %w[2e8a].freeze # Raspberry Pi USB VID (kept for compat)
 
+    # How far above the tty node the USB device sits is not fixed: ttyUSB
+    # bridges add a level that the native-CDC ttyACM nodes do not, and under
+    # WSL the chain hangs off vhci_hcd rather than a PCI controller. The lookup
+    # walks up until idVendor turns up instead of guessing a depth.
+    SYSFS_WALK_LIMIT = 6
+
     def self.find_device
       new.find_device
     end
 
+    # WSL2 does not forward USB devices to the guest: a board Windows enumerates
+    # correctly still has no /dev/ttyACM* here until usbipd-win attaches it.
+    def self.wsl?
+      return @wsl unless @wsl.nil?
+
+      @wsl = RbConfig::CONFIG['host_os'].match?(/linux/) &&
+             File.file?('/proc/version') &&
+             File.read('/proc/version').downcase.include?('microsoft')
+    rescue SystemCallError
+      @wsl = false
+    end
+
+    # Appended wherever a missing device would otherwise look like a prremote
+    # bug, since under WSL the cause is almost always the missing attach.
+    def self.no_device_hint
+      return nil unless wsl?
+
+      'Running under WSL: attach the board with usbipd-win first — ' \
+        '`usbipd list`, then `usbipd attach --wsl --busid <BUSID>`.'
+    end
+
+    def self.find_pico_port
+      new.find_pico_port
+    end
+
+    # A port whose USB vendor is Raspberry Pi — the only kind the 1200 bps
+    # BOOTSEL touch applies to. nil when none (or the vendor can't be read).
+    def find_pico_port
+      label = KNOWN_VENDORS.dig(R2P2_VENDOR_IDS.first, :label)
+      serial_ports.find { |p| port_label(p) == label }
+    end
+
     def find_device
       candidates = serial_ports
       return candidates.first if candidates.size == 1
@@ -66,13 +104,25 @@ module Prremote
         end
         nil
       when /linux/
-        port_name = File.basename(port)
-        vid_path = "/sys/class/tty/#{port_name}/device/../../../idVendor"
-        return nil unless File.exist?(vid_path)
+        vid = linux_vendor_id(port)
+        vid && KNOWN_VENDORS.dig(vid, :label)
+      end
+    end
+
+    def linux_vendor_id(port)
+      dir = File.realpath("/sys/class/tty/#{File.basename(port)}/device")
+      SYSFS_WALK_LIMIT.times do
+        vid_path = File.join(dir, 'idVendor')
+        return File.read(vid_path).strip.downcase if File.file?(vid_path)
+
+        parent = File.dirname(dir)
+        break if parent == dir
 
-        vid = File.read(vid_path).strip.downcase
-        KNOWN_VENDORS.dig(vid, :label)
+        dir = parent
       end
+      nil
+    rescue SystemCallError
+      nil
     end
 
     # Vendor IDs of all connected USB devices as 4-digit hex strings.

data/lib/prremote/runtime_manager.rb

@@ -4,7 +4,7 @@ require 'fileutils'
 
 module Prremote
   module RuntimeManager
-    BOARDS = %w[pico picow esp32 esp32c6].freeze
+    BOARDS = %w[pico picow pico2 esp32 esp32c6].freeze
     ESP32_BOARDS = %w[esp32 esp32c6].freeze
 
     # Pico boards ship as UF2 (copied to the BOOTSEL drive); ESP32 family ships

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prremote
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.3
 platform: ruby
 authors:
 - ITO Yosei