History

Damien George d92694c3e8 tools: Only issue a single Ctrl-C when entering raw REPL. A long time ago when there was only the `stm` port, Ctrl-C would trigger a preemptive NLR jump to break out of running code. Then in commit `124df6f8d0` a more general approach to asynchronous `KeyboardInterrupt` exceptions was implemented, and `stmhal` supported both approaches, with the general (soft) interrupt taking priority. Then in commit `bc1488a05f` `pyboard.py` was updated with a corresponding change to make it issue a double Ctrl-C to break out of any existing code when entering the raw REPL (two Ctrl-C characters were sent in order to more reliably trigger the preemptive NLR jump). No other port has preemptive NLR jumps and so a double Ctrl-C doesn't really behave any differently to a single Ctrl-C: with USB CDC the double Ctrl-C would most likely be in the same USB packet and so processed in the same low-level USB callback, so it's just setting the keyboard interrupt flag twice in a row. The VM/runtime then just sees one keyboard interrupt and acts as though only one Ctrl-C was sent. This commit changes the double Ctrl-C to a single Ctrl-C in `pyboard.py` and `mpremote`. That keeps things as simple as they need to be. Signed-off-by: Damien George <damien@micropython.org>		2024-10-15 11:40:08 +11:00
..
mpremote	tools: Only issue a single Ctrl-C when entering raw REPL.	2024-10-15 11:40:08 +11:00
tests	tools/mpremote: Add initial regression tests for mpremote.	2024-10-09 16:39:00 +11:00
.gitignore	tools/mpremote: Use hatch to build mpremote package.	2023-02-24 11:40:22 +11:00
LICENSE	tools/mpremote: Add command to print the version.	2022-06-07 23:22:04 +10:00
README.md	tools/mpremote: Add hashing ability and use for recursive copy.	2024-10-09 16:35:46 +11:00
mpremote.py	tools/mpremote: Add new CLI utility to interact with remote device.	2021-05-29 17:17:22 +10:00
pyproject.toml	all: Switch to new preview build versioning scheme.	2023-10-06 12:10:14 +11:00
requirements.txt	tools/mpremote: Reduce dependency on importlib_metadata.	2024-01-17 11:27:47 +11:00

README.md

mpremote -- MicroPython remote control

This CLI tool provides an integrated set of utilities to remotely interact with and automate a MicroPython device over a serial connection.

The simplest way to use this tool is:

mpremote

This will automatically connect to a USB serial port and provide an interactive REPL.

The full list of supported commands are:

mpremote connect <device>         -- connect to given device
                                     device may be: list, auto, id:x, port:x
                                     or any valid device name/path
mpremote disconnect               -- disconnect current device
mpremote mount <local-dir>        -- mount local directory on device
mpremote eval <string>            -- evaluate and print the string
mpremote exec <string>            -- execute the string
mpremote run <file>               -- run the given local script
mpremote fs <command> <args...>   -- execute filesystem commands on the device
                                     command may be: cat, ls, cp, rm, mkdir, rmdir, sha256sum
                                     use ":" as a prefix to specify a file on the device
mpremote repl                     -- enter REPL
                                     options:
                                         --capture <file>
                                         --inject-code <string>
                                         --inject-file <file>
mpremote mip install <package...> -- Install packages (from micropython-lib or third-party sources)
                                     options:
                                         --target <path>
                                         --index <url>
                                         --no-mpy
mpremote help                     -- print list of commands and exit

Multiple commands can be specified and they will be run sequentially. 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.

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

a0, a1, a2, a3: connect to /dev/ttyACM?
u0, u1, u2, u3: connect to /dev/ttyUSB?
c0, c1, c2, c3: connect to COM?
cat, ls, cp, rm, mkdir, rmdir, df: filesystem commands
reset: reset the device
bootloader: make the device enter its bootloader

Any user configuration, including user-defined shortcuts, can be placed in .config/mpremote/config.py. For example:

# Custom macro commands
commands = {
    "c33": "connect id:334D335C3138",
    "bl": "bootloader",
    "double x=4": {
        "command": "eval x*2",
        "help": "multiply by two"
    }
}

Examples:

mpremote
mpremote a1
mpremote connect /dev/ttyUSB0 repl
mpremote ls
mpremote a1 ls
mpremote exec "import micropython; micropython.mem_info()"
mpremote eval 1/2 eval 3/4
mpremote mount .
mpremote mount . exec "import local_script"
mpremote ls
mpremote cat boot.py
mpremote cp :main.py .
mpremote cp main.py :
mpremote cp -r dir/ :
mpremote sha256sum :main.py
mpremote mip install aioble
mpremote mip install github:org/repo@branch
mpremote mip install gitlab:org/repo@branch