rpremote 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ccf42c1aa0428ee4996626537122a820d94aac064a8bd40e15defb4b31c76901
-  data.tar.gz: f7d7ac9163993a8c8075861bb750ebda0ba9031f9c4393be77be93428eae5d2d
+  metadata.gz: 900c268660317e50ca480983f9993698adb35ab699a82d3e0539dfb583e03723
+  data.tar.gz: 5e506856f83d7a48f91481cb0ef377df70d4e6f348e922d3412d068c5012fa15
 SHA512:
-  metadata.gz: 01e9ec8f0d4df3d3979903eea9c823bbd8224432c9b6ab246737f499ddb096e908fa2a613d92cddbffa7c53dd5163ceaf22e9c1e50c8f3d664ea5aeae3ae1ff3
-  data.tar.gz: ec02c4c3bb3b1bd28c51b56fb63895d48bac3afcc5c5211308be1f5112d161e175d5710aaa3ebdce24ff31104bc3569a2e49e5af7c3d712903b62444f7abdd12
+  metadata.gz: 7fe7454fe617b0a31004b17ca7e38c681711e90d4bb7889a801092fad8089246e7a1a93d89ff48058a320d60488bd825400b0bfded5380bd8f77d5bde8bded45
+  data.tar.gz: cd79792554f9174f2c416794f5973a3e5090f9494ea54ce22ca96bd21cbb72ef1dda7188b78eb9d5939f3dc44b8fcbd003bac772d41e7b13c24436bc9315f034

data/CHANGELOG.md

@@ -2,23 +2,43 @@
 
 All notable changes to this project will be documented in this file.
 
-## Unreleased
-
-## [0.1.0] - 2026-08-24
-
-- Add `setup`, `build`, and RP2350 BOOTSEL `flash` commands for custom
-  PicoRuby R2P2 firmware on Raspberry Pi Pico 2 and Pico 2 W.
-- Add target configuration for language, language version, board, cache,
-  firmware path, serial port, and timeouts, with command-line precedence.
-- Add `Mrbgems` and `Mrbgems.lock` support for reproducible public and local
-  mrbgems, including automatic regeneration of PicoRuby build output when a
-  custom mrbgem changes.
-- Add PicoModem DFU staging, status, compatible bytecode compilation, and
-  A/B-slot rollback support for Ruby and `.mrb` applications.
-- Add binary-safe file transfer and remote filesystem commands, plus `run`,
-  `exec`, `monitor`, `repl`, and reset with reconnect waiting.
+## 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.
+- Increase the default command timeout from 10 to 20 seconds.
+- Add a bilingual education example for practical PicoModem DFU application updates, startup confirmation, and A/B-slot rollback.
+
+## 0.1.0 - 2026-08-24
+
+- Add `setup`, `build`, and RP2350 BOOTSEL `flash` commands for custom PicoRuby R2P2 firmware on Raspberry Pi Pico 2 and Pico 2 W.
+- Add target configuration for language, language version, board, cache, firmware path, serial port, and timeouts, with command-line precedence.
+- Add `Mrbgems` and `Mrbgems.lock` support for reproducible public and local mrbgems, including automatic regeneration of PicoRuby build output when a custom mrbgem changes.
+- Add PicoModem DFU staging, status, compatible bytecode compilation, and A/B-slot rollback support for Ruby and `.mrb` applications.
+- Add binary-safe file transfer and remote filesystem commands, plus `run`, `exec`, `monitor`, `repl`, and reset with reconnect waiting.
 - Add macOS R2P2 serial-port detection for Raspberry Pi Pico 2 and Pico 2 W.
-- Add bilingual repository, package, configuration, firmware, mrbgem, DFU,
-  and electronic-craft example documentation.
-- Add RBS signatures, automated tests, macOS CI, and release validation with
-  isolated gem installation and CLI smoke testing.
+- Add bilingual repository, package, configuration, firmware, mrbgem, DFU, and electronic-craft example documentation.
+- Add RBS signatures, automated tests, macOS CI, and release validation with isolated gem installation and CLI smoke testing.
+
+### Limitations
+
+- 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

@@ -1,12 +1,10 @@
-# rpremote
+# rpremote CLIリファレンス
 
 [English](README.md)
 
-Raspberry Pi Pico向けのカスタムPicoRuby R2P2ファームウェアを準備、ビルド、
-書き込み、操作するためのコマンドラインツールです。
+Raspberry Pi Pico向けのカスタムPicoRuby R2P2ファームウェアを準備、ビルド、書き込み、操作するためのコマンドラインツールです。
 
-公開mrbgemとローカルmrbgemを再現可能なファームウェアへ組み込み、生成したUF2の
-BOOTSEL書き込み、R2P2経由のバイナリ安全なファイル転送とRuby実行を行えます。
+公開mrbgemとローカルmrbgemを再現可能なファームウェアへ組み込み、生成したUF2のBOOTSEL書き込み、R2P2経由のバイナリ安全なファイル転送とRuby実行を行えます。
 
 ## 必要環境
 
@@ -32,9 +30,15 @@ rpremote flash --mount /Volumes/RP2350
 rpremote run main.rb
 ```
 
-既定では`firmware/picoruby-4.0.3/`にソースを準備し、
-`firmware/picoruby-4.0.3-pico2.uf2`を生成します。対象ボードを明示する必要がある
-場合は、`rpremote ports`でR2P2のCDC 0ポートを確認してください。
+`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を追加する
 
@@ -42,7 +46,6 @@ rpremote run main.rb
 
 ```ruby
 vm :mrubyc
-
 gem github: "ksbmyk/picoruby-ws2812-plus", branch: "main"
 gem path: "../mrbgems/my-device"
 ```
@@ -55,21 +58,17 @@ rpremote mrbgems lock
 rpremote build
 ```
 
-`Mrbgems.lock`はGitHubのcommitとローカルgemの内容hashを固定します。`build`は
-既存lockを再利用し、`rpremote mrbgems update`だけが新しいcommitを解決します。
+`Mrbgems.lock`はGitHubのコミットとローカルgemの内容ハッシュを固定します。`build`は既存のlockを再利用し、`rpremote mrbgems update`だけが新しいコミットを解決します。
 
 ## 対象を選択する
 
 ```sh
 rpremote setup --language picoruby --language-version 3.4.2
 rpremote build --language picoruby --language-version 3.4.2 --board pico2
-rpremote flash --language picoruby --language-version 3.4.2 --board pico2 \
-  --mount /Volumes/RP2350
+rpremote flash --language picoruby --language-version 3.4.2 --board pico2 --mount /Volumes/RP2350
 ```
 
-コマンドラインオプションは`config/setting.json`より優先されます。現在実装されて
-いるのはPicoRubyです。将来のMicroPythonと追加Picoボード対応に備え、
-`language`と`board`はインターフェースに残しています。
+コマンドラインオプションは`config/setting.json`より優先されます。現在実装されているのはPicoRubyです。将来のMicroPythonと追加Picoボード対応に備え、`language`と`board`はインターフェースに残しています。
 
 ## コマンド
 
@@ -78,45 +77,70 @@ rpremote flash --language picoruby --language-version 3.4.2 --board pico2 \
 | `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 flash` | 選択したUF2をBOOTSEL経由で書き込みます。 |
+| `rpremote bootsel --reset-flash-memory` | BOOTSELへ移行し、Pico 2の外部フラッシュメモリ全体を消去します。 |
+| `rpremote config show` | 設定ファイルとコマンドラインオプションを反映した実効設定を表示します。 |
 | `rpremote ports` | R2P2シリアルポートを表示します。 |
-| `rpremote run FILE` | Rubyファイルを転送して実行します。 |
-| `rpremote exec CODE` | 短いRubyコードを実行します。 |
-| `rpremote monitor` / `repl` | 対話型シリアルセッションを開く。 |
-| `rpremote reset` | R2P2を再起動して再接続まで待つ。 |
-| `rpremote fs cp/cat/ls/rm/mkdir` | R2P2ファイルシステムを操作します。 |
+| `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/push/cat/ls/rm/mkdir` | R2P2ファイルシステムを操作します。 |
+
+コマンド一覧は`rpremote --help`で確認できます。コマンド固有の構文、既定値、影響は`rpremote <command> --help`で確認できます。
+
+```sh
+rpremote flash --help
+rpremote dfu app --help
+```
+
+`monitor`と`repl`は`Ctrl-]`で終了します。
+
+`run`と`exec`の例外終了コードには、Ruby例外ステータスに対応したR2P2ファームウェアが必要です。[GitHubリポジトリ](https://github.com/ogom/rpremote)のPicoRubyソースから`rpremote build`で生成したUF2が対応しています。
 
-完全な構文は`rpremote --help`で確認できます。`monitor`と`repl`は`Ctrl-]`で
-終了します。
+## 操作モデル
+
+- `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`を呼び出します。
+- `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`は指定したリモートパスを完全に削除します。
 
 ## ドキュメントとサンプル
 
-[GitHubリポジトリ](https://github.com/ogom/rpremote)に、英語・日本語のガイド、
-設定リファレンス、Mrbgems.lockの解説、カスタムファームウェア手順、電子工作
-サンプルがあります。
+[GitHubリポジトリ](https://github.com/ogom/rpremote)に、英語・日本語のガイド、設定リファレンス、Mrbgems.lockの解説、カスタムファームウェア手順、電子工作サンプルがあります。
 
 ## 関連プロジェクト
 
-- [mbremote](https://github.com/ogom/mbremote)は、BBC micro:bit向けの
-  MicroPython／PicoRubyプロジェクトをビルド、書き込み、操作する、同じコンセプトの
-  ツールです。
+- [mbremote](https://github.com/ogom/mbremote)は、BBC micro:bit向けのMicroPython／PicoRubyプロジェクトをビルド、書き込み、操作する、同じコンセプトのツールです。
 
 ## 開発
 
+依存gemを導入して、テスト、静的解析、RBSを検証します。
+
 ```sh
 bundle install
 bundle exec rake
 bundle exec rbs -I sig validate
 ```
 
-公開前は`bundle exec rake release:check`を実行し、
-[RELEASING.md](RELEASING.md)に従ってください。
+変更したローカル版を試すときは、次を実行します。ネットワークへ接続せずにgemをビルドし、現在のRuby環境へインストールします。
+
+```sh
+bundle exec rake install:local
+rpremote --version
+```
+
+リリースする版は`lib/rpremote/version.rb`と`CHANGELOG.md`を更新します。公開前は`bundle exec rake release:check`を実行し、[RELEASING.md](RELEASING.md)に従ってください。
 
 ## ライセンス
 
-[MIT](LICENSE)です。外部ソフトウェアについては
-[第三者ソフトウェアに関する通知](THIRD_PARTY_NOTICES.md)を参照してください。
+[MIT](LICENSE)です。外部ソフトウェアについては[第三者ソフトウェアに関する通知](THIRD_PARTY_NOTICES.md)を参照してください。

data/README.md

@@ -1,13 +1,10 @@
-# rpremote
+# rpremote CLI reference
 
 [日本語](README.ja.md)
 
-Command-line tools for preparing, building, flashing, and controlling custom
-PicoRuby R2P2 firmware on Raspberry Pi Pico boards.
+Command-line tools for preparing, building, flashing, and controlling custom PicoRuby R2P2 firmware on Raspberry Pi Pico boards.
 
-rpremote embeds public and local mrbgems in reproducible firmware, flashes the
-generated UF2 through BOOTSEL, and provides binary-safe file transfer and Ruby
-execution through R2P2.
+rpremote embeds public and local mrbgems in reproducible firmware, flashes the generated UF2 through BOOTSEL, and provides binary-safe file transfer and Ruby execution through R2P2.
 
 ## Requirements
 
@@ -33,9 +30,15 @@ rpremote flash --mount /Volumes/RP2350
 rpremote run main.rb
 ```
 
-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.
+`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
 
@@ -43,7 +46,6 @@ Create a project-level `Mrbgems` file. Local paths are relative to that file.
 
 ```ruby
 vm :mrubyc
-
 gem github: "ksbmyk/picoruby-ws2812-plus", branch: "main"
 gem path: "../mrbgems/my-device"
 ```
@@ -56,22 +58,17 @@ rpremote mrbgems lock
 rpremote build
 ```
 
-`Mrbgems.lock` pins GitHub commits and hashes local gem contents. Existing
-locks are reused by `build`; `rpremote mrbgems update` deliberately resolves
-new commits.
+`Mrbgems.lock` pins GitHub commits and hashes local gem contents. Existing locks are reused by `build`; `rpremote mrbgems update` deliberately resolves new commits.
 
 ## Select a target
 
 ```sh
 rpremote setup --language picoruby --language-version 3.4.2
 rpremote build --language picoruby --language-version 3.4.2 --board pico2
-rpremote flash --language picoruby --language-version 3.4.2 --board pico2 \
-  --mount /Volumes/RP2350
+rpremote flash --language picoruby --language-version 3.4.2 --board pico2 --mount /Volumes/RP2350
 ```
 
-Command-line options override `config/setting.json`. PicoRuby is implemented
-today; `language` and `board` are retained for planned MicroPython and
-additional Pico board support.
+Command-line options override `config/setting.json`. PicoRuby is implemented today; `language` and `board` are retained for planned MicroPython and additional Pico board support.
 
 ## Commands
 
@@ -80,45 +77,71 @@ additional Pico board support.
 | `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. |
-| `rpremote exec CODE` | Run a short Ruby expression. |
+| `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.
+
+```sh
+rpremote flash --help
+rpremote dfu app --help
+```
+
+`monitor` and `repl` exit with `Ctrl-]`.
+
+Ruby-exception exit statuses for `run` and `exec` require R2P2 firmware with Ruby exception status support.
+UF2 files built with `rpremote build` from the [GitHub repository](https://github.com/ogom/rpremote) include that support.
 
-Run `rpremote --help` for complete syntax. `monitor` and `repl` exit with
-`Ctrl-]`.
+## 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`.
+- `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
 
-The [GitHub repository](https://github.com/ogom/rpremote) contains the full
-English and Japanese guides, configuration reference, Mrbgems.lock reference,
-custom firmware guide, and electronic-craft examples.
+The [GitHub repository](https://github.com/ogom/rpremote) contains the full English and Japanese guides, configuration reference, Mrbgems.lock reference, custom firmware guide, and electronic-craft examples.
 
 ## Related projects
 
-- [mbremote](https://github.com/ogom/mbremote) is a tool with the same concept
-  for building, flashing, and controlling MicroPython and PicoRuby projects on
-  BBC micro:bit boards.
+- [mbremote](https://github.com/ogom/mbremote) is a tool with the same concept for building, flashing, and controlling MicroPython and PicoRuby projects on BBC micro:bit boards.
 
 ## Development
 
+Install dependencies, then run the test and static checks:
+
 ```sh
 bundle install
 bundle exec rake
 bundle exec rbs -I sig validate
 ```
 
-Before publishing, run `bundle exec rake release:check` and follow
-[RELEASING.md](RELEASING.md).
+To try the local gem without publishing it, install it into the current Ruby environment:
+
+```sh
+bundle exec rake install:local
+rpremote --version
+```
+
+Before publishing, run `bundle exec rake release:check` and follow [RELEASING.md](RELEASING.md).
 
 ## License
 
-[MIT](LICENSE). See [Third-Party Notices](THIRD_PARTY_NOTICES.md) for
-externally downloaded software.
+[MIT](LICENSE). See [Third-Party Notices](THIRD_PARTY_NOTICES.md) for externally downloaded software.

data/RELEASING.md

@@ -1,7 +1,6 @@
 # Releasing rpremote
 
-This checklist prepares and publishes one immutable gem version. Run every
-command from `packages/rpremote`.
+This checklist prepares and publishes one immutable gem version. Run every command from `packages/rpremote`.
 
 ## 1. Prepare the version
 
@@ -10,45 +9,46 @@ command from `packages/rpremote`.
 3. Commit all intended files and verify that `git status --short` is empty.
 4. Run the non-publishing release check:
 
-   ```sh
-   bundle exec rake release:check
-   ```
+```sh
+bundle exec rake release:check
+```
 
-The check runs the specs, RuboCop, and RBS validation; builds the gem; checks
-its metadata and packaged documentation; installs it into a temporary isolated
-gem directory; and executes the installed `rpremote --version` command.
+The check runs the specs, RuboCop, and RBS validation; builds the gem; checks its metadata and packaged documentation; installs it into a temporary isolated gem directory; and executes the installed `rpremote --version` command.
 
 ## 2. Prepare publishing services
 
-The repository must have an `origin` remote before releasing. Confirm it with:
+The repository must have an `origin` remote and GitHub CLI authentication before releasing. Confirm them with:
 
 ```sh
 git remote -v
+gh auth status
 ```
 
-For the first RubyGems.org release, confirm that the `rpremote` name is
-available and configure either RubyGems MFA for a manual push or a pending
-trusted publisher for GitHub Actions. Never commit an API key or
-`~/.gem/credentials`.
+Choose one publishing route before the first release:
+
+- For a manual release, sign in to RubyGems.org, confirm that the account owns `rpremote`, and enable MFA:
+
+  ```sh
+  gem signin
+  gem owner rpremote
+  ```
+
+- For a GitHub Actions trusted publisher, confirm the RubyGems.org trusted-publisher entry names this repository and workflow before starting the release.
+
+Never commit an API key or `~/.gem/credentials`.
 
 ## 3. Publish deliberately
 
-`bundle exec rake release` is a publishing command: it creates and pushes the
-version tag and pushes the built gem to RubyGems.org. Run it only after the
-release check passes and the working tree is clean:
+`bundle exec rake release` is a publishing command: it creates and pushes the version tag and pushes the built gem to RubyGems.org. It is not a dry run. Run it only after the release check passes and the working tree is clean:
 
 ```sh
 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:
+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

@@ -1,8 +1,10 @@
 # Third-Party Notices
 
-`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.
+`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
 
@@ -10,20 +12,8 @@ Source: <https://github.com/picoruby/picoruby>
 
 Copyright © 2020 HASUMI Hitoshi
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
-of the Software, and to permit persons to whom the Software is furnished to do
-so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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