rpremote 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ccf42c1aa0428ee4996626537122a820d94aac064a8bd40e15defb4b31c76901
+  data.tar.gz: f7d7ac9163993a8c8075861bb750ebda0ba9031f9c4393be77be93428eae5d2d
+SHA512:
+  metadata.gz: 01e9ec8f0d4df3d3979903eea9c823bbd8224432c9b6ab246737f499ddb096e908fa2a613d92cddbffa7c53dd5163ceaf22e9c1e50c8f3d664ea5aeae3ae1ff3
+  data.tar.gz: ec02c4c3bb3b1bd28c51b56fb63895d48bac3afcc5c5211308be1f5112d161e175d5710aaa3ebdce24ff31104bc3569a2e49e5af7c3d712903b62444f7abdd12

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+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.
+- 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.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ogom
+
+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/README.ja.md

@@ -0,0 +1,122 @@
+# rpremote
+
+[English](README.md)
+
+Raspberry Pi Pico向けのカスタムPicoRuby R2P2ファームウェアを準備、ビルド、
+書き込み、操作するためのコマンドラインツールです。
+
+公開mrbgemとローカルmrbgemを再現可能なファームウェアへ組み込み、生成したUF2の
+BOOTSEL書き込み、R2P2経由のバイナリ安全なファイル転送とRuby実行を行えます。
+
+## 必要環境
+
+- macOSとRuby 4.0以降
+- ファームウェアビルド用のGit、GNU Make、CMake、Arm GNU Toolchain
+- 選択したR2P2ビルド設定に対応するRaspberry Pi Picoボード
+- R2P2ビルド設定を含むPicoRuby
+
+## インストール
+
+```sh
+gem install rpremote
+```
+
+## クイックスタート
+
+プロジェクトのディレクトリで実行します。
+
+```sh
+rpremote setup
+rpremote build
+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ポートを確認してください。
+
+## mrbgemを追加する
+
+プロジェクト直下に`Mrbgems`を作成します。ローカルパスはこのファイルを基準にします。
+
+```ruby
+vm :mrubyc
+
+gem github: "ksbmyk/picoruby-ws2812-plus", branch: "main"
+gem path: "../mrbgems/my-device"
+```
+
+依存関係を検査、固定してビルドします。
+
+```sh
+rpremote mrbgems check
+rpremote mrbgems lock
+rpremote build
+```
+
+`Mrbgems.lock`はGitHubのcommitとローカルgemの内容hashを固定します。`build`は
+既存lockを再利用し、`rpremote mrbgems update`だけが新しいcommitを解決します。
+
+## 対象を選択する
+
+```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
+```
+
+コマンドラインオプションは`config/setting.json`より優先されます。現在実装されて
+いるのはPicoRubyです。将来のMicroPythonと追加Picoボード対応に備え、
+`language`と`board`はインターフェースに残しています。
+
+## コマンド
+
+| コマンド | 説明 |
+| --- | --- |
+| `rpremote setup` | 設定を作成し、言語ソースを準備します。 |
+| `rpremote build` | mrbgemを含むカスタムUF2をビルドします。 |
+| `rpremote build clean` | 中間ビルドファイルを削除します。 |
+| `rpremote dfu app FILE` | PicoModem DFUでRubyまたは版を照合したバイトコードのアプリを更新します。 |
+| `rpremote dfu compile FILE` | DFU用にPicoRuby版と一致する`.mrb`を生成します。 |
+| `rpremote dfu status` | DFUのアクティブおよび起動候補スロットを表示します。 |
+| `rpremote mrbgems …` | mrbgemを検査、表示、固定、更新します。 |
+| `rpremote flash` | 選択したUF2をBOOTSEL経由で書き込む。 |
+| `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 --help`で確認できます。`monitor`と`repl`は`Ctrl-]`で
+終了します。
+
+## ドキュメントとサンプル
+
+[GitHubリポジトリ](https://github.com/ogom/rpremote)に、英語・日本語のガイド、
+設定リファレンス、Mrbgems.lockの解説、カスタムファームウェア手順、電子工作
+サンプルがあります。
+
+## 関連プロジェクト
+
+- [mbremote](https://github.com/ogom/mbremote)は、BBC micro:bit向けの
+  MicroPython／PicoRubyプロジェクトをビルド、書き込み、操作する、同じコンセプトの
+  ツールです。
+
+## 開発
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rbs -I sig validate
+```
+
+公開前は`bundle exec rake release:check`を実行し、
+[RELEASING.md](RELEASING.md)に従ってください。
+
+## ライセンス
+
+[MIT](LICENSE)です。外部ソフトウェアについては
+[第三者ソフトウェアに関する通知](THIRD_PARTY_NOTICES.md)を参照してください。

data/README.md

@@ -0,0 +1,124 @@
+# rpremote
+
+[日本語](README.ja.md)
+
+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.
+
+## Requirements
+
+- macOS and Ruby 4.0 or later
+- Git, GNU Make, CMake, and the Arm GNU Toolchain for firmware builds
+- A Raspberry Pi Pico board supported by the selected R2P2 build configuration
+- A PicoRuby version providing the R2P2 build configuration
+
+## Installation
+
+```sh
+gem install rpremote
+```
+
+## Quick start
+
+Run these commands in a project directory:
+
+```sh
+rpremote setup
+rpremote build
+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.
+
+## Add mrbgems
+
+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"
+```
+
+Then validate, lock, and build the dependencies:
+
+```sh
+rpremote mrbgems check
+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.
+
+## 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
+```
+
+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
+
+| Command | Description |
+| --- | --- |
+| `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 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 mrbgems …` | Check, list, lock, or update mrbgems. |
+| `rpremote flash` | Flash the selected UF2 through BOOTSEL. |
+| `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 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. |
+
+Run `rpremote --help` for complete syntax. `monitor` and `repl` exit with
+`Ctrl-]`.
+
+## 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.
+
+## 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.
+
+## Development
+
+```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).
+
+## License
+
+[MIT](LICENSE). See [Third-Party Notices](THIRD_PARTY_NOTICES.md) for
+externally downloaded software.

data/RELEASING.md

@@ -0,0 +1,54 @@
+# Releasing rpremote
+
+This checklist prepares and publishes one immutable gem version. Run every
+command from `packages/rpremote`.
+
+## 1. Prepare the version
+
+1. Update `Rpremote::VERSION` in `lib/rpremote/version.rb`.
+2. Add the same version and release date to `CHANGELOG.md`.
+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
+   ```
+
+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:
+
+```sh
+git remote -v
+```
+
+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`.
+
+## 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:
+
+```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:
+
+```sh
+gh release create v0.1.0 rpremote-0.1.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`.

data/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,29 @@
+# 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.
+
+## PicoRuby and R2P2
+
+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.

data/exe/rpremote

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rpremote"
+require "rpremote/cli"
+
+exit(Rpremote::CLI.start)

data/lib/rpremote/build_command.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Rpremote
+  class BuildCommand
+    def self.run(args, defaults:, output: $stdout, error: $stderr, builder: Builder.new)
+      if args.first == "clean"
+        args.shift
+        raise ArgumentError, "build clean does not accept arguments" unless args.empty?
+
+        builder.clean(output: output)
+        return
+      end
+
+      options = {
+        language: Target::DEFAULT_LANGUAGE,
+        language_version: Target::DEFAULT_LANGUAGE_VERSION,
+        board: Target::DEFAULT_BOARD,
+        cache_dir: defaults.fetch(:cache, Target::DEFAULT_CACHE_DIR),
+        firmware: defaults[:firmware],
+        mrbgems: nil
+      }.merge(defaults.except(:cache))
+      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("--firmware FILE") { |value| options[:firmware] = value }
+        parser.on("--cache DIR") { |value| options[:cache_dir] = value }
+        parser.on("--mrbgems FILE") { |value| options[:mrbgems] = value }
+        parser.on("--no-mrbgems") { options[:mrbgems] = false }
+      end.parse!(args)
+      raise ArgumentError, "build does not accept arguments" unless args.empty?
+
+      builder.build(**options, output: output, error: error)
+    end
+  end
+end

data/lib/rpremote/builder.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "fileutils"
+require "rubygems/version"
+require_relative "mrbgems"
+
+module Rpremote
+  class Builder
+    class Error < Rpremote::Error; end
+
+    def initialize(root: Dir.pwd, runner: nil, mrbgems_class: Mrbgems)
+      @root = File.expand_path(root)
+      @runner = runner || method(:run_command)
+      @mrbgems_class = mrbgems_class
+    end
+
+    def build(output: $stdout, error: $stderr, **options)
+      target = Target.new(**options.slice(:language, :language_version, :board, :cache_dir, :firmware))
+      script = File.expand_path("../../tasks/firmware_build.rb", __dir__)
+      raise Error, "rpremote installation has no firmware build script: #{script}" unless File.file?(script)
+
+      Language.validate!(target.language)
+
+      source_dir = source_for(target)
+      environment = {
+        "RPREMOTE_LANGUAGE" => target.language,
+        "RPREMOTE_LANGUAGE_VERSION" => target.language_version,
+        "RPREMOTE_BOARD" => target.board,
+        "RPREMOTE_ROOT" => root,
+        "PICORUBY_DIR" => source_dir
+      }
+      build_options = options.merge(
+        language: target.language,
+        language_version: target.language_version,
+        board: target.board
+      )
+      add_mrbgems_environment!(environment, build_options, source_dir, output)
+      environment["RPREMOTE_FIRMWARE"] = target.firmware_path(root: root)
+      success = runner.call(
+        environment,
+        RbConfig.ruby,
+        script,
+        chdir: root,
+        out: output,
+        err: error
+      )
+      raise Error, "custom firmware build failed" unless success
+    end
+
+    def clean(output: $stdout)
+      directory = File.join(root, "build")
+      unless File.directory?(directory)
+        output.puts("no build files: #{directory}")
+        return
+      end
+
+      FileUtils.rm_rf(directory)
+      output.puts("removed build files: #{directory}")
+    end
+
+    private
+
+    attr_reader :root, :runner, :mrbgems_class
+
+    def add_mrbgems_environment!(environment, options, source_dir, output)
+      definition = mrbgems_definition(options[:mrbgems])
+      return unless definition
+
+      manager = mrbgems_class.new(path: definition, cwd: root)
+      config_language = mrbgems_config_language(
+        manager.vm, options.fetch(:language), options.fetch(:language_version)
+      )
+      config_name = "r2p2-#{config_language}-#{options.fetch(:board)}"
+      base_config = File.join(source_dir, "build_config", "#{config_name}.rb")
+      raise Error, "PicoRuby build config not found: #{base_config}" unless File.file?(base_config)
+
+      overlay = manager.generate_overlay(
+        base_config: base_config,
+        target: config_name,
+        directory: File.join(root, "build", "mrbgems")
+      )
+      environment["RPREMOTE_CONFIG_NAME"] = config_name
+      environment["RPREMOTE_MRUBY_CONFIG"] = overlay.path
+      environment["RPREMOTE_MRBGEMS_FINGERPRINT"] = overlay.fingerprint
+      output.puts("using Mrbgems: #{manager.path}")
+      output.puts("using Mrbgems.lock: #{manager.lock_path}")
+    end
+
+    def mrbgems_config_language(vm_name, language, version)
+      return language unless vm_name
+
+      modern = Gem::Version.new(version) >= Gem::Version.new("4.0.0")
+      return modern ? "femtoruby" : "picoruby" if vm_name == :mrubyc
+
+      modern ? "picoruby" : "microruby"
+    end
+
+    def mrbgems_definition(option)
+      return if option == false
+
+      candidate = File.expand_path(option || Mrbgems::DEFAULT_PATH, root)
+      return candidate if File.file?(candidate)
+      raise Error, "mrbgems definition does not exist: #{candidate}" if option
+
+      nil
+    end
+
+    def source_for(target)
+      source = target.source_dir(root: root)
+      return source if File.directory?(source)
+
+      raise Error,
+            "#{target.language} #{target.language_version} source not found: #{source}\n" \
+            "Run `rpremote setup --language #{target.language} " \
+            "--language-version #{target.language_version} --cache #{target.cache_dir}` first."
+    end
+
+    def run_command(...)
+      system(...)
+    end
+  end
+end

data/lib/rpremote/checksum.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Rpremote
+  module Checksum
+    module_function
+
+    def crc16(data, initial = 0xFFFF)
+      data.each_byte.reduce(initial) do |crc, byte|
+        crc ^= byte << 8
+        8.times do
+          crc = if crc.nobits?(0x8000)
+                  crc << 1
+                else
+                  (crc << 1) ^ 0x1021
+                end
+        end
+        crc & 0xFFFF
+      end
+    end
+
+    def crc32(data, initial = 0)
+      Zlib.crc32(data, initial)
+    end
+  end
+end