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",
  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]",
  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] [--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 [--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(:dfu_app)}
    #{COMMAND_USAGE.fetch(:dfu_compile)}
    #{COMMAND_USAGE.fetch(:dfu_status)}
    #{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_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
    --no-mrbgems      build without the automatically detected Mrbgems
    --board BOARD
                      select pico2 or pico2_w (default: pico2)
    --firmware FILE   build to, 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

.build_clean_text ⇒ Object 



131
132
133
134
135
136
137
 
# File 'lib/rpremote/help.rb', line 131

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 



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

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 



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/rpremote/help.rb', line 89

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 "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 



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

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

.dfu_app_text ⇒ Object 



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

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 



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

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_status_text ⇒ Object 



172
173
174
175
176
177
178
179
 
# File 'lib/rpremote/help.rb', line 172

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 



139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/rpremote/help.rb', line 139

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"

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

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

.exec_text ⇒ Object 



225
226
227
228
229
230
231
232
 
# File 'lib/rpremote/help.rb', line 225

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, 20 seconds, and picoruby. It exits nonzero when compatible R2P2 firmware reports a Ruby exception.
  HELP
end

.flash_text ⇒ Object 



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

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 



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

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."
           else "Reads or transfers 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 



258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/rpremote/help.rb', line 258

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

  <<~HELP
    Usage: #{COMMAND_USAGE.fetch(:fs_cp)}
           #{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 



234
235
236
237
238
239
240
 
# File 'lib/rpremote/help.rb', line 234

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 



181
182
183
184
185
186
187
188
189
 
# File 'lib/rpremote/help.rb', line 181

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 



212
213
214
 
# File 'lib/rpremote/help.rb', line 212

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 



242
243
244
245
246
247
248
 
# File 'lib/rpremote/help.rb', line 242

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) 


85
86
87
 
# File 'lib/rpremote/help.rb', line 85

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

.reset_text ⇒ Object 



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

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 



216
217
218
219
220
221
222
223
 
# File 'lib/rpremote/help.rb', line 216

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

    Uploads FILE to R2P2, relays output, then removes the temporary remote file. Defaults are the automatic CDC 0 port,
    115200 baud, 20 seconds, and picoruby. It exits nonzero when compatible R2P2 firmware reports a Ruby exception.
  HELP
end

.setup_text ⇒ Object 



111
112
113
114
115
116
117
118
119
 
# File 'lib/rpremote/help.rb', line 111

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.
    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