RSHELL(1)

✨ rshell ✨

okay bestie, welcome to the rshell manual — it's the General Commands Manual entry for rshell(1), aka the Remote Shell for a MicroPython board. sit down, grab a snack, we're doing this 💅

---

🌸 NAME 🌸

rshell — Remote Shell for a MicroPython board 🫶

---

🎀 SYNOPSIS 🎀

like, here's how you actually call her:

rshell [-b baud] [-p port] [--rts 1|0] [--dtr 1|0] [-u user]
       [-w password] [-e editor] [-f filename] [-d] [-n] [-l] [-a]
       [--buffer-size bytes] [--wait seconds] [--timing] [--quiet] [cmd]

and the two lil shortcut modes:

rshell -h

rshell -V

(yes -l and -V are living in the synopsis rent-free — they're in the original, so they're staying. no cap.)

---

🦋 DESCRIPTION 🦋

so rshell is a simple shell that runs on your host machine and talks to your pyboard using MicroPython's raw-REPL. the way that works is it sends python snippets over to the board to (1) get filesystem information and (2) copy files to and from MicroPython's filesystem. it's giving remote control but make it filesystem 💖

it can also invoke the regular REPL, so rshell doubles as a terminal emulator. iconic behavior honestly.

NOTE: with rshell you can disable USB Mass Storage and still copy files into and out of your pyboard. slay. 🔥

when you're using the commands, the /flash directory and the /sdcard directory (if an sdcard is inserted) are considered to be on the pyboard, and all other directories are considered to be on the host. for an ESP based board you can only reference its directory by using the board name, e.g. /pyboard, etc. iykyk 🧚

NOTE: rshell requires a fairly recent version of the MicroPython firmware — specifically one which contains the ubinascii.unhexlify command, which was added May 19, 2015 (v1.4.3-28-ga3a14b9 or newer). not negotiable bestie 😭

if your version of the firmware isn't new enough, then you'll see an error message something like this:

$ rshell
rshell needs MicroPython firmware with ubinascii.unhexlify

---

💅 OPTIONS 💅

the full menu, no skips, no shortcuts:

• -h, --help — show a help message and exit. the classic "wait what do i do" button 🫶
• -a, --ascii — on certain platforms the raw REPL mode is unreliable with particular sequences of binary characters. specifying --ascii enables the transfer of binary files to such platforms. it does this by encoding the data as ASCII hex. a workaround, but a cute one ✨
• -b, --baud=BAUD — sets the baud rate to use when talking to the pyboard over a serial port. if no baud is specified, then the baudrate from the RSHELL_BAUD environment variable is used. if the RSHELL_BAUD environment variable is not defined then the default baudrate of 115200 is used. periodt.
• --buffer-size=BUFFER_SIZE — sets the buffer size used when transferring files between the host and the pyboard. if no buffer size is specified, then the value from the RSHELL_BUFFER_SIZE environment variable is used. if the RSHELL_BUFFER_SIZE environment variable is not defined, then the default of 512 is used. she's little but she's doing her best 🍓
• -d, --debug — turns on debugging. this allows you to see the script which is sent over the raw REPL and the response received. peak transparency, we love to see it 👑
• --dtr=[0|1|True|False] — sets the state of the DTR line when opening the serial port. this may also be defaulted from the RSHELL_DTR environment variable.
• -e, --editor=EDITOR — specifies the editor to use with the edit command. if no editor is specified, then the following environment variables will be searched: RSHELL_EDITOR, VISUAL, and EDITOR. if none of those environment variables is set then vi will be used. (yes, vi. she's old money 💀)
• -f, --file=FILENAME — specifies a file of rshell commands to process. this allows you to create a script which executes any valid rshell commands. scripted slay 🔥
• -n, --nocolor — by default, rshell uses ANSI color escape codes when displaying the prompt and ls output. this option allows colorized output to be disabled. (a crime, but okay, your terminal your rules 🙈)
• -p, --port=PORT — specifies the serial port which should be used to talk to the MicroPython board. you can set the RSHELL_PORT environment variable to specify the default port to be used, if --port is not specified on the command line.
• --quiet — this option causes the Connecting messages printed when rshell starts to be suppressed. this is mostly useful for the test scripts. shhh 🤫
• --rts=[0|1|True|False] — sets the state of the RTS line when opening the serial port. this may also be defaulted from the RSHELL_RTS environment variable.
• --timing — if the timing option is specified then rshell will print the amount of time that each command takes to execute. performance review core ⏱️
• -u, --user=USER — specifies the username to use when logging into a WiPy over telnet. if no username is specified, then the username from the RSHELL_USER environment variable is used. if the RSHELL_USER environment variable doesn't exist then the default username 'micro' is used.
• -w, --password=PASSWORD — specified the password to use when logging into a WiPy over telnet. if no password is specified, then the password from the RSHELL_PASSWORD environment variable is used. if the RSHELL_PASSWORD environment variable doesn't exist then the default password 'python' is used. (and yes, the original really does say "specified" there — we keep the lore 🫶)
• --wait — if a port is specified defines how long rshell will wait for the port to exist and for a connection to be established. the default is 0 seconds specifying an immediate return. no patience, respect 💅
• cmd — if a command is specified, then that command will be executed and rshell will exit. one and done, bye bestie 👋

---

🌈 FILE SYSTEM 🌈

rshell can be connected to multiple pyboards simultaneously. the way that works is:

if the board module exists on the pyboard (i.e. a file named board.py somewhere in the module search path) and it contains an attribute called name (e.g. name = "myboard") then the pyboard will use that name. if the board module can't be imported then the board will be named pyboard or wipy. names will have -1 (or some other number) to make the board name unique. lowkey a naming ceremony 🎀

you can access the internal flash on the first board connected using /flash and the sd card on the first board connected can be accessed using /sd. 🦋

for all other connected pyboards, you can use /board-name/flash or /board-name/sd (you can see the board names using the boards command).

the boards command will show all of the connected pyboards, along with all of the directories which map onto that pyboard. main character energy fr fr 👑

args [ARGUMENTS...]

A lil debug function for vibe-checking argument parsing 💅 it literally just prints out each argument it receives. That's it. That's the whole job.

boards

Lists all of the boards that rshell is currently connected to, their names, and the connection. ✨

You can give a board a custom name by either copying over a board.py file or using the echo command, like:

echo 'name="myboard"' > /pyboard/board.py

Remember to exit rshell and re-enter to see the change. no cap, it won't show up otherwise 🙈

cat FILENAME...

Concatenates files and sends to stdout. classic cat behaviour, iconic, we love her 🐈

cd DIRECTORY

Changes the current directory. ~ expansion is supported, and cd - goes to the previous directory. yes bestie, the little dash is your "wait go back" button 🫶

connect TYPE TYPE_PARAMS

connect serial PORT [BAUD]

connect telnet IP-ADDR-OR-NAME

Connects a pyboard to rshell. And here's the slay part: rshell can be connected to multiple pyboards simultaneously. 👑

cp SOURCE... DEST

cp [-r|--recursive] [SOURCE|SRC_DIR]... DIRECTORY

cp [-r|--recursive] PATTERN DIRECTORY

Copies the SOURCE file to DEST. DEST may be a filename or a directory name. If more than one source file is specified, then the destination should be a directory.

Directories will only be copied if --recursive is specified. fr fr, don't come crying to me when your folder doesn't move.

A single pattern may be specified, in which case the destination should be a directory. Pattern matching is performed according to a subset of the Unix rules (see below).

Recursive copying uses the rsync command (see below): where a file exists on source and destination, it will only be copied if the source is newer than the destination. so it's giving "only the fresh stuff gets through" 💅

echo TEXT...

Display a line of text. simple. perfect. no notes. 🌸

edit FILENAME

If the file is on a pyboard, it copies the file to host, invokes an editor and if any changes were made to the file, it copies it back to the pyboard. round trip bestie ✈️

The editor which is used defaults to vi, but can be overridden using either the --editor command line option when rshell is invoked, or by using the RSHELL_EDITOR, VISUAL or EDITOR environment variables (they are tried in the order listed). order matters, don't @ me.

filesize FILE

Prints the size of the file, in bytes. This function is primarily for testing. lowkey just a number printer 🔢

filetype FILE

Prints the type of file (dir or file). This function is primarily for testing. also lowkey just a label printer 🏷️

help [COMMAND]

List available commands with no arguments, or detailed help when a command is provided. the girl who knows everything when you ask her nicely 💁

ls [-a] [-l] [FILE|DIRECTORY|PATTERN]...

List directory contents. If --long is specified, a long listing format is used. --all may be specified to show hidden files. Pattern matching is performed according to a subset of the Unix rules (see below).

mkdir DIRECTORY...

Creates one or more directories. plural. ambitious. we stan a go-getter 🌈

repl [BOARD-NAME] [~ LINE] [~]

Enters into the regular REPL with the MicroPython board. Use Control-X to exit REPL mode and return the shell. It may take a second or two before the REPL exits. be patient bestie, she's coming back 😭

If you provide a BOARD-NAME then rshell will connect to that board, otherwise it will connect to the default board (first connected board).

If you provide a tilde followed by a space (~ ) then anything after the tilde will be entered as if you typed it on the command line.

If you want the repl to exit, end the line with the ~ character.

For example, you could use:

rshell repl \~ pyb.bootloader\(\)\~

and it will boot the pyboard into DFU. 🔥

If you want to execute multiple Python commands these should be separated by the ~ character (not the ; character):

rshell repl \~ import mymodule \~ mymodule.run\(\)

NOTE: Escaping (or quoting) of tilde (and parentheses) is likely to be necessary to prevent shell-expansion if you are running rshell from bash. Such escaping is not required if running repl from within an rshell session.

rm [-f|--force] FILE...

rm [-f|--force] PATTERN

rm -r [-f|--force] PATTERN

rm -r [-f|--force] [FILE|DIRECTORY]...

Removes files or directories (including their contents). 💀

A single pattern may be specified. Pattern matching is performed according to a subset of the Unix rules (see below). Directories can only be removed if the --recursive argument is provided.

Beware of rm -r * or worse. genuinely. this is your villain origin story warning, bestie, do not do it 🙈

rsync [-m|--mirror] [-n|--dry-run] [-q|--quiet] SRC_DIR DEST_DIR

Recursively synchronises a source directory to a destination. Directories must exist. no conjuring dirs out of thin air ✨

If --mirror is specified, files or directories will be removed from the destination if they are absent in the source. --dry-run can be specified to report what would be done without making any changes. a little sneak preview, no commitment 🎀

Synchronisation is performed by comparing the date and time of source and destination files. Files are copied if the source is newer than the destination.

shell [COMMAND]

! [COMMAND]

The shell command can be abbreviated using the exclamation point. This will invoke a command, and return back to rshell. Example:

!make deploy

will flash the pyboard. 🦋

---

🌈 PATTERN MATCHING 🌈

This is performed according to a subset of the Unix rules. The limitations are that wildcards are only allowed in the rightmost directory of a path and curly bracket {} syntax is unsupported:

• *.py — Match files in current directory with a .py extension.
• temp/x[0-9]a.* — Match temp/x1a.bmp but not temp/x00a.bmp
• t*/*.bmp — Invalid: will produce an error message
• {*.doc,*.pdf} — Invalid: will produce an error message

so basically: rightmost dir only, no curly bracket shenanigans, or she WILL yell at you. 💅

---

and that's a wrap on RSHELL(1), bestie 💖 this page is dated 2022-04-14 and lives under the name RSHELL(1) — go forth, connect all the boards, and don't rm -r * anything you love. mwah. 🫶✨🌸