prremote 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a30a56541a311e708b79d18eb2f3a07b1007df6fe5c971d307ecbf069b64a78a
-  data.tar.gz: 75bd5a9439f0eacb9237e375010e7d65423c6f8c5556d82b352d946ba3702f88
+  metadata.gz: e8eeb5a287e2d90f2c3fdab1324a778be063eee3bb8eeb5577803113478f7afe
+  data.tar.gz: f58b759474589038e3c4f5b4fc5c0504543fa2c03f4fde9957a30fe2d6f198f1
 SHA512:
-  metadata.gz: bb40ffda0d41b8fa8863eb330597e9f46d4dd0c963763f66a8e543e11fce491b5f969ce84a8986cc6564908f07a9d37951c5e9ed8d9a06591032e4eb7248b0bd
-  data.tar.gz: b740c328761c6c31f0a2bd400b0baf8a537bd4d5e04637223588b9e56e695f870d2d8557790d1a92794a71f3c6be1903f31cb84a0b13ba7e5829edbcc6893dc9
+  metadata.gz: bec989326521193f9abcdd90794d79d2acefe8f9d41721507188cd267dc9fbb085c75bc953e7c14960f6ccdb6106da8f5cc276f4a8a7b861038092beeb74af57
+  data.tar.gz: f5087a5ab44764509e10b7c70b4b1214223cebdf3ff8f72adee7740297a8deeb7b37c8729a27511484630521ba8da20c55102174e8333728ffd36c39fbd37b12

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,7 +66,9 @@ 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 esp32                 # ESP32 (M5GO / M5Stack Core, M5StickC PLUS, etc.)
+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)
 prremote install -b picow --version 0.1.1 # specify a runtime version
 ```
@@ -73,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: put the device 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).
 
@@ -81,6 +85,8 @@ ESP32-C6: flashing is delegated to [esptool](https://docs.espressif.com/projects
 
 Reflashing the runtime does not erase a deployed script on either chip.
 
+Board names such as `m5stickc_plus` install the runtime image of their chip (esp32) and record the board name on the device, which the runtime then reports (`prremote version` shows `board=m5stickc_plus`). That name decides which [board libraries](#board-libraries) scripts can use; installing with the plain chip name (`-b esp32`) clears it.
+
 ---
 
 ### `run FILE [FILE ...]`
@@ -177,13 +183,48 @@ Show the gem version, mrbc version, and the connected device's runtime version.
 
 ```bash
 prremote version
-# prremote: 0.4.0
-# runtime:  0.4.0 (/dev/tty.usbmodem101)
+# prremote: 0.4.2
+# runtime:  0.4.2 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 |
@@ -197,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)
@@ -213,6 +254,25 @@ prremote undeploy         # remove from flash
 
 ---
 
+## Board libraries
+
+Some boards come with a Ruby library for their built-in hardware. You don't load it yourself: when a script mentions one of its classes, `run` / `deploy` / `watch` / `eval` compile the library in ahead of your files (it prints `Adding board library: ...`). Scripts that don't mention it pay nothing on the device.
+
+| Board (`install -b`) | Classes | Covers |
+|---|---|---|
+| `m5stickc_plus` | `M5StickCPlus`, `BM8563` | AXP192 power-on, LCD preset per rotation, buttons A/B, red LED, buzzer, IR LED, BM8563 RTC (as `Time`) |
+
+```ruby
+stick = M5StickCPlus.new            # powers the LCD
+lcd = stick.lcd(rotation: 1)        # pins / size / RAM offset / color order preset
+lcd.text(4, 4, stick.rtc.time.to_s, scale: 1)
+stick.led.on if stick.button_a.pressed?
+```
+
+A board library is refused if the device reports a different board (e.g. `M5StickCPlus` on an esp32c6). Chip drivers such as `BM8563` work on any board. The library sources live in [lib/prremote/boards/](lib/prremote/boards/) and double as the reference for driving the hardware directly.
+
+---
+
 ## How It Works
 
 prremote flashes a minimal C firmware (built on mruby/c) onto the board. The firmware:

data/VERSION

@@ -1 +1 @@
-0.4.0
+0.4.2

data/lib/prremote/boards/bm8563.rb

@@ -0,0 +1,55 @@
+# BM8563 / PCF8563 real-time clock (I2C address 0x51).
+# Board library for prremote — compiled into the script by the host when it
+# references BM8563 (see lib/prremote/boards.rb); this file runs on the device.
+#
+#   rtc = BM8563.new(i2c)
+#   rtc.valid?                 # false until the time has been set (VL flag)
+#   puts rtc.time.to_s         # => "2026-09-28T08:30:42+9" (a Time)
+#   rtc.time = Time.new(offset: 9).sync("ntp.nict.jp")
+#
+# The chip holds local time; `time(offset:)` says which zone that is (JST by
+# default) and `time=` writes the given Time in its own offset.
+class BM8563
+  ADDR = 0x51
+
+  def initialize(i2c)
+    @i2c = i2c
+  end
+
+  # false while the VL (voltage-low) flag says the clock lost integrity —
+  # never set, or the backup battery ran out.
+  def valid?
+    r = @i2c.read(ADDR, 1, 0x02)
+    !r.nil? && r.getbyte(0) < 0x80
+  end
+
+  def time(offset: 9)
+    r = @i2c.read(ADDR, 7, 0x02).bytes
+    t = Time.new(offset: offset)
+    year = _dec(r[6]) + (r[5] < 0x80 ? 2000 : 1900) # month bit7 = century
+    days = t._days_since_epoch(year, _dec(r[5] & 0x1F), _dec(r[3] & 0x3F))
+    t._set_from_epoch((days * 86_400) + _seconds_of_day(r) - (offset * 3600))
+    t
+  end
+
+  # Also clears the VL flag and restarts the clock if it was stopped.
+  def time=(t)
+    wday = (((t.epoch + (t.utc_offset * 3600)) / 86_400) + 4) % 7 # 1970-01-01 = Thu
+    @i2c.write(ADDR, 0x00, 0x00, 0x00) # control 1/2: running, no alarm/timer IRQ
+    @i2c.write(ADDR, 0x02, _bcd(t.sec), _bcd(t.min), _bcd(t.hour), _bcd(t.day),
+               wday, _bcd(t.month), _bcd(t.year % 100))
+  end
+
+  # r: registers 0x02.. (sec, min, hour, ...)
+  def _seconds_of_day(r)
+    (_dec(r[2] & 0x3F) * 3600) + (_dec(r[1] & 0x7F) * 60) + _dec(r[0] & 0x7F)
+  end
+
+  def _dec(b)
+    ((b >> 4) * 10) + (b & 0x0F)
+  end
+
+  def _bcd(n)
+    ((n / 10) << 4) | (n % 10)
+  end
+end

data/lib/prremote/boards/m5stickc_plus.rb

@@ -0,0 +1,102 @@
+# M5StickC PLUS board support: power-on, LCD preset and built-in devices.
+# Board library for prremote — compiled into the script by the host when it
+# references M5StickCPlus (see lib/prremote/boards.rb); this file runs on the
+# device (esp32 runtime) together with bm8563.rb.
+#
+#   stick = M5StickCPlus.new         # powers the LCD via the AXP192 PMIC
+#   lcd = stick.lcd(rotation: 1)     # landscape; 0-3 all preset
+#   stick.button_a.pressed?          # front button; button_b = side button
+#   stick.led.on                     # red LED
+#   stick.tone(440, 0.2)             # passive buzzer
+#   stick.rtc.time.to_s              # BM8563 RTC (see bm8563.rb)
+#   stick.ir.send_nec(0x00, 0x45)    # IR LED
+#
+# Built-in devices share one I2C bus (SDA=21/SCL=22): AXP192 0x34, BM8563
+# 0x51, MPU6886 0x68 — use stick.i2c for anything else on it.
+class M5StickCPlus
+  AXP192 = 0x34
+
+  # ST7789v2 135x240 inside a 240x320 RAM window. Per rotation: MADCTL (the
+  # generic table minus its BGR bit — this panel is RGB) and the RAM offset
+  # of the 135-px side, which is 52 px from one edge and 53 from the other,
+  # so it changes when a rotation mirrors that axis.
+  LCD_MADCTL   = [0x00, 0x60, 0xC0, 0xA0]
+  LCD_OFFSET_X = [52, 53, 53, 52]
+
+  attr_reader :i2c
+
+  def initialize
+    @i2c = I2C.new(sda_pin: 21, scl_pin: 22)
+    @i2c.write(AXP192, 0x28, 0xCC)             # LDO2 (backlight) / LDO3 (panel) = 3.0V
+    cur = @i2c.read(AXP192, 1, 0x12).getbyte(0)
+    @i2c.write(AXP192, 0x12, cur | 0x4D)       # enable EXTEN (Grove 5V), LDO2, LDO3, DCDC1
+  end
+
+  # rotation: 0 = portrait (USB at the bottom), 1/3 = landscape, 2 = portrait
+  # upside down. Returns a plain LCD (see lcd_wrap.rb for drawing methods).
+  def lcd(rotation: 0)
+    r = rotation % 4
+    LCD.new(rotation: r, sck_pin: 13, mosi_pin: 15, miso_pin: -1, cs_pin: 5,
+            dc_pin: 23, rst_pin: 18, bl_pin: -1, invert: true,
+            madctl: LCD_MADCTL[r], width: 135, height: 240,
+            offset_x: LCD_OFFSET_X[r], offset_y: 40)
+  end
+
+  def rtc
+    @rtc ||= BM8563.new(@i2c)
+  end
+
+  # Front (big) button.
+  def button_a
+    @button_a ||= Button.new(37)
+  end
+
+  # Side button, opposite the power button.
+  def button_b
+    @button_b ||= Button.new(39)
+  end
+
+  def led
+    @led ||= LED.new(10)
+  end
+
+  # Plays `hz` on the passive buzzer (GPIO2) for `duration` seconds.
+  def tone(hz, duration)
+    @buzzer ||= PWM.new(2, frequency: hz, duty_u16: 0)
+    @buzzer.frequency = hz
+    @buzzer.duty_u16 = 32_768
+    sleep duration
+    @buzzer.duty_u16 = 0
+  end
+
+  def ir
+    @ir ||= IR.new(9)
+  end
+
+  # External pull-up on the board; pressed reads 0.
+  class Button
+    def initialize(pin)
+      @gpio = GPIO.new(pin, GPIO::IN)
+    end
+
+    def pressed?
+      @gpio.read == 0
+    end
+  end
+
+  # Active-low red LED.
+  class LED
+    def initialize(pin)
+      @gpio = GPIO.new(pin, GPIO::OUT)
+      off
+    end
+
+    def on
+      @gpio.write(0)
+    end
+
+    def off
+      @gpio.write(1)
+    end
+  end
+end

data/lib/prremote/boards.rb

@@ -0,0 +1,85 @@
+module Prremote
+  # Board support libraries: Ruby files under lib/prremote/boards/ that run on
+  # the device (not on the host). They are compiled into the user's script
+  # only when the script references one of their constants, so scripts that
+  # don't use them pay nothing in device heap / symbol table.
+  #
+  # A board name is what `install -b NAME` records on the device and what the
+  # runtime reports in its READY banner (`READY prremote-runtime/X board=NAME`).
+  # Several board names can share one runtime image (FIRMWARE).
+  module Boards
+    LIB_DIR = File.expand_path('boards', __dir__)
+
+    # Board name => runtime image it runs. Boards not listed here are their
+    # own image (pico, picow, esp32, esp32c6, ...).
+    FIRMWARE = {
+      'm5stickc_plus' => 'esp32'
+    }.freeze
+
+    # file:      path under LIB_DIR
+    # constants: referencing any of these pulls the library in
+    # boards:    board names it is written for (nil = any board)
+    # requires:  other library files it needs, compiled before it
+    Library = Struct.new(:file, :constants, :boards, :requires, keyword_init: true)
+
+    LIBRARIES = [
+      Library.new(file: 'bm8563.rb', constants: %w[BM8563], boards: nil, requires: []),
+      Library.new(file: 'm5stickc_plus.rb', constants: %w[M5StickCPlus],
+                  boards: %w[m5stickc_plus], requires: %w[bm8563.rb])
+    ].freeze
+
+    module_function
+
+    def firmware_for(board)
+      FIRMWARE.fetch(board, board)
+    end
+
+    # Board names `install` accepts on top of the plain runtime images.
+    def names
+      FIRMWARE.keys
+    end
+
+    # Libraries the sources reference directly.
+    def referenced(sources)
+      LIBRARIES.select { |lib| referenced?(lib, sources) }
+    end
+
+    # Library file paths to compile ahead of the user's sources, in dependency
+    # order. Depends only on the sources, so it can run before connecting.
+    def library_paths(sources)
+      files = []
+      referenced(sources).each { |lib| add_with_requires(lib.file, files) }
+      files.map { |f| File.join(LIB_DIR, f) }
+    end
+
+    # Raises if a referenced library is for another board than the device's
+    # (`board` is nil when the runtime is too old to report one).
+    def check!(sources, board)
+      referenced(sources).each { |lib| check_board!(lib, board) }
+    end
+
+    def referenced?(lib, sources)
+      lib.constants.any? { |c| sources.any? { |src| src.match?(/\b#{c}\b/) } }
+    end
+
+    # A board library also runs on a device that only reports its runtime
+    # image name (installed with the plain `-b esp32`, or a runtime older than
+    # board names), since the host cannot tell those boards apart.
+    def check_board!(lib, board)
+      return if lib.boards.nil? || board.nil?
+      return if lib.boards.include?(board)
+      return if lib.boards.any? { |b| firmware_for(b) == board }
+
+      raise "#{lib.constants.join('/')} is for #{lib.boards.join('/')}, " \
+            "but the device reports board=#{board}"
+    end
+
+    def add_with_requires(file, files)
+      return if files.include?(file)
+
+      lib = LIBRARIES.find { |l| l.file == file }
+      lib&.requires&.each { |dep| add_with_requires(dep, files) }
+      files << file
+    end
+  end
+end

data/lib/prremote/cli.rb

@@ -27,7 +27,7 @@ module Prremote
     desc 'install', 'Flash prremote runtime firmware to a supported board'
     option :version, type: :string, desc: "Firmware version to install (default: #{VERSION})"
     option :board, aliases: '-b', type: :string,
-                   desc: "Board type: #{RuntimeManager::BOARDS.join(', ')}"
+                   desc: "Board type: #{Commands::Install.board_names.join(', ')}"
     option :verbose, aliases: '-V', type: :boolean, default: false,
                      desc: 'Print step-by-step flash diagnostics'
     def install
@@ -36,14 +36,14 @@ module Prremote
 
       unless board
         puts "Specify a board with --board / -b. Supported boards:"
-        RuntimeManager::BOARDS.each { |b| puts "  #{b}" }
+        Commands::Install.board_names.each { |b| puts "  #{b}" }
         puts
         puts "Example: prremote install -b esp32c6"
         return
       end
 
-      unless RuntimeManager::BOARDS.include?(board)
-        raise Thor::Error, "Unknown board '#{board}'. Supported boards: #{RuntimeManager::BOARDS.join(', ')}"
+      unless Commands::Install.board_names.include?(board)
+        raise Thor::Error, "Unknown board '#{board}'. Supported boards: #{Commands::Install.board_names.join(', ')}"
       end
 
       Commands::Install.new(version: version, board: board, port: options[:port],
@@ -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
@@ -188,7 +190,8 @@ module Prremote
           next
         end
 
-        return "#{::Regexp.last_match(1)} (#{port})" if buf =~ %r{READY prremote-runtime/([\d.]+)}
+        ready = format_ready(buf, port)
+        return ready if ready
         return '(not responding)' if Time.now > deadline
 
         sleep 0.05
@@ -199,6 +202,16 @@ module Prremote
       serial&.close
     end
 
+    # "0.4.1 board=m5stickc_plus (/dev/...)" from a complete READY line, else
+    # nil. Runtimes older than board names omit the board= field.
+    def format_ready(buf, port)
+      m = buf.match(%r{READY prremote-runtime/([\d.]+)(?: board=(\S+))?\s*\n})
+      return nil unless m
+
+      board = m[2] ? " board=#{m[2]}" : ''
+      "#{m[1]}#{board} (#{port})"
+    end
+
     def resolve_port
       return options[:port] if options[:port]
 

data/lib/prremote/commands/deploy.rb

@@ -1,6 +1,3 @@
-require 'open3'
-require 'tempfile'
-require_relative '../mrbc'
 require_relative 'serial_helpers'
 
 module Prremote
@@ -20,29 +17,19 @@ module Prremote
         rb_paths.each { |f| raise "File not found: #{f}" unless File.exist?(f) }
 
         warn "Compiling #{rb_paths.map { |f| File.basename(f) }.join(', ')}..."
-        mrb_data = compile(*rb_paths)
+        mrb_data = compile_with_boards(rb_paths)
 
-        warn 'Deploying to flash...'
         deploy_to_device(mrb_data, rb_paths)
         warn 'Deployed. Script will run automatically on next boot.'
       end
 
       private
 
-      def compile(*rb_paths)
-        Mrbc.check_version!
-        tmp = Tempfile.new(['prremote', '.mrb'])
-        out, status = Open3.capture2e(Mrbc.bin, '-o', tmp.path, *rb_paths)
-        raise "mrbc failed:\n#{out.chomp}" unless status.success?
-
-        File.binread(tmp.path)
-      ensure
-        tmp&.close!
-      end
-
       def deploy_to_device(mrb_data, rb_paths)
         serial = Serial.new(@port, @baud)
-        wait_for_ready(serial)
+        check_board!(wait_for_ready(serial), rb_paths)
+
+        warn 'Deploying to flash...'
         write_chunked(serial, DEPLOY_MAGIC + build_meta_packet(rb_paths) + mrb_data)
         wait_for_deployed(serial)
       ensure

data/lib/prremote/commands/install.rb

@@ -1,27 +1,49 @@
 require 'fileutils'
+require_relative '../boards'
+require_relative 'serial_helpers'
 
 module Prremote
   module Commands
     class Install
+      include SerialHelpers
+
+      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
+
+      # 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)
-        @version = version
-        @board   = board
-        @port    = port
-        @verbose = verbose
+        @version  = version
+        @board    = board
+        @firmware = Boards.firmware_for(board)
+        @port     = port
+        @verbose  = verbose
+      end
+
+      # Runtime images plus boards that share one (m5stickc_plus).
+      def self.board_names
+        RuntimeManager::BOARDS + Boards.names
       end
 
       def call
-        return install_esp32 if RuntimeManager::ESP32_BOARDS.include?(@board)
+        return install_esp32 if RuntimeManager::ESP32_BOARDS.include?(@firmware)
 
         uf2_path = RuntimeManager.fetch(@version, @board)
 
-        device_label = @board == 'picow' ? 'Pico W' : 'Pico'
+        warn_unverified
         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 "  3. Release BOOTSEL — #{volume_name} should appear as a USB drive"
         puts
-        puts 'Waiting for RPI-RP2...'
+        puts "Waiting for #{volume_name}..."
 
         volume = wait_for_volume
         puts "Copying firmware to #{volume}..."
@@ -38,21 +60,99 @@ module Prremote
       # 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)
+        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: @board, verbose: @verbose)
+        EspFlasher.flash(port: port, image_path: image, board: @firmware, verbose: @verbose)
+        record_board(port)
         puts "Done. Runtime #{@version} installed."
       end
 
+      # One ESP32 image serves several boards, so tell the runtime which one
+      # this is (kept in NVS; reported as board= in READY, which picks the
+      # board libraries). Installing the plain image clears it.
+      def record_board(port)
+        name = @board == @firmware ? '' : @board
+        serial = Serial.new(port, 115_200)
+        wait_for_ready(serial)
+        serial.write(BOARD_MAGIC + [name.bytesize].pack('C') + name)
+        reply = wait_for_board_reply(serial)
+        if reply.nil?
+          warn "WARNING: runtime #{@version} does not record board names; board=#{@board} not set."
+        elsif !name.empty?
+          puts "Board: #{reply}"
+        end
+      ensure
+        serial&.close
+      end
+
+      # "BOARD <name>" on success; nil if the runtime predates the command.
+      def wait_for_board_reply(serial)
+        buf = +''
+        deadline = Time.now + 3
+        loop do
+          buf << normalize(safe_read(serial, 256))
+          return Regexp.last_match(1) if buf =~ /^BOARD (\S+)\n/
+          raise "Device rejected board name '#{@board}'" if buf.include?("ERROR board\n")
+          return nil if Time.now > deadline
+
+          sleep 0.05
+        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
 
       def wait_for_volume(timeout: 60)
@@ -60,21 +160,31 @@ module Prremote
         loop do
           path = volume_paths.find { |p| File.directory?(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/commands/run.rb

@@ -1,6 +1,3 @@
-require 'open3'
-require 'tempfile'
-require_relative '../mrbc'
 require_relative 'serial_helpers'
 
 module Prremote
@@ -17,31 +14,20 @@ module Prremote
         rb_paths.each { |f| raise "File not found: #{f}" unless File.exist?(f) }
 
         warn "Compiling #{rb_paths.map { |f| File.basename(f) }.join(', ')}..."
-        mrb_data = compile(*rb_paths)
+        mrb_data = compile_with_boards(rb_paths)
 
-        warn 'Running...'
-        run_on_device(mrb_data)
+        run_on_device(mrb_data, rb_paths)
       rescue Interrupt
         warn ''
       end
 
       private
 
-      def compile(*rb_paths)
-        Mrbc.check_version!
-        tmp = Tempfile.new(['prremote', '.mrb'])
-        out, status = Open3.capture2e(Mrbc.bin, '-o', tmp.path, *rb_paths)
-        raise "mrbc failed:\n#{out.chomp}" unless status.success?
-
-        File.binread(tmp.path)
-      ensure
-        tmp&.close!
-      end
-
-      def run_on_device(mrb_data)
+      def run_on_device(mrb_data, rb_paths)
         serial = Serial.new(@port, @baud)
-        wait_for_ready(serial)
+        check_board!(wait_for_ready(serial), rb_paths)
 
+        warn 'Running...'
         write_chunked(serial, mrb_data)
         debug "sent #{mrb_data.bytesize} bytes (first 4: #{mrb_data[0, 4].inspect})"
 

data/lib/prremote/commands/serial_helpers.rb

@@ -1,3 +1,6 @@
+require_relative '../boards'
+require_relative '../mrbc'
+
 module Prremote
   module Commands
     module SerialHelpers
@@ -16,9 +19,10 @@ module Prremote
         next_ctrl = Time.now + 1
         loop do
           buf << normalize(safe_read(serial, 256))
-          if buf.include?('READY ')
+          # Wait for the whole line: the board= field follows the version.
+          if buf.match?(/READY [^\n]*\n/)
             warn_if_runtime_outdated(buf)
-            return
+            return parse_ready(buf)
           end
           raise 'Timeout waiting for device. Run `prremote reset` if a script is running.' if Time.now > deadline
 
@@ -30,6 +34,32 @@ module Prremote
         end
       end
 
+      # READY banner fields. board is nil on runtimes older than board names.
+      Ready = Struct.new(:version, :board)
+
+      def parse_ready(buf)
+        m = buf.match(%r{READY prremote-runtime/(\S+)(?: board=(\S+))?})
+        m ? Ready.new(m[1], m[2]) : Ready.new(nil, nil)
+      end
+
+      # Compiles the user's files, prepending the board libraries they
+      # reference (see Boards). Done before connecting: an open ESP32 port can
+      # reset the chip, so the gap between READY and sending stays minimal.
+      def compile_with_boards(rb_paths)
+        libs = Boards.library_paths(sources_of(rb_paths))
+        warn "Adding board library: #{libs.map { |f| File.basename(f) }.join(', ')}" unless libs.empty?
+        Mrbc.compile(*libs, *rb_paths)
+      end
+
+      # After READY: refuse a board library meant for another board.
+      def check_board!(ready, rb_paths)
+        Boards.check!(sources_of(rb_paths), ready.board)
+      end
+
+      def sources_of(rb_paths)
+        rb_paths.map { |f| File.read(f, encoding: 'UTF-8') }
+      end
+
       def normalize(str)
         str.gsub("\r\n", "\n").gsub("\r", '')
       end

data/lib/prremote/detector.rb

@@ -13,10 +13,37 @@ 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 find_device
       candidates = serial_ports
       return candidates.first if candidates.size == 1
@@ -66,13 +93,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/mrbc.rb

@@ -1,4 +1,5 @@
 require 'open3'
+require 'tempfile'
 
 module Prremote
   # mrbc lookup order:
@@ -43,6 +44,18 @@ module Prremote
       @version_ok = true
     end
 
+    # Compiles the given .rb files (in order) into one .mrb; returns its bytes.
+    def self.compile(*rb_paths)
+      check_version!
+      tmp = Tempfile.new(['prremote', '.mrb'])
+      out, status = Open3.capture2e(bin, '-o', tmp.path, *rb_paths)
+      raise "mrbc failed:\n#{out.chomp}" unless status.success?
+
+      File.binread(tmp.path)
+    ensure
+      tmp&.close!
+    end
+
     private_class_method def self.path_candidates
       ENV['PATH'].split(File::PATH_SEPARATOR)
                  .grep_v(SHIMS_RE)

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.0
+  version: 0.4.2
 platform: ruby
 authors:
 - ITO Yosei
@@ -106,6 +106,9 @@ files:
 - VERSION
 - bin/prremote
 - lib/prremote.rb
+- lib/prremote/boards.rb
+- lib/prremote/boards/bm8563.rb
+- lib/prremote/boards/m5stickc_plus.rb
 - lib/prremote/cli.rb
 - lib/prremote/commands/deploy.rb
 - lib/prremote/commands/eval_cmd.rb