rpremote 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dfb50a1e7d831a80c938b09c267d0ffa38bbcba43c9c0d870d2bfd594fe5502
-  data.tar.gz: af28f94924f0d121960a32f58dda68d3927d02b69d8d7cf13ce1680307ecf36f
+  metadata.gz: 900c268660317e50ca480983f9993698adb35ab699a82d3e0539dfb583e03723
+  data.tar.gz: 5e506856f83d7a48f91481cb0ef377df70d4e6f348e922d3412d068c5012fa15
 SHA512:
-  metadata.gz: 0d9cbfdb48f779fdd0075e3712dac31a7ec815cc96b9779144b05a5970a24e8ee39ed7994eca120f55b248617173455ad951c8a431a0d3feb29a336b6be51875
-  data.tar.gz: e9a4d8a3aaf6de6a88adeac72ed27b880665a33621499c9ce062ea404bdd594361e08bc3a4d646dfbac48c50526046acdf24ef4d97895cff95d376a6fe62cf81
+  metadata.gz: 7fe7454fe617b0a31004b17ca7e38c681711e90d4bb7889a801092fad8089246e7a1a93d89ff48058a320d60488bd825400b0bfded5380bd8f77d5bde8bded45
+  data.tar.gz: cd79792554f9174f2c416794f5973a3e5090f9494ea54ce22ca96bd21cbb72ef1dda7188b78eb9d5939f3dc44b8fcbd003bac772d41e7b13c24436bc9315f034

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.3.0 - 2026-08-28
+
+- Add `bootsel` to ask supported R2P2 firmware to enter USB BOOTSEL mode without pressing the button.
+- Add `bootsel --reset-flash-memory` to erase Raspberry Pi Pico external flash memory with the official universal erase UF2, whether BOOTSEL is already mounted or entered through R2P2.
+- Have `setup` download Raspberry Pi's official `nuke_universal.uf2` into `firmware/`; `--force` refreshes the downloaded file.
+- Change `deploy FILE` to `deploy PATH`: build and flash mrbgem-enabled firmware, recursively copy `PATH/lib/NAME` to `:/lib/NAME`, then temporarily run `PATH/main.rb`.
+- Add `fs cp --recursive LOCAL_DIR :/REMOTE_DIR` and its `fs push` alias to create missing remote directories and upload a local directory tree in one command.
+- Add `dfu remove` to permanently clear both DFU boot-application slots; a separate `reset` stops an application already running in RAM.
+- Improve `run`: accept a project directory and run its `main.rb`, treat `--timeout` as an idle timeout while output continues, add `--reset-on-timeout`, and print upload, execution, cleanup, and error diagnostics to stderr.
+- Reuse one temporary remote path for `run` and `exec`, so a failed cleanup cannot accumulate temporary files on the device.
+- Read mrbgem `require_name` values from `Mrbgems.lock` and automatically prepend the corresponding `require` calls to `run`, `exec`, and `deploy`; allow `Mrbgems` entries to specify `require:` explicitly.
+- Change `flash` to accept an explicit UF2 only through `--firmware FILE`; positional UF2 arguments are no longer supported.
+- Improve RP2350 BOOTSEL flashing on macOS by accepting the expected `ENXIO` volume-detach race after a successful copy.
+- Add PicoRuby mrbgem examples for BMI270, HC-SR04 temperature, MAX30102, MPU6050, and WS2812 SPI, plus oximeter and Processing project examples.
+
 ## 0.2.0 - 2026-08-26
 
 - Make `run` and `exec` exit nonzero when compatible R2P2 firmware reports a Ruby exception, while preserving real-time program output.
@@ -24,5 +39,6 @@ All notable changes to this project will be documented in this file.
 - rpremote currently supports PicoRuby only.
 - Supported boards are Raspberry Pi Pico 2 and Pico 2 W; serial commands currently require macOS.
 - `rpremote run` and `exec` are temporary R2P2 executions, not persistent deployments. Use `build` and `flash` to replace firmware.
+- `rpremote deploy` requires PicoRuby 4.x firmware; use `build`, `flash`, `fs push`, and `run` separately with PicoRuby 3.4.x.
 - PicoModem DFU updates only the boot application. Changes to PicoRuby, R2P2, or embedded mrbgems require rebuilding and flashing a UF2.
 - DFU retains the complete application in RAM before writing flash. Verify available memory, bytecode compatibility, boot confirmation, and rollback on target hardware.

data/README.ja.md

@@ -30,6 +30,14 @@ rpremote flash --mount /Volumes/RP2350
 rpremote run main.rb
 ```
 
+`setup`はRaspberry Pi公式のリセット用`nuke_universal.uf2`も`firmware/`へダウンロードします。
+
+再利用するRubyコードを`lib/NAME`へ置くプロジェクトでは、`deploy`がファームウェアをビルドして書き込み、そのディレクトリをR2P2へコピーしてからエントリーファイルを実行します。
+
+```sh
+rpremote deploy path/to/project
+```
+
 既定では`firmware/picoruby-4.0.3/`にソースを準備し、`firmware/picoruby-4.0.3-pico2.uf2`を生成します。対象ボードを明示する必要がある場合は、`rpremote ports`でR2P2のCDC 0ポートを確認してください。
 
 ## mrbgemを追加する
@@ -69,18 +77,22 @@ rpremote flash --language picoruby --language-version 3.4.2 --board pico2 --moun
 | `rpremote setup` | 設定を作成し、言語ソースを準備します。 |
 | `rpremote build` | mrbgemを含むカスタムUF2をビルドします。 |
 | `rpremote build clean` | 中間ビルドファイルを削除します。 |
+| `rpremote bootsel` | 実行中のR2P2へBOOTSEL移行を要求し、USBボリュームの出現を待ちます。 |
+| `rpremote deploy PATH` | ファームウェアをビルドして書き込み、存在する場合は`PATH/lib/NAME`を`:/lib/NAME`へコピーしてから`PATH/main.rb`を実行します。ハードウェア出力は次のコマンドまで維持されます。 |
 | `rpremote dfu app FILE` | PicoModem DFUでRubyまたは版を照合したバイトコードのアプリを更新します。 |
 | `rpremote dfu compile FILE` | DFU用にPicoRuby版と一致する`.mrb`を生成します。 |
 | `rpremote dfu status` | DFUのアクティブおよび起動候補スロットを表示します。 |
+| `rpremote dfu remove` | DFU起動アプリを両スロットから削除します。実行中のアプリを停止するには別途リセットします。 |
 | `rpremote mrbgems …` | mrbgemを検査、表示、固定、更新します。 |
 | `rpremote flash` | 選択したUF2をBOOTSEL経由で書き込みます。 |
+| `rpremote bootsel --reset-flash-memory` | BOOTSELへ移行し、Pico 2の外部フラッシュメモリ全体を消去します。 |
 | `rpremote config show` | 設定ファイルとコマンドラインオプションを反映した実効設定を表示します。 |
 | `rpremote ports` | R2P2シリアルポートを表示します。 |
-| `rpremote run FILE` | Rubyファイルを転送して実行し、出力をリアルタイム表示します。Ruby例外時は非0で終了します。 |
+| `rpremote run FILE` | Rubyファイルを転送して実行します。ディレクトリ指定時は`main.rb`を実行し、出力をリアルタイム表示します。タイムアウトは無出力の継続時間として扱い、Ruby例外時は非0で終了します。`--reset-on-timeout`を指定すると実行タイムアウト後にR2P2をリセットします。 |
 | `rpremote exec CODE` | 短いRubyコードを実行します。Ruby例外時は非0で終了します。 |
 | `rpremote monitor` / `repl` | 対話型シリアルセッションを開きます。 |
 | `rpremote reset` | R2P2を再起動して再接続まで待ちます。 |
-| `rpremote fs cp/cat/ls/rm/mkdir` | R2P2ファイルシステムを操作します。 |
+| `rpremote fs cp/push/cat/ls/rm/mkdir` | R2P2ファイルシステムを操作します。 |
 
 コマンド一覧は`rpremote --help`で確認できます。コマンド固有の構文、既定値、影響は`rpremote <command> --help`で確認できます。
 
@@ -96,9 +108,11 @@ rpremote dfu app --help
 ## 操作モデル
 
 - `run`と`exec`はRubyコードを一時的に転送・実行して出力を表示し、一時リモートファイルを削除します。対応するR2P2ファームウェアがRuby例外を報告した場合は、非0で終了します。
+- `deploy PATH`はファームウェアをビルドし、BOOTSELへ移行して書き込んだ後、R2P2 Shellの起動完了を待ちます。存在する場合は`PATH/lib/NAME`を`:/lib/NAME`へコピーし、実行直前に読み込んだ`PATH/main.rb`を実行します。Shellジョブを保持するため、ハードウェア出力は次のコマンドまで維持されます。正常終了と出力バイト数を表示し、R2P2のRuby例外はコマンド失敗として扱います。ライブラリディレクトリがない場合、コピー処理はスキップします。PicoRuby 4系のファームウェアが必要です。
 - `flash`はUF2をRP2350 BOOTSELボリュームへコピーし、永続的なR2P2ファームウェアを置き換えます。
 - `dfu app`はRubyソースまたは対応するバイトコードのアプリを非アクティブDFUスロットへ登録します。R2P2を再起動して試行し、正常に起動したアプリは`DFU.confirm`を呼び出します。
-- リモートパスには`:/REMOTE/PATH`を使います。`fs cp`はローカルパスとリモートパスの間で転送し、`fs rm`は指定したリモートパスを完全に削除します。
+- `dfu remove`はDFUのA/B両アプリスロットを完全に空にします。RAM上ですでに動作しているアプリは`rpremote reset`を実行するまで継続するため、起動アプリのログを混ぜずに`rpremote run`を使う場合は両方のコマンドを実行します。その他の`/home`ファイルとR2P2ファームウェアは削除しません。
+- リモートパスには`:/REMOTE/PATH`を使います。`fs cp`はローカルパスとリモートパスの間で転送します。`fs push LOCAL_DIR :/REMOTE_DIR`は`fs cp --recursive`の別名で、不足しているリモートディレクトリを作成し、ローカルディレクトリの内容を一括転送します。リモートにだけ存在するファイルは削除しません。`fs rm`は指定したリモートパスを完全に削除します。
 
 ## ドキュメントとサンプル
 

data/README.md

@@ -30,6 +30,14 @@ rpremote flash --mount /Volumes/RP2350
 rpremote run main.rb
 ```
 
+`setup` also downloads the official Raspberry Pi `nuke_universal.uf2` reset firmware into `firmware/`.
+
+For a project that stores reusable Ruby code in `lib/NAME`, `deploy` builds and flashes the firmware, copies that directory to R2P2, and then runs its entry file:
+
+```sh
+rpremote deploy path/to/project
+```
+
 The defaults prepare `firmware/picoruby-4.0.3/` and create `firmware/picoruby-4.0.3-pico2.uf2`. Use `rpremote ports` to locate the R2P2 CDC 0 port when a board must be selected explicitly.
 
 ## Add mrbgems
@@ -69,18 +77,22 @@ Command-line options override `config/setting.json`. PicoRuby is implemented tod
 | `rpremote setup` | Create configuration and prepare language sources. |
 | `rpremote build` | Build a custom UF2 with project mrbgems. |
 | `rpremote build clean` | Remove intermediate build files. |
+| `rpremote bootsel` | Ask the running R2P2 firmware to enter BOOTSEL and wait for its USB volume. |
+| `rpremote deploy PATH` | Build and flash firmware, copy `PATH/lib/NAME` to `:/lib/NAME` when present, then run `PATH/main.rb` while preserving its hardware output until the next command. |
 | `rpremote dfu app FILE` | Stage a Ruby or version-checked bytecode app through PicoModem DFU. |
 | `rpremote dfu compile FILE` | Compile `.rb` to matching PicoRuby bytecode for DFU. |
 | `rpremote dfu status` | Show the active and candidate DFU slots. |
+| `rpremote dfu remove` | Remove both DFU boot applications; reset separately to stop one already running. |
 | `rpremote mrbgems …` | Check, list, lock, or update mrbgems. |
 | `rpremote flash` | Flash the selected UF2 through BOOTSEL. |
+| `rpremote bootsel --reset-flash-memory` | Enter BOOTSEL and erase all Pico 2 external flash memory. |
 | `rpremote config show` | Show the effective configuration after file and command-line options are resolved. |
 | `rpremote ports` | List detected R2P2 serial ports. |
-| `rpremote run FILE` | Upload and run a Ruby file with real-time output; exit nonzero on a Ruby exception. |
+| `rpremote run FILE` | Upload and run a Ruby file, or `main.rb` when FILE is a directory, with real-time output; exit nonzero on a Ruby exception. The timeout measures idle time without output. Use `--reset-on-timeout` to reset R2P2 after a run timeout. |
 | `rpremote exec CODE` | Run short Ruby code and exit nonzero on a Ruby exception. |
 | `rpremote monitor` / `repl` | Open an interactive serial session. |
 | `rpremote reset` | Reboot R2P2 and wait for reconnection. |
-| `rpremote fs cp/cat/ls/rm/mkdir` | Operate on the R2P2 filesystem. |
+| `rpremote fs cp/push/cat/ls/rm/mkdir` | Operate on the R2P2 filesystem. |
 
 Run `rpremote --help` for the complete command list. Run `rpremote <command> --help` for command-specific syntax, defaults, and effects.
 
@@ -97,9 +109,11 @@ UF2 files built with `rpremote build` from the [GitHub repository](https://githu
 ## Operation model
 
 - `run` and `exec` upload Ruby code temporarily, relay output, then remove the temporary remote file. A Ruby exception reported by compatible R2P2 firmware makes the command exit nonzero.
+- `deploy PATH` builds the selected firmware, enters BOOTSEL, flashes it, waits until the R2P2 Shell is ready, copies `PATH/lib/NAME` to `:/lib/NAME` when present, then runs the current contents of `PATH/main.rb`. Its Shell job is retained so hardware output remains active until the next command. It reports successful completion and the output byte count; an R2P2 Ruby exception remains a command failure. If the library directory is absent, the copy step is skipped. It requires PicoRuby 4.x firmware.
 - `flash` copies a UF2 to the RP2350 BOOTSEL volume and replaces persistent R2P2 firmware.
 - `dfu app` stages a Ruby source or matching bytecode app in the inactive DFU slot. Restart R2P2 to try it; a successful app must call `DFU.confirm`.
-- Remote paths use `:/REMOTE/PATH`. `fs cp` transfers between one local and one remote path, and `fs rm` permanently deletes the selected remote path.
+- `dfu remove` permanently clears both DFU A/B application slots. The application already loaded in RAM continues until you run `rpremote reset`; use both commands before `rpremote run` when boot-app output would be unwanted. It does not remove other `/home` files or R2P2 firmware.
+- Remote paths use `:/REMOTE/PATH`. `fs cp` transfers between one local and one remote path. `fs push LOCAL_DIR :/REMOTE_DIR` is an alias of `fs cp --recursive`; it creates missing remote directories and uploads the local directory contents. It does not delete remote files. `fs rm` permanently deletes the selected remote path.
 
 ## Documentation and examples
 

data/RELEASING.md

@@ -48,7 +48,7 @@ bundle exec rake release
 After the tag exists on GitHub, create a GitHub Release and attach the exact gem that passed validation. `--verify-tag` prevents GitHub CLI from silently creating a tag at another commit:
 
 ```sh
-gh release create v0.1.0 rpremote-0.1.0.gem --verify-tag --generate-notes
+gh release create v0.3.0 rpremote-0.3.0.gem --verify-tag --generate-notes
 ```
 
-Replace `0.1.0` in both places for later versions. Finally, install from RubyGems.org in a fresh environment and run `rpremote --version`.
+Replace `0.3.0` in both places for later versions. Finally, install from RubyGems.org in a fresh environment and run `rpremote --version`.

data/THIRD_PARTY_NOTICES.md

@@ -2,6 +2,10 @@
 
 `rpremote` does not bundle R2P2 firmware. The `setup` command downloads a selected PicoRuby/R2P2 4.0.3 or 3.4.2 release from the PicoRuby project and verifies its published SHA-256 digest.
 
+`setup` also downloads Raspberry Pi's `nuke_universal.uf2` from the official Pico SDK prebuilts release. It is used only by `rpremote bootsel --reset-flash-memory` to erase external flash memory.
+
+Source: <https://github.com/raspberrypi/pico-sdk-prebuilts/releases/latest/download/nuke_universal.uf2>
+
 ## PicoRuby and R2P2
 
 Source: <https://github.com/picoruby/picoruby>

data/lib/rpremote/bootsel_command.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Rpremote
+  class BootselCommand
+    SHELL_READY_TIMEOUT = 2.0
+    RETRY_INTERVAL = 0.25
+    RESET_FLASH_FIRMWARE = File.join("firmware", "nuke_universal.uf2").freeze
+
+    class Error < Rpremote::Error; end
+
+    def self.run(args, defaults:, output: $stdout, services: {})
+      options = parse_options(args, defaults)
+      raise ArgumentError, "bootsel does not accept arguments" unless args.empty?
+
+      reset_flasher = nil
+      if options[:reset_flash_memory]
+        flasher = services.fetch(:flasher, Flasher)
+        reset_flasher = flasher.new(timeout: options[:timeout])
+        target = reset_flasher.find_mounted(options[:mount])
+        output.puts("BOOTSEL ready: #{target}") if target
+      end
+      target ||= enter(**options.slice(:mount, :port, :baud, :timeout), output: output, services: services)
+      reset_flash_memory(target, output: output, flasher: reset_flasher) if options[:reset_flash_memory]
+      target
+    end
+
+    def self.reset_flash_memory(target, output:, flasher:)
+      firmware_path = File.expand_path(RESET_FLASH_FIRMWARE, Dir.pwd)
+      raise Error, "reset firmware not found: #{firmware_path}; run `rpremote setup` first" unless File.file?(firmware_path)
+
+      output.puts("resetting Raspberry Pi Pico 2 external flash memory through #{target}; this erases all stored data and firmware")
+      flasher.flash(firmware_path, mount: target, wait_for_port: false)
+      output.puts("Pico 2 external flash memory reset; wait for the RP2350 BOOTSEL drive, then run `rpremote flash` to install R2P2")
+    end
+    private_class_method :reset_flash_memory
+
+    def self.enter(mount:, port:, baud:, timeout:, output:, services: {})
+      serial = services.fetch(:serial, Serial)
+      device = services.fetch(:device, Device)
+      shell = services.fetch(:shell, Shell)
+      flasher = services.fetch(:flasher, Flasher)
+      sleeper = services.fetch(:sleeper) { ->(seconds) { sleep(seconds) } }
+      clock = services.fetch(:clock) { -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) } }
+      deadline = clock.call + timeout
+
+      request_bootsel(
+        port: port, baud: baud, deadline: deadline, output: output,
+        serial: serial, device: device, shell: shell, sleeper: sleeper, clock: clock
+      )
+
+      remaining = deadline - clock.call
+      raise Error, "timed out waiting for R2P2 Shell to accept a BOOTSEL request" unless remaining.positive?
+
+      target = flasher.new(timeout: remaining).wait_for_mount(mount: mount)
+      output.puts("BOOTSEL ready: #{target}")
+      target
+    end
+
+    def self.request_bootsel(context)
+      port = context.fetch(:port)
+      baud = context.fetch(:baud)
+      deadline = context.fetch(:deadline)
+      output = context.fetch(:output)
+      serial = context.fetch(:serial)
+      device = context.fetch(:device)
+      shell = context.fetch(:shell)
+      sleeper = context.fetch(:sleeper)
+      clock = context.fetch(:clock)
+      announced = false
+
+      loop do
+        port_path = device.main_port(port)
+        unless announced
+          output.puts("entering BOOTSEL mode: #{port_path}")
+          announced = true
+        end
+
+        requested = false
+        serial.open(port_path, baud: baud) do |connection|
+          remaining = deadline - clock.call
+          raise Shell::TimeoutError, "R2P2 Shell is not ready" unless remaining.positive?
+
+          remote_shell = shell.new(connection, timeout: [remaining, SHELL_READY_TIMEOUT].min)
+          remote_shell.synchronize!
+          unless remote_shell.execute("type bootsel").include?("bootsel is")
+            raise Error, "connected R2P2 firmware does not support BOOTSEL reset; flash a current rpremote UF2 once while holding BOOTSEL"
+          end
+
+          remote_shell.send_command("bootsel")
+          requested = true
+        end
+        break if requested
+      rescue Device::NotFoundError, Serial::ConfigurationError, Shell::TimeoutError, IOError, SystemCallError
+        raise Error, "timed out waiting for R2P2 Shell to accept a BOOTSEL request" if clock.call >= deadline
+
+        sleeper.call(RETRY_INTERVAL)
+      end
+    end
+    private_class_method :request_bootsel
+
+    def self.parse_options(args, defaults)
+      options = {
+        mount: defaults[:mount],
+        port: defaults[:port],
+        baud: defaults.fetch(:baud, Serial::BAUD_RATE),
+        timeout: defaults.fetch(:timeout, Flasher::DEFAULT_TIMEOUT)
+      }
+      OptionParser.new do |parser|
+        parser.on("--mount DIR") { |value| options[:mount] = value }
+        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 }
+        parser.on("--reset-flash-memory") { options[:reset_flash_memory] = true }
+      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_options
+  end
+end

data/lib/rpremote/cli.rb

@@ -2,13 +2,17 @@
 
 require "optparse"
 require_relative "build_command"
+require_relative "bootsel_command"
 require_relative "config_show"
 require_relative "dfu_command"
+require_relative "deploy_command"
 require_relative "flash_command"
 require_relative "help"
 require_relative "mrbgems_command"
+require_relative "recursive_copy"
 require_relative "setup_command"
 
+# rubocop:disable Metrics/ClassLength
 module Rpremote
   class CLI
     def self.start(argv = ARGV, config: Config, **options)
@@ -64,7 +68,7 @@ module Rpremote
         ports(args)
       when "config"
         config_command(args)
-      when "setup", "flash", "build", "dfu", "mrbgems"
+      when "setup", "flash", "build", "bootsel", "deploy", "dfu", "mrbgems"
         project_command(command, args)
       when "run", "monitor", "repl", "exec", "reset", "fs"
         remote_command(command, args)
@@ -81,6 +85,21 @@ module Rpremote
         FlashCommand.run(args, defaults: config_options, output: stdout, flasher: flasher)
       when "build"
         BuildCommand.run(args, defaults: config_options, output: stdout, error: stderr)
+      when "bootsel"
+        BootselCommand.run(
+          args,
+          defaults: config_options,
+          output: stdout,
+          services: { flasher: flasher, serial: serial, device: device }
+        )
+      when "deploy"
+        DeployCommand.run(
+          args,
+          defaults: config_options,
+          output: stdout,
+          error: stderr,
+          services: { flasher: flasher, serial: serial, device: device }
+        )
       when "dfu"
         DfuCommand.run(args, defaults: config_options, output: stdout, services: { serial: serial, device: device })
       when "mrbgems"
@@ -119,10 +138,13 @@ module Rpremote
 
     def fs(args)
       subcommand = args.shift
+      recursive = subcommand == "cp" && (args.delete("--recursive") || args.delete("-r"))
       options = parse_connection_options(args)
       case subcommand
       when "cp"
-        copy(args, options)
+        copy(args, options, recursive: recursive)
+      when "push"
+        copy(args, options, recursive: true, command: "push")
       when "cat"
         cat(args, options)
       when "ls", "rm", "mkdir"
@@ -133,12 +155,14 @@ module Rpremote
     end
 
     def run_file(args)
+      reset_on_timeout = !args.delete("--reset-on-timeout").nil?
       options = parse_connection_options(args)
       raise ArgumentError, "usage: rpremote run FILE [options]" unless args.length == 1
 
       source = args.first
-      data = File.binread(source)
-      execute_temporary(data, options, output: stdout)
+      source = File.join(source, "main.rb") if File.directory?(source)
+      data = prepend_mrbgem_requires(File.binread(source))
+      execute_temporary(data, options, output: stdout, reset_on_timeout: reset_on_timeout)
     rescue Errno::ENOENT => e
       raise ArgumentError, e.message
     end
@@ -147,16 +171,32 @@ module Rpremote
       options = parse_connection_options(args)
       raise ArgumentError, "usage: rpremote exec CODE [options]" unless args.length == 1
 
-      execute_temporary(args.first, options, output: stdout)
+      execute_temporary(prepend_mrbgem_requires(args.first), options, output: stdout)
     end
 
-    def execute_temporary(data, options, output: nil)
+    def execute_temporary(data, options, output: nil, reset_on_timeout: false)
       Language.validate!(options[:language])
       port_path = device.main_port(options[:port])
       serial.open(port_path, baud: options[:baud]) do |port|
         runner = Runner.new(port, timeout: options[:timeout])
-        output ? runner.run(data, output: output) : runner.run(data)
+        output ? runner.run(data, output: output, diagnostics: stderr) : runner.run(data, diagnostics: stderr)
       end
+    rescue Shell::TimeoutError => e
+      reset_after_run_timeout(port_path, options, e) if reset_on_timeout
+      raise
+    end
+
+    def reset_after_run_timeout(port_path, options, timeout_error)
+      stderr.puts("rpremote: run timed out; resetting R2P2: #{port_path}")
+      Resetter.new(serial: serial, timeout: options[:timeout]).reset(port_path, baud: options[:baud])
+      stderr.puts("rpremote: reset R2P2 after run timeout: #{port_path}")
+    rescue Rpremote::Error, IOError, SystemCallError => e
+      raise Shell::TimeoutError,
+            "#{timeout_error.message}; automatic reset failed: #{e.message}"
+    end
+
+    def prepend_mrbgem_requires(data)
+      Mrbgems.new(cwd: Dir.pwd).prepend_requires(data)
     end
 
     def interactive(args, repl: false)
@@ -205,13 +245,15 @@ module Rpremote
       options
     end
 
-    def copy(args, options)
-      raise ArgumentError, "usage: rpremote fs cp SOURCE DESTINATION [options]" unless args.length == 2
+    def copy(args, options, recursive: false, command: "cp")
+      usage = command == "push" ? "rpremote fs push LOCAL_DIR :/REMOTE_DIR" : "rpremote fs cp SOURCE DESTINATION"
+      raise ArgumentError, "usage: #{usage} [options]" unless args.length == 2
 
       source, destination = args
       source_remote = RemotePath.remote?(source)
       destination_remote = RemotePath.remote?(destination)
       raise ArgumentError, "exactly one cp path must be remote (prefix remote paths with :)" if source_remote == destination_remote
+      return RecursiveCopy.new(output: stdout, serial: serial, device: device).call(source, destination, options) if recursive
 
       if source_remote
         data = with_modem(options) { |modem| modem.download(RemotePath.unwrap(source)) }
@@ -274,3 +316,4 @@ module Rpremote
     end
   end
 end
+# rubocop:enable Metrics/ClassLength

data/lib/rpremote/config.rb

@@ -21,6 +21,8 @@ module Rpremote
     COMMAND_OPTIONS = {
       "setup" => %i[cache language language_version],
       "build" => %i[cache language language_version board firmware mrbgems],
+      "bootsel" => %i[mount port baud timeout],
+      "deploy" => %i[cache language language_version board firmware mrbgems mount port baud timeout],
       "dfu" => %i[cache language language_version port baud timeout],
       "flash" => %i[cache language language_version board firmware mount port timeout],
       "run" => %i[port baud timeout language],

data/lib/rpremote/deploy_command.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "bootsel_command"
+require_relative "recursive_copy"
+
+module Rpremote
+  class DeployCommand
+    SHELL_READY_TIMEOUT = 2.0
+    RETRY_INTERVAL = 0.25
+
+    class Error < Rpremote::Error; end
+
+    # The command intentionally keeps the six deployment stages visible in execution order.
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def self.run(args, defaults:, output: $stdout, error: $stderr, services: {})
+      options = parse_options(args, defaults)
+      raise ArgumentError, "usage: rpremote deploy PATH [options]" unless args.length == 1
+
+      project = File.expand_path(args.first)
+      library, remote_library, source = project_files(project)
+      Language.validate!(options[:language])
+
+      builder = services.fetch(:builder) { Builder.new }
+      flasher = services.fetch(:flasher, Flasher)
+      serial = services.fetch(:serial, Serial)
+      device = services.fetch(:device, Device)
+      runner = services.fetch(:runner, Runner)
+      target_options = options.slice(:language, :language_version, :board, :cache_dir, :firmware)
+      firmware_path = Target.new(**target_options).firmware_path(root: Dir.pwd)
+
+      output.puts("deploy build: #{firmware_path}")
+      builder.build(
+        **target_options,
+        mrbgems: options[:mrbgems],
+        output: output,
+        error: error
+      )
+
+      flash_service = flasher.new(timeout: options[:timeout])
+      bootsel_mount = resolve_bootsel_mount(options, flash_service, output, services)
+
+      mount = options[:mount] || "an automatically detected RP2350 BOOTSEL volume"
+      output.puts("deploy flash: #{firmware_path} to #{mount}; this replaces persistent board firmware")
+      result = flash_service.flash(
+        firmware_path,
+        mount: bootsel_mount,
+        port: options[:port]
+      )
+
+      connection_options = options.merge(port: result.port)
+      output.puts("deploy connect: waiting for R2P2 Shell on #{result.port}")
+      wait_for_shell(
+        port: result.port, baud: options[:baud], timeout: options[:timeout], serial: serial,
+        shell: services.fetch(:shell, Shell),
+        sleeper: services.fetch(:sleeper) { ->(seconds) { sleep(seconds) } },
+        clock: services.fetch(:clock) { -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) } }
+      )
+      output.puts("deploy connect: ready on #{result.port}")
+
+      if File.directory?(library)
+        output.puts("deploy push: #{library} -> :#{remote_library}")
+        recursive_copy = services.fetch(:recursive_copy) do
+          RecursiveCopy.new(output: output, serial: serial, device: device)
+        end
+        recursive_copy.call(library, ":#{remote_library}", connection_options)
+      else
+        output.puts("deploy push: skipped; directory not found: #{library}")
+      end
+
+      output.puts("deploy run: #{source} on #{result.port}")
+      source_data = prepend_mrbgem_requires(File.binread(source), options[:mrbgems])
+      run_output = serial.open(result.port, baud: options[:baud]) do |port|
+        runner.new(port, timeout: options[:timeout]).run(
+          source_data, output: output, cleanup: false, remote_path: Runner::DEPLOY_REMOTE_PATH
+        )
+      end
+      output.puts("deploy run: completed; output bytes: #{run_output.to_s.bytesize}")
+    rescue Errno::ENOENT => e
+      raise ArgumentError, e.message
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    def self.project_files(project)
+      raise ArgumentError, "project directory not found: #{project}" unless File.directory?(project)
+
+      name = File.basename(project)
+      library = File.join(project, "lib", name)
+      source = File.join(project, "main.rb")
+      raise ArgumentError, "project entry file not found: #{source}" unless File.file?(source)
+
+      [library, File.join("/lib", name), source]
+    end
+    private_class_method :project_files
+
+    def self.prepend_mrbgem_requires(source, definition)
+      return source if definition == false
+
+      Mrbgems.new(path: definition || Mrbgems::DEFAULT_PATH, cwd: Dir.pwd).prepend_requires(source)
+    end
+    private_class_method :prepend_mrbgem_requires
+
+    def self.wait_for_shell(context)
+      port = context.fetch(:port)
+      baud = context.fetch(:baud)
+      timeout = context.fetch(:timeout)
+      serial = context.fetch(:serial)
+      shell = context.fetch(:shell)
+      sleeper = context.fetch(:sleeper)
+      clock = context.fetch(:clock)
+      deadline = clock.call + timeout
+      loop do
+        serial.open(port, baud:) do |connection|
+          remaining = deadline - clock.call
+          raise Shell::TimeoutError, "R2P2 Shell is not ready" unless remaining.positive?
+
+          shell.new(connection, timeout: [remaining, SHELL_READY_TIMEOUT].min).synchronize!
+        end
+        return
+      rescue Serial::ConfigurationError, Shell::TimeoutError, IOError, SystemCallError
+        raise Error, "timed out waiting for R2P2 Shell after flash" if clock.call >= deadline
+
+        sleeper.call(RETRY_INTERVAL)
+      end
+    end
+    private_class_method :wait_for_shell
+
+    def self.resolve_bootsel_mount(options, flash_service, output, services)
+      mounted = flash_service.find_mounted(options[:mount])
+      if mounted
+        output.puts("deploy bootsel: already mounted at #{mounted}; skipping serial reset")
+        return mounted
+      end
+
+      port = options[:port] || "an automatically detected R2P2 port"
+      output.puts("deploy bootsel: requesting USB BOOTSEL mode through #{port}")
+      BootselCommand.enter(
+        mount: options[:mount], port: options[:port], baud: options[:baud], timeout: options[:timeout],
+        output: output, services: services.slice(:flasher, :serial, :device, :shell)
+      )
+    end
+    private_class_method :resolve_bootsel_mount
+
+    def self.parse_options(args, defaults)
+      options = default_options(defaults)
+      option_parser(options).parse!(args)
+      validate_options!(options)
+      options
+    end
+    private_class_method :parse_options
+
+    def self.default_options(defaults)
+      {
+        language: defaults.fetch(:language, Target::DEFAULT_LANGUAGE),
+        language_version: defaults.fetch(:language_version, Target::DEFAULT_LANGUAGE_VERSION),
+        board: defaults.fetch(:board, Target::DEFAULT_BOARD),
+        cache_dir: defaults.fetch(:cache, Target::DEFAULT_CACHE_DIR),
+        firmware: defaults[:firmware],
+        mrbgems: defaults[:mrbgems],
+        mount: defaults[:mount],
+        port: defaults[:port],
+        baud: defaults.fetch(:baud, Serial::BAUD_RATE),
+        timeout: defaults.fetch(:timeout, Flasher::DEFAULT_TIMEOUT)
+      }
+    end
+    private_class_method :default_options
+
+    def self.option_parser(options)
+      OptionParser.new do |parser|
+        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 }
+        parser.on("--cache DIR") { |value| options[:cache_dir] = value }
+        parser.on("--firmware FILE") { |value| options[:firmware] = value }
+        parser.on("--mrbgems FILE") { |value| options[:mrbgems] = value }
+        parser.on("--no-mrbgems") { options[:mrbgems] = false }
+        parser.on("--mount DIR") { |value| options[:mount] = value }
+        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
+    end
+    private_class_method :option_parser
+
+    def self.validate_options!(options)
+      raise ArgumentError, "--baud must be positive" unless options[:baud].positive?
+      raise ArgumentError, "--timeout must be positive" unless options[:timeout].positive?
+    end
+    private_class_method :validate_options!
+  end
+end