mpremote(1)

💖 mpremote — MicroPython remote control 💖

okay bestie, buckle up, because this is the mpremote(1) page from the General Commands Manual, and it is genuinely one of the most useful little tools you'll ever meet. it's the remote control for your MicroPython board and i'm gonna walk you through every single thing it does 🫶

---

✨ NAME ✨

mpremote — MicroPython remote control

---

🌸 SYNOPSIS 🌸

mpremote command [options] [+command ...]

mpremote [--help]

mpremote [--version]

---

🦋 DESCRIPTION 🦋

okay so. mpremote is a command line tool that gives you a whole integrated set of utilities to remotely interact with and automate a MicroPython device over a serial connection. that's the whole vibe. it's your little portal into the board ✨

the simplest way to use it is literally just to invoke it with no arguments at all:

mpremote

and that's it. it automatically detects and connects to the first available serial device and drops you into an interactive REPL. main character energy fr fr 💅

heads up bestie: serial ports are opened in exclusive mode, so if you run a second (or third, etc) instance of mpremote, it will connect to subsequent serial devices, if any are available. no fighting over ports in this house 💀

---

💅 OPTIONS 💅

• --help — show a help message and exit. your lil friendly nudge when you forget stuff 🙈
• --version — show the program version and exit. slay 💖

---

👑 COMMANDS 👑

for REPL access, running mpremote with no arguments is usually all you need. but mpremote also supports a set of commands given at the command line which will perform various actions on remote MicroPython devices. it's giving ✨versatile✨

for commands that support multiple arguments (e.g. a list of files), the argument list can be terminated with +. the full list of supported commands are:

• connect [device] — connect to a specified device via a device-name shortcut. device may be one of:
  • auto — connect to the first available device
  • list — list the available devices
  • id:serial — connect to the device with USB serial number serial (the second entry in the output from the connect list command)
  • port:path — connect to the device with the given path
  • if the device is not specified, auto is assumed.
• disconnect — disconnects the current device. after a disconnect, auto soft-reset is enabled (see AUTO-CONNECTION AND SOFT-RESET below).
• resume — resume a previous mpremote session. this disables auto soft-reset (see AUTO-CONNECTION AND SOFT-RESET below).
• soft-reset — perform a soft-reset of the device. this will clear out the Python heap and restart the interpreter. it also disables auto soft-reset (see AUTO-CONNECTION AND SOFT-RESET below).
• repl [options] — enter the REPL on the connected device. the available options are:
  • --capture file — to capture output of the REPL session to the given file
  • --inject-code string — to specify characters to inject at the REPL when Ctrl-J is pressed
  • --inject-file file — to specify a file to inject at the REPL when Ctrl-K is pressed
• eval string — evaluate and print the result of a Python expression.
• exec string — execute the given Python code.
• run file — run a script from the local filesystem.
• fs subcommand — execute filesystem commands on the device. subcommand may be:
  • cat files... — to show the contents of a file or files on the device
  • ls
  • ls dirs... — to list the current, or specified directories
  • cp [-r] src... dest — to copy files; use ":" as a prefix to specify a file on the device
  • rm src... — to remove files on the device
  • mkdir dirs... — to create directories on the device
  • rmdir dirs... — to remove directories on the device
  • touch files... — to create empty files (if they don't already exist)
• edit files... — edit a file (or files) on the device. the edit command will copy each file from the device to a local temporary directory and then launch your editor (defined by the environment variable $EDITOR). if the editor exits successfully, the updated file will be copied back to the device. chef's kiss workflow honestly 🎀
• mip install [options] packages... — install packages from micropython-lib (or GitHub) using the mip tool. the available options are:
  • --target path — install under path instead of the default location (the first entry in sys.path ending in /lib). please note that it must exist in sys.path for you to be able to subsequently import the package.
  • --no-mpy — install the source version .py files rather than .mpy).
  • --index URL — use the specified URL instead of the default package index at https://micropython.org/pi.
• mount [options] local-dir — mount a local directory on the remote device (under the path /remote). during usage, Ctrl-D will soft-reboot and normally reconnect the mount automatically. if the unit has a main.py running at startup however, the remount cannot occur. in this case a raw mode soft reboot can be used: Ctrl-A Ctrl-D to reboot, then Ctrl-B to get back to normal repl at which point the mount will be ready.
  • the available options are:
  • -l, --unsafe-links — by default an error will be raised if the device accesses a file or directory which is outside (up one or more directory levels) the local directory that is mounted. this option disables this check for symbolic links, allowing the device to follow symbolic links outside of the local directory.
• umount — unmount the local directory from the remote device.

---

🔄 AUTO-CONNECTION AND SOFT-RESET 🔄

connection and disconnection will be done automatically at the start and end of the execution of the tool, if such commands are not explicitly given. automatic connection will search for the first available serial device. if no action is specified then the REPL will be entered. it just knows ✨

once connected to a device, mpremote will automatically soft-reset the device if needed. this clears the Python heap and restarts the interpreter, making sure that subsequent Python code executes in a fresh environment. auto soft-reset is performed the first time one of the following commands are executed: mount, eval, exec, run, fs. after doing a soft-reset for the first time, it will not be done again automatically, until a disconnect command is issued.

auto soft-reset behaviour can be controlled by the resume command. and the soft-reset command can be used to perform an explicit soft reset.

---

🌈 SHORTCUTS 🌈

shortcuts can be defined using the macro system. built-in shortcuts are:

• devs — list available devices (shortcut for connect list)
• a0, a1, a2, a3 — connect to /dev/ttyACMn
• u0, u1, u2, u3 — connect to /dev/ttyUSBn
• c0, c1, c2, c3 — connect to COMn
• cat, ls, cp, rm, mkdir, rmdir, touch, df — filesystem commands (mostly aliases for the fs equivalent)
• reset — reset the device
• bootloader — make the device enter its bootloader

any user configuration, including user-defined shortcuts, can be placed in the file ~/.config/mpremote/config.py. for example:

commands = {
    "c33": "connect id:334D335C3138",
    "bl": "bootloader",
    "double x=4": "eval x*2",  # x is an argument, with default 4
    "wl_scan": ["exec", """
import network
wl = network.WLAN()
wl.active(1)
for ap in wl.scan():
    print(ap)
""",],
    "test": ["mount", ".", "exec", "import test"],
}

---

⭐ EXAMPLES ⭐

• mpremote — launch a repl on the automatically detected device.
• mpremote a1 — launch a repl on the device connected to port /dev/ttyACM1 (using the built-in a1 shortcut).
• mpremote connect /dev/ttyUSB0 repl — launch a repl on the device connect to port /dev/ttyUSB0.
• mpremote ls — list files on the automatically detected device.
• mpremote a1 ls — list files on the device connected to port /dev/ttyACM1 (using the built-in a1 shortcut).
• mpremote exec import micropython; micropython.mem_info() — execute some Python code on the remote board to obtain various memory statistics.
• mpremote eval 1/2 eval 3/4 — execute (and show the output of) two simple Python statements on the remote board. note that no + was required because eval accepts a single string argument.
• mpremote mount . — mount the local directory under /remote on the automatically detected device.
• mpremote mount . exec "import localscript" — mount the local directory under /remote on the MicroPython board, then import the "localscript" module
• mpremote cat boot.py — show the contents of boot.py on the MicroPython board.
• mpremote cp :main.py . — copy the main.py file from the (remote) MicroPython board to the current (local) directory.
• mpremote cp main.py : — copy the main.py from the current (local) directory to the (remote) MicroPython board.
• mpremote cp :a.py :b.py — on the MicroPython board, copy a.py to b.py.
• mpremote cp -r dir/ : — recursively copy the local directory dir/ to the root directory of the (remote) MicroPython board.
• mpremote cp a.py b.py : + repl — copy the local files a.py and b.py to the root directory of the (remote) MicroPython board, then launch a repl. note that the + terminator is required here as the cp command takes an arbitrary number of parameters.
• mpremote mip install aioble — install the asyncio-based wrapper for the Bluetooth API.
• mpremote mip install github:org/repo@branch — install the branch of the MicroPython package located under org/repo on GitHub.
• mpremote mip install --target /flash/third-party functools — install the functools package under the /flash/third-party directory on the MicroPython board.

---

🫶 SEE ALSO 🫶

micropython(1)

---

and that's the whole page bestie!! 💖 this was mpremote(1) from the General Commands Manual, section 1, no cap. go forth and remote-control your board, you absolute icon 👑✨