prremote

⚠️ This project is in early development. APIs and commands are subject to change.

prremote is a command-line tool for deploying and running Ruby scripts on a Raspberry Pi Pico W over USB serial. It ships a minimal mruby/c runtime firmware and lets you compile and send .rb files from your Mac or Linux machine directly to the device.

Inspired by mpremote for MicroPython.

• Ruby 3.4 or later
• Raspberry Pi Pico W
• mrbc (mruby 4.x) for run, deploy, and eval
  • macOS: brew install mruby
  • Linux: build from source — github.com/mruby/mruby/releases (sudo apt install mruby installs mruby 3.x which is not compatible)
  • If mrbc is not on your PATH, set the MRBC environment variable: MRBC=/path/to/mrbc prremote run app.rb

gem install prremote

# 1. Flash the prremote runtime to your Pico W (one-time setup)
prremote install

# 2. Write your app
echo 'puts "Hello from Pico W!"' > app.rb

# 3. Run it
prremote run app.rb

Flash the prremote runtime firmware to a Pico W or Pico.

prremote install                          # Pico W (default)
prremote install --board pico             # Pico (no wireless)
prremote install --version 0.1.1          # specify a runtime version
prremote install --board pico --version 0.1.1

The firmware is downloaded from GitHub Releases on first use and cached in ~/.prremote/runtime/. Subsequent installs use the cache.

Put the device into BOOTSEL mode (hold BOOTSEL, connect USB, release) when prompted.

Compile one or more local .rb files to mruby bytecode and run them on the device immediately (one-shot).

prremote run app.rb
prremote run blink.rb --port /dev/tty.usbmodem101

Multiple files are compiled in order into a single .mrb. Classes and methods defined in earlier files are available to later ones — this is the recommended alternative to require, which is not available in mruby/c.

prremote run lib.rb main.rb

The device responds with RUNNING, streams any output, then DONE.

You can find some examples in test/samples.

Compile one or more local .rb files and save them to the device's flash. The script runs automatically on every boot.

prremote deploy app.rb
prremote deploy lib.rb main.rb

The device responds with DEPLOYED when the write is complete.

Erase the deployed script from flash. After this, the device boots into idle mode.

prremote undeploy

Evaluate a Ruby one-liner on the device.

prremote eval "puts 1 + 1"
prremote eval "CYW43.init; CYW43::GPIO.new(CYW43::GPIO::LED_PIN).write 1"

Send Ctrl+C to interrupt a running program.

prremote reset

Watch one or more local files for changes and automatically re-run them on the device on every save.

prremote watch app.rb
prremote watch lib.rb main.rb

Useful during development — save any watched file and the device immediately runs the updated code.

List USB serial devices that may be prremote-compatible.

prremote list

Show the gem version, mrbc version, and the connected device's runtime version.

prremote version
# prremote: 0.1.5
# runtime:  0.1.5 (/dev/tty.usbmodem101)
# mrbc: mruby 4.0.0 (2026-04-20) (/opt/homebrew/bin/mrbc)

# First-time setup
prremote install

# Manual cycle
prremote run app.rb       # compile + run (one-shot)
prremote reset            # interrupt a running program

# Automated cycle (recommended)
prremote watch app.rb     # auto-run on every file save

# Persistent deployment (auto-runs on boot)
prremote deploy app.rb
prremote undeploy         # remove from flash

prremote flashes a minimal C firmware (built on mruby/c) onto the Pico W. The firmware:

1. Waits for a USB serial connection and sends READY prremote-runtime/VERSION
2. Receives a command from the host:
   • Raw .mrb bytecode → execute immediately and stream output (run / eval / watch)
   • DPLY + .mrb bytecode → save to flash and confirm with DEPLOYED (deploy)
3. Waits for the next command

Scripts saved via deploy are stored in flash and run automatically on every boot. GPIO and WiFi (CYW43) C bindings are available in Ruby code running on the device.

MIT License

• mruby/c — Lightweight mruby implementation used in the runtime
• picotool — Official Raspberry Pi tool for inspecting and managing Pico devices; useful for checking what's on flash or force-rebooting outside of prremote
• mpremote — MicroPython equivalent (inspiration)