Module: Rpremote::Help

Defined in:
lib/rpremote/help.rb

Constant Summary collapse

COMMAND_USAGE = 
{
  setup: "rpremote setup [--language LANGUAGE] [--language-version VERSION] [--force] [--cache DIR]",
  build: "rpremote build [--language LANGUAGE] [--language-version VERSION] [--board BOARD] " \
         "[--firmware FILE] [--cache DIR] [--mrbgems FILE|--no-mrbgems]",
  build_clean: "rpremote build clean",
  bootsel: "rpremote bootsel [--reset-flash-memory] [--mount DIR] [--port PORT] [--baud RATE] [--timeout SEC]",
  deploy: "rpremote deploy PATH [--language LANGUAGE] [--language-version VERSION] [--board BOARD] " \
          "[--firmware FILE] [--cache DIR] [--mrbgems FILE|--no-mrbgems] [--mount DIR] " \
          "[--port PORT] [--baud RATE] [--timeout SEC]",
  dfu_app: "rpremote dfu app FILE [--type ruby|rite] [--port PORT] [--baud RATE] [--timeout SEC]",
  dfu_compile: "rpremote dfu compile FILE [--output FILE] [--language LANGUAGE] [--language-version VERSION] [--cache DIR]",
  dfu_status: "rpremote dfu status [--port PORT] [--baud RATE] [--timeout SEC]",
  dfu_remove: "rpremote dfu remove [--port PORT] [--baud RATE] [--timeout SEC]",
  mrbgems: "rpremote mrbgems SUBCOMMAND [--file FILE] [--lockfile FILE]",
  flash: "rpremote flash [--firmware FILE] [--language LANGUAGE] [--language-version VERSION] " \
         "[--board BOARD] [--cache DIR] [--mount DIR] [--port PORT] [--timeout SEC]",
  config_show: "rpremote config show [--language LANGUAGE] [--language-version VERSION] [--board BOARD] " \
               "[--cache DIR] [--firmware FILE] [--mrbgems FILE|--no-mrbgems] [--mount DIR] " \
               "[--port PORT] [--baud RATE] [--timeout SEC]",
  ports: "rpremote ports",
  run: "rpremote run FILE [--port PORT] [--baud RATE] [--timeout SEC] [--reset-on-timeout] [--language LANGUAGE]",
  monitor: "rpremote monitor [--port PORT] [--baud RATE] [--timeout SEC]",
  repl: "rpremote repl [--port PORT] [--baud RATE] [--timeout SEC]",
  exec: "rpremote exec CODE [--port PORT] [--baud RATE] [--timeout SEC] [--language LANGUAGE]",
  reset: "rpremote reset [--port PORT] [--baud RATE] [--timeout SEC]",
  fs_cp: "rpremote fs cp SOURCE DESTINATION [--recursive] [--port PORT] [--baud RATE] [--timeout SEC]",
  fs_push: "rpremote fs push LOCAL_DIR :/REMOTE_DIR [--port PORT] [--baud RATE] [--timeout SEC]",
  fs_cat: "rpremote fs cat :/REMOTE/PATH [--port PORT] [--baud RATE] [--timeout SEC]",
  fs_ls: "rpremote fs ls :/REMOTE/PATH [--port PORT] [--baud RATE] [--timeout SEC]",
  fs_rm: "rpremote fs rm :/REMOTE/PATH [--port PORT] [--baud RATE] [--timeout SEC]",
  fs_mkdir: "rpremote fs mkdir :/REMOTE/PATH [--port PORT] [--baud RATE] [--timeout SEC]"
}.freeze
TEXT = 
<<~HELP.freeze
  rpremote - R2P2 remote control for Raspberry Pi Pico 2

  Usage:
    #{COMMAND_USAGE.fetch(:setup)}
    #{COMMAND_USAGE.fetch(:build)}
    #{COMMAND_USAGE.fetch(:build_clean)}
    #{COMMAND_USAGE.fetch(:bootsel)}
    #{COMMAND_USAGE.fetch(:deploy)}
    #{COMMAND_USAGE.fetch(:dfu_app)}
    #{COMMAND_USAGE.fetch(:dfu_compile)}
    #{COMMAND_USAGE.fetch(:dfu_status)}
    #{COMMAND_USAGE.fetch(:dfu_remove)}
    #{COMMAND_USAGE.fetch(:mrbgems).sub("SUBCOMMAND", "check|list|lock|update")}
    #{COMMAND_USAGE.fetch(:flash)}
    #{COMMAND_USAGE.fetch(:config_show)}
    #{COMMAND_USAGE.fetch(:ports)}
    #{COMMAND_USAGE.fetch(:run)}
    #{COMMAND_USAGE.fetch(:monitor)}
    #{COMMAND_USAGE.fetch(:repl)}
    #{COMMAND_USAGE.fetch(:exec)}
    #{COMMAND_USAGE.fetch(:reset)}
    #{COMMAND_USAGE.fetch(:fs_cp)}
    #{COMMAND_USAGE.fetch(:fs_push)}
    #{COMMAND_USAGE.fetch(:fs_cat)}
    #{COMMAND_USAGE.fetch(:fs_ls)}
    #{COMMAND_USAGE.fetch(:fs_rm)}
    #{COMMAND_USAGE.fetch(:fs_mkdir)}

  `rpremote build clean` removes only the project's generated `build/` directory.

  Configuration:
    config/setting.json  default project options

  Options:
    --force           download the PicoRuby source again during setup
    --language-version VERSION
                      use R2P2/PicoRuby 4.0.3 or 3.4.2 (default: 4.0.3)
    --cache DIR       use another project cache directory
    --mrbgems FILE    use an explicit Mrbgems definition during build or deploy
    --no-mrbgems      build or deploy without the automatically detected Mrbgems
    --board BOARD
                      select pico2 or pico2_w (default: pico2)
    --firmware FILE   build to, or deploy or flash from, this UF2 path
    --language LANGUAGE
                      select the remote language (default: picoruby)
    --config FILE     use another configuration file
    --mount DIR       use an explicit RP2350 BOOTSEL drive
    --port PORT       use an explicit R2P2 CDC 0 device
    --baud RATE       serial baud rate (default: 115200)
    --timeout SEC     timeout in seconds (default: 20)
    -h, --help        show this help
    -V, --version     show the version
HELP

Class Method Summary collapse

Class Method Details

.bootsel_text ⇒ Object 



163
164
165
166
167
168
169
170
171
172
 
# File 'lib/rpremote/help.rb', line 163

def self.bootsel_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:bootsel)}

    Asks the running R2P2 firmware to restart as an RP2350 BOOTSEL USB volume, then waits for that volume to appear.
    By default it does not write firmware. This requires firmware built by a current rpremote; use physical BOOTSEL once to install it first.
    --reset-flash-memory copies the official Raspberry Pi nuke_universal.uf2 in BOOTSEL mode and erases all external flash memory.
    After resetting flash memory, wait for BOOTSEL to reappear and run `rpremote flash` to install R2P2 again.
  HELP
end

.build_clean_text ⇒ Object 



143
144
145
146
147
148
149
 
# File 'lib/rpremote/help.rb', line 143

def self.build_clean_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:build_clean)}

    Removes only the project's generated build/ directory. It does not remove firmware/, Mrbgems, or Mrbgems.lock.
  HELP
end

.build_text ⇒ Object 



133
134
135
136
137
138
139
140
141
 
# File 'lib/rpremote/help.rb', line 133

def self.build_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:build)}

    Builds a custom UF2 for the selected target. It writes generated files under build/ and the selected firmware path.
    Options: --language LANGUAGE, --language-version VERSION, --board BOARD (pico2), --cache DIR (firmware),
    --firmware FILE, --mrbgems FILE, --no-mrbgems. A project Mrbgems file is used automatically by default.
  HELP
end

.command_text(command, args) ⇒ Object 



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/rpremote/help.rb', line 99

def self.command_text(command, args)
  command = args.shift if command == "help"
  return TEXT if command.nil? || %w[help --help -h].include?(command)

  case command
  when "setup" then setup_text
  when "build" then args.first == "clean" ? build_clean_text : build_text
  when "bootsel" then bootsel_text
  when "deploy" then deploy_text
  when "dfu" then dfu_text(args.first)
  when "mrbgems" then mrbgems_text(args.first)
  when "flash" then flash_text
  when "config" then config_text(args.first)
  when "ports" then ports_text
  when "run" then run_text
  when "exec" then exec_text
  when "monitor" then monitor_text
  when "repl" then repl_text
  when "reset" then reset_text
  when "fs" then fs_text(args.first)
  else TEXT
  end
end

.config_text(subcommand) ⇒ Object 



247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/rpremote/help.rb', line 247

def self.config_text(subcommand)
  unless subcommand == "show"
    return "Usage: #{COMMAND_USAGE.fetch(:config_show)}\n\nUse `rpremote config show --help` for the supported overrides.\n"
  end

  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:config_show)}

    Prints the configuration file, defaults, and command-line overrides after resolution. It does not connect to a board or change state.
  HELP
end

.deploy_text ⇒ Object 



151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/rpremote/help.rb', line 151

def self.deploy_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:deploy)}

    Builds the selected custom UF2, enters BOOTSEL when needed, flashes the firmware, and waits for the R2P2 Shell to become ready.
    If PATH/lib/NAME exists, it copies it to :/lib/NAME, where NAME is the final component of PATH. It then runs PATH/main.rb and preserves its Shell job, so hardware output remains active until the next command.
    The stages run in order and stop at the first failure. Flashing replaces persistent board firmware.
    deploy requires PicoRuby 4.x firmware (currently 4.0.3).
    Options combine build, BOOTSEL, flash, library-copy, and run settings. The first install of firmware with automatic BOOTSEL still requires holding BOOTSEL.
  HELP
end

.dfu_app_text ⇒ Object 



190
191
192
193
194
195
196
197
198
 
# File 'lib/rpremote/help.rb', line 190

def self.dfu_app_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:dfu_app)}

    Transfers a Ruby source or matching RITE bytecode application to the inactive DFU slot. The next R2P2 restart tries it.
    Options default to the configured or automatically selected CDC 0 port, 115200 baud, and 20 seconds.
    The transfer changes the staged boot application; use `rpremote reset` to restart and require DFU.confirm after a successful boot.
  HELP
end

.dfu_compile_text ⇒ Object 



200
201
202
203
204
205
206
207
 
# File 'lib/rpremote/help.rb', line 200

def self.dfu_compile_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:dfu_compile)}

    Compiles Ruby source to bytecode that matches the selected PicoRuby version. The output defaults beside FILE.
    It requires prepared PicoRuby source and does not connect to a board.
  HELP
end

.dfu_remove_text ⇒ Object 



218
219
220
221
222
223
224
225
226
 
# File 'lib/rpremote/help.rb', line 218

def self.dfu_remove_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:dfu_remove)}

    Permanently removes the Ruby source and bytecode applications from both DFU A/B slots and resets their metadata.
    Run `rpremote reset` afterward to stop the application already running in RAM. It does not remove /home/app.rb,
    /home/app.mrb, other files, embedded mrbgems, or R2P2 firmware.
  HELP
end

.dfu_status_text ⇒ Object 



209
210
211
212
213
214
215
216
 
# File 'lib/rpremote/help.rb', line 209

def self.dfu_status_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:dfu_status)}

    Prints the active and candidate DFU A/B slots. Defaults are the configured or automatically selected CDC 0 port,
    115200 baud, and 20 seconds. This command reads board state without changing it.
  HELP
end

.dfu_text(subcommand) ⇒ Object 



174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/rpremote/help.rb', line 174

def self.dfu_text(subcommand)
  return dfu_app_text if subcommand == "app"
  return dfu_compile_text if subcommand == "compile"
  return dfu_status_text if subcommand == "status"
  return dfu_remove_text if subcommand == "remove"

  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:dfu_app)}
           #{COMMAND_USAGE.fetch(:dfu_compile)}
           #{COMMAND_USAGE.fetch(:dfu_status)}
           #{COMMAND_USAGE.fetch(:dfu_remove)}

    Stages and inspects PicoModem DFU applications. Run `rpremote dfu SUBCOMMAND --help` for details.
  HELP
end

.exec_text ⇒ Object 



274
275
276
277
278
279
280
281
282
 
# File 'lib/rpremote/help.rb', line 274

def self.exec_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:exec)}

    Runs short Ruby CODE through a temporary remote file, then removes it. Defaults are the automatic CDC 0 port,
    115200 baud, a 20-second idle timeout, and picoruby. Output from the running program resets the idle timeout.
    It exits nonzero when compatible R2P2 firmware reports a Ruby exception.
  HELP
end

.flash_text ⇒ Object 



238
239
240
241
242
243
244
245
 
# File 'lib/rpremote/help.rb', line 238

def self.flash_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:flash)}

    Copies the selected UF2 to an RP2350 BOOTSEL volume and waits for R2P2 to reconnect. It replaces persistent board firmware.
    Defaults select pico2, firmware/picoruby-4.0.3-pico2.uf2, an automatic BOOTSEL mount and CDC 0 port, and 20 seconds.
  HELP
end

.fs_subcommand_text(subcommand) ⇒ Object 



323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
 
# File 'lib/rpremote/help.rb', line 323

def self.fs_subcommand_text(subcommand)
  usage = COMMAND_USAGE.fetch(:"fs_#{subcommand}")
  effect = case subcommand
           when "rm" then "Deletes the remote path permanently."
           when "mkdir" then "Creates a remote directory."
           when "cp" then "Transfers one file, or recursively uploads a local directory with --recursive."
           when "push" then "Creates missing remote directories and recursively uploads a local directory."
           else "Reads remote files."
           end
  <<~HELP
    Usage: #{usage}

    #{effect} Defaults are the automatic CDC 0 port, 115200 baud, and 20 seconds.
  HELP
end

.fs_text(subcommand) ⇒ Object 



308
309
310
311
312
313
314
315
316
317
318
319
320
321
 
# File 'lib/rpremote/help.rb', line 308

def self.fs_text(subcommand)
  return fs_subcommand_text(subcommand) if %w[cp push cat ls rm mkdir].include?(subcommand)

  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:fs_cp)}
           #{COMMAND_USAGE.fetch(:fs_push)}
           #{COMMAND_USAGE.fetch(:fs_cat)}
           #{COMMAND_USAGE.fetch(:fs_ls)}
           #{COMMAND_USAGE.fetch(:fs_rm)}
           #{COMMAND_USAGE.fetch(:fs_mkdir)}

    Uses :/REMOTE/PATH for R2P2 paths. Run `rpremote fs SUBCOMMAND --help` for details.
  HELP
end

.monitor_text ⇒ Object 



284
285
286
287
288
289
290
 
# File 'lib/rpremote/help.rb', line 284

def self.monitor_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:monitor)}

    Opens a serial monitor for the selected CDC 0 port. Defaults are 115200 baud and 20 seconds; exit with Ctrl-].
  HELP
end

.mrbgems_text(subcommand) ⇒ Object 



228
229
230
231
232
233
234
235
236
 
# File 'lib/rpremote/help.rb', line 228

def self.mrbgems_text(subcommand)
  action = subcommand || "check|list|lock|update"
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:mrbgems).sub("SUBCOMMAND", action)}

    Checks or lists build dependencies, writes a reproducible lock file, or updates locked GitHub commits.
    `check` and `list` are read-only. `lock` writes Mrbgems.lock; `update` resolves new commits and rewrites it.
  HELP
end

.ports_text ⇒ Object 



259
260
261
 
# File 'lib/rpremote/help.rb', line 259

def self.ports_text
  "Usage: #{COMMAND_USAGE.fetch(:ports)}\n\nPrints each detected R2P2 CDC 0 serial path, one per line. It does not connect to a board.\n"
end

.repl_text ⇒ Object 



292
293
294
295
296
297
298
 
# File 'lib/rpremote/help.rb', line 292

def self.repl_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:repl)}

    Opens PicoIRB on the selected CDC 0 port. Defaults are 115200 baud and 20 seconds; exit with Ctrl-].
  HELP
end

.requested?(command, args) ⇒ Boolean

Returns:

  • (Boolean) 


95
96
97
 
# File 'lib/rpremote/help.rb', line 95

def self.requested?(command, args)
  %w[help --help -h].include?(command) || args.include?("--help") || args.include?("-h")
end

.reset_text ⇒ Object 



300
301
302
303
304
305
306
 
# File 'lib/rpremote/help.rb', line 300

def self.reset_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:reset)}

    Reboots R2P2 and waits for reconnection. Defaults are the automatic CDC 0 port, 115200 baud, and 20 seconds.
  HELP
end

.run_text ⇒ Object 



263
264
265
266
267
268
269
270
271
272
 
# File 'lib/rpremote/help.rb', line 263

def self.run_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:run)}

    Uploads FILE to R2P2, or main.rb when FILE is a directory, relays output, then removes the temporary remote file. Defaults are the automatic CDC 0 port,
    115200 baud, a 20-second idle timeout, and picoruby. Output from the running program resets the idle timeout.
    It exits nonzero when compatible R2P2 firmware reports a Ruby exception.
    --reset-on-timeout resets R2P2 after the run times out and the serial connection has closed.
  HELP
end

.setup_text ⇒ Object 



123
124
125
126
127
128
129
130
131
 
# File 'lib/rpremote/help.rb', line 123

def self.setup_text
  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:setup)}

    Creates config/setting.json when it does not exist, then downloads and prepares PicoRuby source and the official Raspberry Pi nuke_universal.uf2 firmware.
    Options: --language LANGUAGE (picoruby), --language-version VERSION (4.0.3), --cache DIR (firmware), --force.
    This changes the project configuration and source cache but does not connect to a board.
  HELP
end