README.md
1# mpremote -- MicroPython remote control
2
3This CLI tool provides an integrated set of utilities to remotely interact with
4and automate a MicroPython device over a serial connection.
5
6The simplest way to use this tool is:
7
8 mpremote
9
10This will automatically connect to the device and provide an interactive REPL.
11
12The full list of supported commands are:
13
14 mpremote connect <device> -- connect to given device
15 device may be: list, auto, id:x, port:x
16 or any valid device name/path
17 mpremote disconnect -- disconnect current device
18 mpremote mount <local-dir> -- mount local directory on device
19 mpremote eval <string> -- evaluate and print the string
20 mpremote exec <string> -- execute the string
21 mpremote run <file> -- run the given local script
22 mpremote fs <command> <args...> -- execute filesystem commands on the device
23 command may be: cat, ls, cp, rm, mkdir, rmdir
24 use ":" as a prefix to specify a file on the device
25 mpremote repl -- enter REPL
26 options:
27 --capture <file>
28 --inject-code <string>
29 --inject-file <file>
30
31Multiple commands can be specified and they will be run sequentially. Connection
32and disconnection will be done automatically at the start and end of the execution
33of the tool, if such commands are not explicitly given. Automatic connection will
34search for the first available serial device. If no action is specified then the
35REPL will be entered.
36
37Shortcuts can be defined using the macro system. Built-in shortcuts are:
38
39- a0, a1, a2, a3: connect to `/dev/ttyACM?`
40- u0, u1, u2, u3: connect to `/dev/ttyUSB?`
41- c0, c1, c2, c3: connect to `COM?`
42- cat, ls, cp, rm, mkdir, rmdir, df: filesystem commands
43- reset: reset the device
44- bootloader: make the device enter its bootloader
45
46Any user configuration, including user-defined shortcuts, can be placed in
47.config/mpremote/config.py. For example:
48
49 # Custom macro commands
50 commands = {
51 "c33": "connect id:334D335C3138",
52 "bl": "bootloader",
53 "double x=4": "eval x*2",
54 }
55
56Examples:
57
58 mpremote
59 mpremote a1
60 mpremote connect /dev/ttyUSB0 repl
61 mpremote ls
62 mpremote a1 ls
63 mpremote exec "import micropython; micropython.mem_info()"
64 mpremote eval 1/2 eval 3/4
65 mpremote mount .
66 mpremote mount . exec "import local_script"
67 mpremote ls
68 mpremote cat boot.py
69 mpremote cp :main.py .
70 mpremote cp main.py :
71 mpremote cp -r dir/ :
72