rpremote 0.2.0 → 0.3.0

data/lib/rpremote/dfu_command.rb

@@ -8,16 +8,21 @@ module Rpremote
     TYPES = { ".rb" => "RUBY", ".mrb" => "RITE" }.freeze
 
     def self.run(args, defaults:, output: $stdout, services: {})
-      default_services = { serial: Serial, device: Device, modem: PicoModem, runner: Runner, compiler: DfuCompiler }
+      default_services = {
+        serial: Serial, device: Device, modem: PicoModem, runner: Runner,
+        compiler: DfuCompiler
+      }
       services = default_services.merge(services)
       subcommand = args.shift
       case subcommand
       when "app" then stage(args, defaults, output, services)
       when "compile" then compile(args, defaults, output, services[:compiler])
       when "status" then status(args, defaults, output, services)
+      when "remove" then remove(args, defaults, output, services)
       else
         raise ArgumentError,
-              "usage: rpremote dfu app FILE [options], dfu compile FILE [options], or dfu status [options]"
+              "usage: rpremote dfu app FILE [options], dfu compile FILE [options], " \
+              "dfu status [options], or dfu remove [options]"
       end
     end
 
@@ -52,7 +57,7 @@ module Rpremote
     private_class_method :compile
 
     def self.status(args, defaults, output, services)
-      options = parse_app_options(args, defaults)
+      options = parse_connection_options(args, defaults)
       raise ArgumentError, "usage: rpremote dfu status [options]" unless args.empty?
 
       port_path = services[:device].main_port(options[:port])
@@ -71,6 +76,45 @@ module Rpremote
     end
     private_class_method :status
 
+    def self.remove(args, defaults, output, services)
+      options = parse_connection_options(args, defaults)
+      raise ArgumentError, "usage: rpremote dfu remove [options]" unless args.empty?
+
+      port_path = services[:device].main_port(options[:port])
+      code = <<~'RUBY'
+        require "dfu"
+        # A confirmed DFU launcher may have returned after leaving a Sandbox
+        # worker alive. Stop known Processing workers before waiting for the
+        # Shell prompt; deleting their source files does not stop RAM tasks.
+        begin
+          $imu_processing_stream.close if $imu_processing_stream
+          $imu_processing_stream = nil
+        rescue Exception
+          $imu_processing_stream = nil
+        end
+        begin
+          $mpu6050_processing_stream.close if $mpu6050_processing_stream
+          $mpu6050_processing_stream = nil
+        rescue Exception
+          $mpu6050_processing_stream = nil
+        end
+        DFU::Meta.recover
+        DFU::Meta.save(DFU::Meta.deep_copy(DFU::Meta::DEFAULT))
+        %w[a b].each do |slot|
+          %w[rb mrb].each do |ext|
+            path = "#{ENV['HOME']}/app_#{slot}.#{ext}"
+            File.unlink(path) if File.exist?(path)
+          end
+        end
+      RUBY
+      output.puts("removing all DFU boot applications from #{port_path}; this permanently clears both A/B slots")
+      services[:serial].open(port_path, baud: options[:baud]) do |port|
+        services[:runner].new(port, timeout: options[:timeout]).run(code)
+      end
+      output.puts("removed all DFU boot applications; run `rpremote reset` to stop the running application")
+    end
+    private_class_method :remove
+
     def self.parse_app_options(args, defaults)
       options = {
         port: defaults[:port],
@@ -91,6 +135,24 @@ module Rpremote
     end
     private_class_method :parse_app_options
 
+    def self.parse_connection_options(args, defaults)
+      options = {
+        port: defaults[:port],
+        baud: defaults.fetch(:baud, Serial::BAUD_RATE),
+        timeout: defaults.fetch(:timeout, DEFAULT_TIMEOUT)
+      }
+      OptionParser.new do |parser|
+        parser.on("--port PORT") { |value| options[:port] = value }
+        parser.on("--baud RATE", Integer) { |value| options[:baud] = value }
+        parser.on("--timeout SECONDS", Float) { |value| options[:timeout] = value }
+      end.parse!(args)
+      raise ArgumentError, "--baud must be positive" unless options[:baud].positive?
+      raise ArgumentError, "--timeout must be positive" unless options[:timeout].positive?
+
+      options
+    end
+    private_class_method :parse_connection_options
+
     def self.parse_compile_options(args, defaults)
       options = {
         language: defaults.fetch(:language, Target::DEFAULT_LANGUAGE),

data/lib/rpremote/flash_command.rb

@@ -33,7 +33,10 @@ module Rpremote
       }
       OptionParser.new do |parser|
         parser.on("--cache DIR") { |value| options[:cache_dir] = value }
-        parser.on("--firmware FILE") { |value| options[:firmware] = value }
+        parser.on("--firmware FILE") do |value|
+          options[:firmware] = value
+          options[:firmware_explicit] = true
+        end
         parser.on("--language LANGUAGE") { |value| options[:language] = value }
         parser.on("--language-version VERSION") { |value| options[:language_version] = value }
         parser.on("--board BOARD") { |value| options[:board] = value }

data/lib/rpremote/flasher.rb

@@ -36,30 +36,57 @@ module Rpremote
       raise ArgumentError, "timeout must be positive" unless @timeout.positive?
     end
 
-    def flash(uf2_path, mount: nil, port: nil)
+    def flash(uf2_path, mount: nil, port: nil, wait_for_port: true)
       validate_firmware!(uf2_path)
       target = find_mount(mount)
       destination = File.join(target, File.basename(uf2_path))
       copy_firmware(uf2_path, destination)
       wait_until("BOOTSEL drive to disappear") { !mount_probe.call(target) }
+      return Result.new(mount: target, destination: destination, port: nil) unless wait_for_port
+
       detected_port = wait_until("R2P2 serial port to appear") { detect_port(port) }
       Result.new(mount: target, destination: destination, port: detected_port)
     end
 
     def find_mount(explicit_mount = nil)
-      return validate_mount!(File.expand_path(explicit_mount)) if explicit_mount
+      mounted = find_mounted(explicit_mount)
+      return mounted if mounted
 
-      matches = Dir.glob(File.join(volumes_root, "*")).select do |path|
-        Dir.exist?(path) && valid_target?(path)
+      raise MountNotFoundError,
+            "Pico 2 BOOTSEL drive not found; reconnect it while holding BOOTSEL or use --mount DIR"
+    end
+
+    def find_mounted(explicit_mount = nil)
+      if explicit_mount
+        path = File.expand_path(explicit_mount)
+        return unless Dir.exist?(path)
+
+        return validate_mount!(path)
+      end
+
+      matches = bootsel_mounts
+      return if matches.empty?
+      return matches.first if matches.one?
+
+      raise MountNotFoundError, "multiple Pico 2 BOOTSEL drives found; use --mount DIR"
+    end
+
+    def wait_for_mount(mount: nil)
+      if mount
+        path = File.expand_path(mount)
+        return wait_until("Pico 2 BOOTSEL drive to appear") do
+          next unless Dir.exist?(path)
+          next unless valid_target?(path)
+
+          path
+        end
       end
-      case matches.length
-      when 0
-        raise MountNotFoundError,
-              "Pico 2 BOOTSEL drive not found; reconnect it while holding BOOTSEL or use --mount DIR"
-      when 1
+
+      wait_until("Pico 2 BOOTSEL drive to appear") do
+        matches = bootsel_mounts
+        raise MountNotFoundError, "multiple Pico 2 BOOTSEL drives found; use --mount DIR" if matches.length > 1
+
         matches.first
-      else
-        raise MountNotFoundError, "multiple Pico 2 BOOTSEL drives found; use --mount DIR"
       end
     end
 
@@ -90,8 +117,19 @@ module Rpremote
       false
     end
 
+    def bootsel_mounts
+      Dir.glob(File.join(volumes_root, "*")).select do |path|
+        Dir.exist?(path) && valid_target?(path)
+      end
+    end
+
     def copy_firmware(source, destination)
       FileUtils.copy_file(source, destination)
+    rescue Errno::ENXIO
+      # RP2350 may reboot and detach its BOOTSEL volume before macOS finishes
+      # closing the destination. The disappearance and serial reconnect checks
+      # in #flash determine whether the transfer actually completed.
+      nil
     rescue SystemCallError => e
       raise Error, "failed to copy UF2 firmware: #{e.message}"
     end

data/lib/rpremote/help.rb

@@ -9,9 +9,14 @@ module Rpremote
       build: "rpremote build [--language LANGUAGE] [--language-version VERSION] [--board BOARD] " \
              "[--firmware FILE] [--cache DIR] [--mrbgems FILE|--no-mrbgems]",
       build_clean: "rpremote build clean",
+      bootsel: "rpremote bootsel [--reset-flash-memory] [--mount DIR] [--port PORT] [--baud RATE] [--timeout SEC]",
+      deploy: "rpremote deploy PATH [--language LANGUAGE] [--language-version VERSION] [--board BOARD] " \
+              "[--firmware FILE] [--cache DIR] [--mrbgems FILE|--no-mrbgems] [--mount DIR] " \
+              "[--port PORT] [--baud RATE] [--timeout SEC]",
       dfu_app: "rpremote dfu app FILE [--type ruby|rite] [--port PORT] [--baud RATE] [--timeout SEC]",
       dfu_compile: "rpremote dfu compile FILE [--output FILE] [--language LANGUAGE] [--language-version VERSION] [--cache DIR]",
       dfu_status: "rpremote dfu status [--port PORT] [--baud RATE] [--timeout SEC]",
+      dfu_remove: "rpremote dfu remove [--port PORT] [--baud RATE] [--timeout SEC]",
       mrbgems: "rpremote mrbgems SUBCOMMAND [--file FILE] [--lockfile FILE]",
       flash: "rpremote flash [--firmware FILE] [--language LANGUAGE] [--language-version VERSION] " \
              "[--board BOARD] [--cache DIR] [--mount DIR] [--port PORT] [--timeout SEC]",
@@ -19,12 +24,13 @@ module Rpremote
                    "[--cache DIR] [--firmware FILE] [--mrbgems FILE|--no-mrbgems] [--mount DIR] " \
                    "[--port PORT] [--baud RATE] [--timeout SEC]",
       ports: "rpremote ports",
-      run: "rpremote run FILE [--port PORT] [--baud RATE] [--timeout SEC] [--language LANGUAGE]",
+      run: "rpremote run FILE [--port PORT] [--baud RATE] [--timeout SEC] [--reset-on-timeout] [--language LANGUAGE]",
       monitor: "rpremote monitor [--port PORT] [--baud RATE] [--timeout SEC]",
       repl: "rpremote repl [--port PORT] [--baud RATE] [--timeout SEC]",
       exec: "rpremote exec CODE [--port PORT] [--baud RATE] [--timeout SEC] [--language LANGUAGE]",
       reset: "rpremote reset [--port PORT] [--baud RATE] [--timeout SEC]",
-      fs_cp: "rpremote fs cp SOURCE DESTINATION [--port PORT] [--baud RATE] [--timeout SEC]",
+      fs_cp: "rpremote fs cp SOURCE DESTINATION [--recursive] [--port PORT] [--baud RATE] [--timeout SEC]",
+      fs_push: "rpremote fs push LOCAL_DIR :/REMOTE_DIR [--port PORT] [--baud RATE] [--timeout SEC]",
       fs_cat: "rpremote fs cat :/REMOTE/PATH [--port PORT] [--baud RATE] [--timeout SEC]",
       fs_ls: "rpremote fs ls :/REMOTE/PATH [--port PORT] [--baud RATE] [--timeout SEC]",
       fs_rm: "rpremote fs rm :/REMOTE/PATH [--port PORT] [--baud RATE] [--timeout SEC]",
@@ -38,9 +44,12 @@ module Rpremote
         #{COMMAND_USAGE.fetch(:setup)}
         #{COMMAND_USAGE.fetch(:build)}
         #{COMMAND_USAGE.fetch(:build_clean)}
+        #{COMMAND_USAGE.fetch(:bootsel)}
+        #{COMMAND_USAGE.fetch(:deploy)}
         #{COMMAND_USAGE.fetch(:dfu_app)}
         #{COMMAND_USAGE.fetch(:dfu_compile)}
         #{COMMAND_USAGE.fetch(:dfu_status)}
+        #{COMMAND_USAGE.fetch(:dfu_remove)}
         #{COMMAND_USAGE.fetch(:mrbgems).sub("SUBCOMMAND", "check|list|lock|update")}
         #{COMMAND_USAGE.fetch(:flash)}
         #{COMMAND_USAGE.fetch(:config_show)}
@@ -51,6 +60,7 @@ module Rpremote
         #{COMMAND_USAGE.fetch(:exec)}
         #{COMMAND_USAGE.fetch(:reset)}
         #{COMMAND_USAGE.fetch(:fs_cp)}
+        #{COMMAND_USAGE.fetch(:fs_push)}
         #{COMMAND_USAGE.fetch(:fs_cat)}
         #{COMMAND_USAGE.fetch(:fs_ls)}
         #{COMMAND_USAGE.fetch(:fs_rm)}
@@ -66,11 +76,11 @@ module Rpremote
         --language-version VERSION
                           use R2P2/PicoRuby 4.0.3 or 3.4.2 (default: 4.0.3)
         --cache DIR       use another project cache directory
-        --mrbgems FILE    use an explicit Mrbgems definition during build
-        --no-mrbgems      build without the automatically detected Mrbgems
+        --mrbgems FILE    use an explicit Mrbgems definition during build or deploy
+        --no-mrbgems      build or deploy without the automatically detected Mrbgems
         --board BOARD
                           select pico2 or pico2_w (default: pico2)
-        --firmware FILE   build to, or flash from, this UF2 path
+        --firmware FILE   build to, or deploy or flash from, this UF2 path
         --language LANGUAGE
                           select the remote language (default: picoruby)
         --config FILE     use another configuration file
@@ -93,6 +103,8 @@ module Rpremote
       case command
       when "setup" then setup_text
       when "build" then args.first == "clean" ? build_clean_text : build_text
+      when "bootsel" then bootsel_text
+      when "deploy" then deploy_text
       when "dfu" then dfu_text(args.first)
       when "mrbgems" then mrbgems_text(args.first)
       when "flash" then flash_text
@@ -112,7 +124,7 @@ module Rpremote
       <<~HELP
         Usage: #{COMMAND_USAGE.fetch(:setup)}
 
-        Creates config/setting.json when it does not exist, then downloads and prepares PicoRuby source.
+        Creates config/setting.json when it does not exist, then downloads and prepares PicoRuby source and the official Raspberry Pi nuke_universal.uf2 firmware.
         Options: --language LANGUAGE (picoruby), --language-version VERSION (4.0.3), --cache DIR (firmware), --force.
         This changes the project configuration and source cache but does not connect to a board.
       HELP
@@ -136,15 +148,40 @@ module Rpremote
       HELP
     end
 
+    def self.deploy_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:deploy)}
+
+        Builds the selected custom UF2, enters BOOTSEL when needed, flashes the firmware, and waits for the R2P2 Shell to become ready.
+        If PATH/lib/NAME exists, it copies it to :/lib/NAME, where NAME is the final component of PATH. It then runs PATH/main.rb and preserves its Shell job, so hardware output remains active until the next command.
+        The stages run in order and stop at the first failure. Flashing replaces persistent board firmware.
+        deploy requires PicoRuby 4.x firmware (currently 4.0.3).
+        Options combine build, BOOTSEL, flash, library-copy, and run settings. The first install of firmware with automatic BOOTSEL still requires holding BOOTSEL.
+      HELP
+    end
+
+    def self.bootsel_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:bootsel)}
+
+        Asks the running R2P2 firmware to restart as an RP2350 BOOTSEL USB volume, then waits for that volume to appear.
+        By default it does not write firmware. This requires firmware built by a current rpremote; use physical BOOTSEL once to install it first.
+        --reset-flash-memory copies the official Raspberry Pi nuke_universal.uf2 in BOOTSEL mode and erases all external flash memory.
+        After resetting flash memory, wait for BOOTSEL to reappear and run `rpremote flash` to install R2P2 again.
+      HELP
+    end
+
     def self.dfu_text(subcommand)
       return dfu_app_text if subcommand == "app"
       return dfu_compile_text if subcommand == "compile"
       return dfu_status_text if subcommand == "status"
+      return dfu_remove_text if subcommand == "remove"
 
       <<~HELP
         Usage: #{COMMAND_USAGE.fetch(:dfu_app)}
                #{COMMAND_USAGE.fetch(:dfu_compile)}
                #{COMMAND_USAGE.fetch(:dfu_status)}
+               #{COMMAND_USAGE.fetch(:dfu_remove)}
 
         Stages and inspects PicoModem DFU applications. Run `rpremote dfu SUBCOMMAND --help` for details.
       HELP
@@ -178,6 +215,16 @@ module Rpremote
       HELP
     end
 
+    def self.dfu_remove_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:dfu_remove)}
+
+        Permanently removes the Ruby source and bytecode applications from both DFU A/B slots and resets their metadata.
+        Run `rpremote reset` afterward to stop the application already running in RAM. It does not remove /home/app.rb,
+        /home/app.mrb, other files, embedded mrbgems, or R2P2 firmware.
+      HELP
+    end
+
     def self.mrbgems_text(subcommand)
       action = subcommand || "check|list|lock|update"
       <<~HELP
@@ -217,8 +264,10 @@ module Rpremote
       <<~HELP
         Usage: #{COMMAND_USAGE.fetch(:run)}
 
-        Uploads FILE to R2P2, relays output, then removes the temporary remote file. Defaults are the automatic CDC 0 port,
-        115200 baud, 20 seconds, and picoruby. It exits nonzero when compatible R2P2 firmware reports a Ruby exception.
+        Uploads FILE to R2P2, or main.rb when FILE is a directory, relays output, then removes the temporary remote file. Defaults are the automatic CDC 0 port,
+        115200 baud, a 20-second idle timeout, and picoruby. Output from the running program resets the idle timeout.
+        It exits nonzero when compatible R2P2 firmware reports a Ruby exception.
+        --reset-on-timeout resets R2P2 after the run times out and the serial connection has closed.
       HELP
     end
 
@@ -227,7 +276,8 @@ module Rpremote
         Usage: #{COMMAND_USAGE.fetch(:exec)}
 
         Runs short Ruby CODE through a temporary remote file, then removes it. Defaults are the automatic CDC 0 port,
-        115200 baud, 20 seconds, and picoruby. It exits nonzero when compatible R2P2 firmware reports a Ruby exception.
+        115200 baud, a 20-second idle timeout, and picoruby. Output from the running program resets the idle timeout.
+        It exits nonzero when compatible R2P2 firmware reports a Ruby exception.
       HELP
     end
 
@@ -256,10 +306,11 @@ module Rpremote
     end
 
     def self.fs_text(subcommand)
-      return fs_subcommand_text(subcommand) if %w[cp cat ls rm mkdir].include?(subcommand)
+      return fs_subcommand_text(subcommand) if %w[cp push cat ls rm mkdir].include?(subcommand)
 
       <<~HELP
         Usage: #{COMMAND_USAGE.fetch(:fs_cp)}
+               #{COMMAND_USAGE.fetch(:fs_push)}
                #{COMMAND_USAGE.fetch(:fs_cat)}
                #{COMMAND_USAGE.fetch(:fs_ls)}
                #{COMMAND_USAGE.fetch(:fs_rm)}
@@ -274,7 +325,9 @@ module Rpremote
       effect = case subcommand
                when "rm" then "Deletes the remote path permanently."
                when "mkdir" then "Creates a remote directory."
-               else "Reads or transfers remote files."
+               when "cp" then "Transfers one file, or recursively uploads a local directory with --recursive."
+               when "push" then "Creates missing remote directories and recursively uploads a local directory."
+               else "Reads remote files."
                end
       <<~HELP
         Usage: #{usage}

data/lib/rpremote/mrbgems.rb

@@ -14,7 +14,7 @@ module Rpremote
     COMMIT_PATTERN = /\A[0-9a-f]{40,64}\z/i
     VMS = %i[mruby mrubyc].freeze
 
-    Dependency = Data.define(:type, :source, :branch, :commit, :path)
+    Dependency = Data.define(:type, :source, :branch, :commit, :path, :require_name)
     Overlay = Data.define(:path, :fingerprint)
 
     class Error < Rpremote::Error; end
@@ -68,6 +68,20 @@ module Rpremote
       raise LockError, "invalid mrbgems lock file #{lock_path}: #{e.message}"
     end
 
+    def require_names
+      lock_data = read_lock(required: false)
+      return [] unless lock_data
+
+      lock_data.fetch("gems").filter_map { |gem| gem["require_name"] }.uniq
+    end
+
+    def prepend_requires(source)
+      names = require_names
+      return source if names.empty?
+
+      names.map { |name| "require #{name.inspect}\n" }.join.b + source.b
+    end
+
     def generate_overlay(base_config:, target:, directory:, update: false)
       lock_data = lock(update: update)
       fingerprint = build_fingerprint(base_config, lock_data)
@@ -109,10 +123,12 @@ module Rpremote
           dependency.source, dependency.branch
         )
         { "type" => "github", "source" => dependency.source,
-          "branch" => dependency.branch, "commit" => validate_commit!(commit) }
+          "branch" => dependency.branch, "commit" => validate_commit!(commit),
+          "require_name" => dependency.require_name }.compact
       else
         { "type" => "path", "source" => dependency.source,
-          "sha256" => digest_directory(dependency.path) }
+          "sha256" => digest_directory(dependency.path),
+          "require_name" => dependency.require_name || local_require_name(dependency.path) }.compact
       end
     end
 
@@ -184,12 +200,22 @@ module Rpremote
 
     def valid_github_lock?(entry)
       GITHUB_PATTERN.match?(entry["source"].to_s) && !entry["branch"].to_s.empty? &&
-        COMMIT_PATTERN.match?(entry["commit"].to_s)
+        COMMIT_PATTERN.match?(entry["commit"].to_s) && valid_require_name?(entry["require_name"])
     end
 
     def valid_path_lock?(entry)
       entry["type"] == "path" && !entry["source"].to_s.empty? &&
-        /\A[0-9a-f]{64}\z/.match?(entry["sha256"].to_s)
+        /\A[0-9a-f]{64}\z/.match?(entry["sha256"].to_s) && valid_require_name?(entry["require_name"])
+    end
+
+    def valid_require_name?(name)
+      name.nil? || (name.is_a?(String) && !name.empty? && !name.match?(/[\x00-\x1f\x7f]/))
+    end
+
+    def local_require_name(directory)
+      source = File.read(File.join(directory, "mrbgem.rake"))
+      match = source.match(/^\s*spec\.require_name\s*=\s*["']([^"']+)["']\s*$/)
+      match && match[1]
     end
 
     def build_fingerprint(base_config, lock_data)
@@ -246,14 +272,17 @@ module Rpremote
         @vm_name = value
       end
 
-      def gem(github: nil, path: nil, branch: "main", commit: nil)
+      def gem(github: nil, path: nil, branch: "main", commit: nil, require: nil)
         sources = [github, path].compact
         raise DefinitionError, "gem requires exactly one of github or path" unless sources.length == 1
+        unless require.nil? || (require.is_a?(String) && !require.empty? && !require.match?(/[\x00-\x1f\x7f]/))
+          raise DefinitionError, "invalid mrbgem require name: #{require.inspect}"
+        end
 
         dependency = if github
-                       github_dependency(github, branch, commit)
+                       github_dependency(github, branch, commit, require)
                      else
-                       path_dependency(path, branch, commit)
+                       path_dependency(path, branch, commit, require)
                      end
         key = [dependency.type, dependency.source]
         raise DefinitionError, "duplicate mrbgem: #{dependency.source}" if dependencies.any? do |item|
@@ -267,21 +296,21 @@ module Rpremote
 
       attr_reader :directory
 
-      def github_dependency(source, branch, commit)
+      def github_dependency(source, branch, commit, require_name)
         raise DefinitionError, "invalid GitHub mrbgem: #{source.inspect}" unless GITHUB_PATTERN.match?(source.to_s)
         raise DefinitionError, "GitHub mrbgem branch must not be empty" if branch.to_s.empty?
         raise DefinitionError, "invalid Git commit: #{commit.inspect}" if commit && !COMMIT_PATTERN.match?(commit.to_s)
 
         Dependency.new(type: :github, source: source, branch: branch,
-                       commit: commit&.downcase, path: nil)
+                       commit: commit&.downcase, path: nil, require_name: require_name)
       end
 
-      def path_dependency(source, branch, commit)
+      def path_dependency(source, branch, commit, require_name)
         raise DefinitionError, "local mrbgem path must not be empty" if source.to_s.empty?
         raise DefinitionError, "local mrbgem does not accept branch or commit" if branch != "main" || commit
 
         Dependency.new(type: :path, source: source, branch: nil, commit: nil,
-                       path: File.expand_path(source, directory))
+                       path: File.expand_path(source, directory), require_name: require_name)
       end
     end
   end

data/lib/rpremote/nuke_firmware.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "net/http"
+require "timeout"
+require "uri"
+
+module Rpremote
+  class NukeFirmware
+    URL = "https://github.com/raspberrypi/pico-sdk-prebuilts/releases/latest/download/nuke_universal.uf2"
+    FILENAME = "nuke_universal.uf2"
+    MAX_REDIRECTS = 5
+
+    class DownloadError < Rpremote::Error; end
+
+    def initialize(directory: Target::DEFAULT_CACHE_DIR, fetcher: nil)
+      @directory = File.expand_path(directory)
+      @fetcher = fetcher || method(:download)
+    end
+
+    def setup(force: false)
+      FileUtils.mkdir_p(directory)
+      return path if File.size?(path) && !force
+
+      temporary = "#{path}.part"
+      File.binwrite(temporary, fetcher.call(URL))
+      raise DownloadError, "downloaded nuke_universal.uf2 is empty" unless File.size?(temporary)
+
+      File.rename(temporary, path)
+      path
+    rescue SystemCallError => e
+      raise DownloadError, "cannot store nuke_universal.uf2: #{e.message}"
+    ensure
+      FileUtils.rm_f(temporary) if temporary
+    end
+
+    private
+
+    attr_reader :directory, :fetcher
+
+    def path
+      File.join(directory, FILENAME)
+    end
+
+    def download(url, redirects = MAX_REDIRECTS)
+      raise DownloadError, "too many redirects while downloading nuke_universal.uf2" if redirects.negative?
+
+      uri = URI(url)
+      raise DownloadError, "nuke_universal.uf2 download requires HTTPS" unless uri.is_a?(URI::HTTPS)
+
+      request = Net::HTTP::Get.new(uri)
+      request["User-Agent"] = "rpremote/#{Rpremote::VERSION}"
+      response = Net::HTTP.start(
+        uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 60
+      ) { |http| http.request(request) }
+
+      case response
+      when Net::HTTPSuccess then response.body
+      when Net::HTTPRedirection
+        location = response["location"]
+        raise DownloadError, "nuke_universal.uf2 download redirect has no location" unless location
+
+        download(URI.join(url, location).to_s, redirects - 1)
+      else
+        raise DownloadError, "nuke_universal.uf2 download failed: HTTP #{response.code} #{response.message}"
+      end
+    rescue SocketError, SystemCallError, Timeout::Error => e
+      raise DownloadError, "nuke_universal.uf2 download failed: #{e.message}"
+    end
+  end
+end

data/lib/rpremote/picoruby_source_patch.rb

@@ -3,6 +3,7 @@
 module Rpremote
   class PicoRubySourcePatch
     JOB_PATH = "mrbgems/picoruby-shell/mrblib/job.rb"
+    BOOTSEL_PATH = "mrbgems/picoruby-machine/include/machine.h"
     PATCH_ALIASES = { "3.4.2" => "3.4.5" }.freeze
 
     class Error < Rpremote::Error; end
@@ -14,19 +15,35 @@ module Rpremote
     end
 
     def apply(source)
+      return unless Dir.exist?(source)
+
       patch_version = PATCH_ALIASES.fetch(version, version)
-      patch = File.expand_path("../../patches/picoruby-#{patch_version}-ruby-exception-status.patch", __dir__)
-      return unless File.file?(patch) && File.file?(File.join(source, JOB_PATH))
-      return if git_apply?(source, patch, "--reverse", "--check")
+      patches(patch_version).each do |patch, prerequisite|
+        next unless File.file?(patch) && File.file?(File.join(source, prerequisite))
+        next if prerequisite == BOOTSEL_PATH && File.read(File.join(source, prerequisite)).include?("Machine_bootsel")
+
+        next if git_apply?(source, patch, "--reverse", "--check")
 
-      raise Error, "cannot apply rpremote patch to PicoRuby #{version}" unless git_apply?(source, patch, "--check")
-      raise Error, "cannot apply rpremote patch to PicoRuby #{version}" unless git_apply?(source, patch)
+        raise Error, "cannot apply rpremote patch to PicoRuby #{version}" unless git_apply?(source, patch, "--check")
+        raise Error, "cannot apply rpremote patch to PicoRuby #{version}" unless git_apply?(source, patch)
+      end
+      nil
     end
 
     private
 
+    def patches(patch_version)
+      definitions = {
+        "ruby-exception-status" => JOB_PATH,
+        "bootsel" => BOOTSEL_PATH
+      }
+      definitions.map do |name, prerequisite|
+        [File.expand_path("../../patches/picoruby-#{patch_version}-#{name}.patch", __dir__), prerequisite]
+      end
+    end
+
     def git_apply?(source, patch, *options)
-      system("git", "apply", *options, patch, chdir: source, out: File::NULL, err: File::NULL)
+      system("git", "apply", "--unidiff-zero", *options, patch, chdir: source, out: File::NULL, err: File::NULL)
     end
   end
 end