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.

Requirements

  • Ruby 3.x or later
  • Raspberry Pi Pico W
  • mrbc in your PATH (for run, deploy, and eval) — install via brew install mruby on macOS

Installation

gem install prremote

Quick Start

# 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

Commands

install

Flash the prremote runtime firmware to a Pico W.

prremote install
prremote install --version 0.1.1   # specify a runtime version

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

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

run FILE

Compile a local .rb file to mruby bytecode and run it on the device immediately (one-shot).

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

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

deploy FILE

Compile a local .rb file and save it to the device's flash. The script runs automatically on every boot.

prremote deploy app.rb

The device responds with DEPLOYED when the write is complete.

undeploy

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

prremote undeploy

eval EXPR

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"

reset

Send Ctrl+C to interrupt a running program.

prremote reset

watch FILE

Watch a local file for changes and automatically re-run it on the device on every save.

prremote watch app.rb

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

list

List USB serial devices that may be prremote-compatible.

prremote list

version

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

prremote version
# prremote: 0.1.0
# mrbc:     3.3.0 (/usr/local/bin/mrbc)
# runtime:  0.1.2

Global Options

Option Description
--port, -p PORT Serial port (default: auto-detect)
--baud, -b N Baud rate (default: 115200)

Typical Development Workflow

# 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

How It Works

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.

License

MIT License

  • mruby/c — Lightweight mruby implementation used in the runtime
  • mpremote — MicroPython equivalent (inspiration)