{"id":13802706,"url":"https://github.com/bulletmark/mpr","last_synced_at":"2025-04-19T12:12:47.149Z","repository":{"id":39832843,"uuid":"507213540","full_name":"bulletmark/mpr","owner":"bulletmark","description":"Wrapper for MicroPython mpremote tool","archived":false,"fork":false,"pushed_at":"2024-07-30T01:25:45.000Z","size":86,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-11T12:09:48.096Z","etag":null,"topics":["ampy","micropython","mpfshell","mpremote","rshell","thonny","upydev","upyloader","webrepl"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bulletmark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-25T04:32:45.000Z","updated_at":"2024-08-28T06:59:19.000Z","dependencies_parsed_at":"2023-02-09T17:20:18.078Z","dependency_job_id":"bf590860-d8be-4fb7-bd2f-b79de7ce9c63","html_url":"https://github.com/bulletmark/mpr","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Fmpr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Fmpr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Fmpr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Fmpr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bulletmark","download_url":"https://codeload.github.com/bulletmark/mpr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246031181,"owners_count":20712503,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ampy","micropython","mpfshell","mpremote","rshell","thonny","upydev","upyloader","webrepl"],"created_at":"2024-08-04T00:01:50.713Z","updated_at":"2025-03-30T21:31:52.025Z","avatar_url":"https://github.com/bulletmark.png","language":"Python","readme":"## MPR - Wrapper for MicroPython mpremote tool\n[![PyPi](https://img.shields.io/pypi/v/mpr)](https://pypi.org/project/mpr/)\n[![AUR](https://img.shields.io/aur/version/mpr)](https://aur.archlinux.org/packages/mpr/)\n\nThe [mpremote][mpremote] command line tool is used to interact with a\n[MicroPython][upy] device over a USB/serial connection. It's an official\npart of [MicroPython][upy], well featured, and it works more reliably\nthan competing tools. However, [mpremote][mpremote] exhibits an\nunconventional and slightly awkward Linux command line interface.\n[mpremote][mpremote] allows \"chaining\" of multiple sequential commands\nbut the vast majority of users merely want to copy/delete files etc and\nunfortunately the [mpremote][mpremote] user interface compromises\nusability for those most common use-cases. Also, users expect in-built\nhelp for all commands so they can easily see usage and expected\narguments (e.g. like [git](https://git-scm.com/) provides).\n\nSo [mpr][mpr] presents an alternative interface which wraps\n[mpremote][mpremote] to make it appear like a conventional Linux\ncommand line tool where only a single command is accepted (although\nthere are global options to connect an explicit device; and/or mount a\nlocal directory before that command; and/or reset/reboot after the\ncommand). Unlike [mpremote][mpremote], [mpr][mpr] always allows you to\nexploit your shell wildcard abilities to pass multiple file/directory\narguments to commands. Full in-built usage help is available for the\ntool, and each of it's commands (see [Usage](#usage) section below). It\nalso provides a novel shortcut mechanism to [infer target device\ndirectories](#directorypath-inference) based on where on your local PC\nyou are copying files from or to. There are a few other nice\n[features](#compatibility-notes). The following session shows small\nexamples of [mpr][mpr] in use.\n\n```\n$ tree\n./\n├── Makefile\n├── boot.py\n├── main.py\n├── package_a.py\n└── package_b/\n    ├── file1.py\n    └── file2.py\n\n# View the inbuild usage/help for the put command (Note you can just type\n# mpr without any arguments to see all available commands, see Usage\n# section below):\n$ mpr put -h\nusage: mpr put [-h] [-f] [-r] src [src ...] dst\n\nCopy one or more local files to directory on device.\n\npositional arguments:\n  src              name of local source file[s] on PC\n  dst              name of destination dir on device\n\noptions:\n  -h, --help       show this help message and exit\n  -f, --file       destination is file, not directory\n  -r, --recursive  copy local directory recursively to / on device\n\n# Copy all Python files to root on device:\n$ mpr put *.py /\ncp boot.py :boot.py\ncp main.py :main.py\ncp package_a.py :package_a.py\n\n# Create package_b dir and copy all package_b Python files:\n$ mpr mkdir package_b\nmkdir :package_b\n$ cd package_b\n# The following exploits mpr's directory inference feature to save typing\n# the target directory, see Directory/Path Inference section below:\n$ mpr put *.py //\ncp file1.py :package_b/file1.py\ncp file2.py :package_b/file2.py\n\n# Connect to explicit 1st port, mount local dir, and then import main.py:\n$ mpr -d id:0001 -m . exec 'import main'\n...\n```\n\nI have developed this tool on Linux. The latest version and\ndocumentation is available at https://github.com/bulletmark/mpr.\n\n## Installation\n\nArch Linux users can install [mpr from the\nAUR](https://aur.archlinux.org/packages/mpr/).\n\nPython 3.7 or later is required. The [mpremote][mpremote] program must be\n[installed](#path-to-mpremote). If you want to use the `xrun` command then you\nalso need to install the [mpy-cross][mpy-cross] program.\n\nNote [mpr][mpr-py], [mpremote][mpremote-py], and [mpy-cross][mpy-cross] are\nall available on [PyPI](https://pypi.org/) and so the easiest way to install them is to use\n[`uv tool`][uvtool] (or [`pipx`][pipx] or [`pipxu`][pipxu]). I.e:\n\nTo install:\n\n```sh\n$ uv tool install mpr\n$ uv tool install mpremote\n$ uv tool install mpy-cross  # if needed, for xrun command\n```\n\nTo upgrade:\n\n```sh\n$ uv tool upgrade mpr mpremote mpy-cross\n```\n\nTo uninstall:\n\n```sh\n$ uv tool uninstall mpr mpremote mpy-cross\n```\n\n## Usage\n\nType `mpr` or `mpr -h` to view the usage summary:\n\n```\nusage: mpr [-h] [-d DEVICE] [-m MOUNT] [-M MOUNT_UNSAFE_LINKS] [-x]\n                   [-b] [-p PATH_TO_MPREMOTE] [-X PATH_TO_MPY_CROSS]\n                   [--mip-list-url MIP_LIST_URL] [-v] [-V]\n                   {get,g,put,p,copy,c,ls,mkdir,mkd,rmdir,rmd,rm,touch,edit,e,reset,x,reboot,b,repl,r,list,l,devs,run,xrun,xr,exec,eval,mip,m,bootloader,df,rtc,version,config,cf} ...\n\nThis is a command line tool to wrap the MicroPython mpremote tool and provide\na more conventional command line interface. Multiple arguments can be\nspecified for commands and inbuilt usage help is provided for all commands.\n\noptions:\n  -h, --help            show this help message and exit\n  -d, --device DEVICE   serial port/device to connect to, default is \"auto\".\n                        Specify \"-d list\" to print out device mnemonics that\n                        can be used.\n  -m, --mount MOUNT     mount local directory on device before command\n  -M, --mount-unsafe-links MOUNT_UNSAFE_LINKS\n                        mount local directory and allow external links\n  -x, --reset           do soft reset after command\n  -b, --reboot          do hard reboot after command\n  -p, --path-to-mpremote PATH_TO_MPREMOTE\n                        path to mpremote program. Assumes same directory as\n                        this program, or then just \"mpremote\"\n  -X, --path-to-mpy-cross PATH_TO_MPY_CROSS\n                        path to mpy-cross program (for xrun command). Assumes\n                        same directory as mpremote, or then just \"mpy-cross\"\n  --mip-list-url MIP_LIST_URL\n                        mip list url for packages,\n                        default=\"https://micropython.org/pi/v2/index.json\"\n  -v, --verbose         print mpremote execution command line (for debug)\n  -V, --version         print mpr version\n\nCommands:\n  {get,g,put,p,copy,c,ls,mkdir,mkd,rmdir,rmd,rm,touch,edit,e,reset,x,reboot,b,repl,r,list,l,devs,run,xrun,xr,exec,eval,mip,m,bootloader,df,rtc,version,config,cf}\n    get (g)             Copy one or more files from device to local directory.\n    put (p)             Copy one or more local files to directory on device.\n    copy (c)            Copy one of more remote files to a directory on\n                        device.\n    ls                  List directory on device.\n    mkdir (mkd)         Create the given directory[s] on device.\n    rmdir (rmd)         Remove the given directory[s] on device.\n    rm                  Remove the given file[s] on device.\n    touch               Touch the given file[s] on device.\n    edit (e)            Edit the given file[s] on device.\n    reset (x)           Soft reset the device.\n    reboot (b)          Hard reboot the device.\n    repl (r)            Enter REPL on device.\n    list (l, devs)      List currently connected devices.\n    run                 Run the given local program on device.\n    xrun (xr)           Tool to compile and run a local application/program on\n                        device.\n    exec                Execute the given strings on device.\n    eval                Evaluate and print the given strings on device.\n    mip (m)             Install packages from micropython-lib or third-party\n                        sources.\n    bootloader          Enter bootloader on device.\n    df                  Show flash usage on device.\n    rtc                 Get/set the Real Time Clock (RTC) time from/to device.\n    version             Show mpremote version.\n    config (cf)         Open the mpr configuration file with your editor.\n\nType \"mpr \u003ccommand\u003e -h\" to see specific help/usage for any of the above\ncommands. Some commands offer a short alias as seen in parentheses above. Note\nyou can set default options in ~/.config/mpr.conf (e.g. for --path-to-mpremote\nor --mip-list-url). Use \"mpr config\" to conveniently change the file.\n```\n\nType `mpr \u003ccommand\u003e -h` to see specific help/usage for any\nindividual command:\n\n### Command `get`\n\n```\nusage: mpr get [-h] [-f] [-r] [-F] src [src ...] dst\n\nCopy one or more files from device to local directory.\n\npositional arguments:\n  src              name of source file[s] on device\n  dst              name of local destination dir on PC, or \"-\" for stdout\n\noptions:\n  -h, --help       show this help message and exit\n  -f, --file       destination is file, not directory\n  -r, --recursive  copy directory recursively\n  -F, --force      force recursive copy to overwrite identical files\n\naliases: g\n```\n\n### Command `put`\n\n```\nusage: mpr put [-h] [-f] [-r] [-F] src [src ...] dst\n\nCopy one or more local files to directory on device.\n\npositional arguments:\n  src              name of local source file[s] on PC\n  dst              name of destination dir on device\n\noptions:\n  -h, --help       show this help message and exit\n  -f, --file       destination is file, not directory\n  -r, --recursive  copy directory recursively\n  -F, --force      force recursive copy to overwrite identical files\n\naliases: p\n```\n\n### Command `copy`\n\n```\nusage: mpr copy [-h] [-f] [-r] [-F] src [src ...] dst\n\nCopy one of more remote files to a directory on device.\n\npositional arguments:\n  src              name of source file[s] on device\n  dst              name of destination dir on device\n\noptions:\n  -h, --help       show this help message and exit\n  -f, --file       destination is file, not directory\n  -r, --recursive  copy directory recursively\n  -F, --force      force recursive copy to overwrite identical files\n\naliases: c\n```\n\n### Command `ls`\n\n```\nusage: mpr ls [-h] [dir]\n\nList directory on device.\n\npositional arguments:\n  dir         name of dir (default: /)\n\noptions:\n  -h, --help  show this help message and exit\n\naliases: \u003cnone\u003e\n```\n\n### Command `mkdir`\n\n```\nusage: mpr mkdir [-h] [-q] dir [dir ...]\n\nCreate the given directory[s] on device.\n\npositional arguments:\n  dir          name of dir[s]\n\noptions:\n  -h, --help   show this help message and exit\n  -q, --quiet  supress normal and error output\n\naliases: mkd\n```\n\n### Command `rmdir`\n\n```\nusage: mpr rmdir [-h] [-q] [--rf] [-d DEPTH] dir [dir ...]\n\nRemove the given directory[s] on device.\n\npositional arguments:\n  dir                name of dir[s]\n\noptions:\n  -h, --help         show this help message and exit\n  -q, --quiet        supress normal and error output\n  --rf               force remove given directories and files recursively and\n                     quietly\n  -d, --depth DEPTH  use with --rf to remove paths recursively to given depth\n                     only, 1=\"/*\", 2=\"/*/*\", etc. Default is no limit.\n\naliases: rmd\n```\n\n### Command `rm`\n\n```\nusage: mpr rm [-h] [-q] [--rf] [-d DEPTH] file [file ...]\n\nRemove the given file[s] on device.\n\npositional arguments:\n  file               name of file[s]\n\noptions:\n  -h, --help         show this help message and exit\n  -q, --quiet        supress normal and error output\n  --rf               force remove given directories and files recursively and\n                     quietly\n  -d, --depth DEPTH  use with --rf to remove paths recursively to given depth\n                     only, 1=\"/*\", 2=\"/*/*\", etc. Default is no limit.\n\naliases: \u003cnone\u003e\n```\n\n### Command `touch`\n\n```\nusage: mpr touch [-h] file [file ...]\n\nTouch the given file[s] on device.\n\npositional arguments:\n  file        name of file[s]\n\noptions:\n  -h, --help  show this help message and exit\n\naliases: \u003cnone\u003e\n```\n\n### Command `edit`\n\n```\nusage: mpr edit [-h] file [file ...]\n\nEdit the given file[s] on device. Copies the file from device, opens your\neditor on that local file, then copies it back.\n\npositional arguments:\n  file        name of file[s]\n\noptions:\n  -h, --help  show this help message and exit\n\naliases: e\n```\n\n### Command `reset`\n\n```\nusage: mpr reset [-h]\n\nSoft reset the device.\n\noptions:\n  -h, --help  show this help message and exit\n\naliases: x\n```\n\n### Command `reboot`\n\n```\nusage: mpr reboot [-h] [delay_ms]\n\nHard reboot the device.\n\npositional arguments:\n  delay_ms    optional delay before reboot (millisecs)\n\noptions:\n  -h, --help  show this help message and exit\n\naliases: b\n```\n\n### Command `repl`\n\n```\nusage: mpr repl [-h] [-e] [-c CAPTURE] [-x INJECT_CODE]\n                        [-i INJECT_FILE]\n\nEnter REPL on device.\n\noptions:\n  -h, --help            show this help message and exit\n  -e, --escape-non-printable\n                        print non-printable bytes/chars as hex codes\n  -c, --capture CAPTURE\n                        capture output of the REPL session to given file\n  -x, --inject-code INJECT_CODE\n                        characters to inject at the REPL when Ctrl-J is\n                        pressed\n  -i, --inject-file INJECT_FILE\n                        file to inject at the REPL when Ctrl-K is pressed\n\naliases: r\n```\n\n### Command `list`\n\n```\nusage: mpr list [-h]\n\nList currently connected devices.\n\noptions:\n  -h, --help  show this help message and exit\n\naliases: l, devs\n```\n\n### Command `run`\n\n```\nusage: mpr run [-h] [-f] script [script ...]\n\nRun the given local program on device.\n\npositional arguments:\n  script           script to run\n\noptions:\n  -h, --help       show this help message and exit\n  -f, --no-follow  do not keep following output, return immediately\n\naliases: \u003cnone\u003e\n```\n\n### Command `xrun`\n\n```\nusage: mpr xrun [-h] [-f] [-D DEPTH] [-o] [-C] [-e EXCLUDE]\n                        [--map MAP] [-1]\n                        [prog] [args ...]\n\nTool to compile and run a local application/program on device. Displays\nprogram output in your local terminal using mpremote and, in parallel, it\nwaits watching for edits/changes to Python source files in the associated\ndirectory tree on your host. When changes are detected then new .mpy bytecode\nfiles for changed files are compiled using mpy-cross in a hidden cache\ndirectory on your host and then copied to the device. The specified program is\nthen restarted and redisplayed in your local terminal. Command line arguments\non the host can be passed to the program via sys.argv on the device. Only .mpy\nbytecode files are copied to the device, never .py source files, and the\nspecified prog[.py] is imported to run as a .mpy file. So you run this utility\nin one terminal window while you edit your source files in other windows and\nyour program will be automatically restarted and redisplayed each time you\nsave your changes. Since all bytecode compilation is done on your host, not on\nthe remote device, your development workflow is faster to build, load, and\nrun; and device memory usage and fragmentation is significantly reduced. Note\nthat you can specify default options for this command locally in your working\ndirectory in mpr-xrun.conf, or globally in ~/.config/mpr-xrun.conf.\n\npositional arguments:\n  prog                  name of .py module to run, e.g. \"main.py\". If not\n                        specified then new .mpy files are merely compiled and\n                        copied to the device.\n  args                  optional arguments to pass in sys.argv to started\n                        program. Separate with -- if switch options are passed\n\noptions:\n  -h, --help            show this help message and exit\n  -f, --flush           flush cache and force update of all .mpy files at\n                        start\n  -D, --depth DEPTH     directory depth limit, 1 = current directory only\n  -o, --only            only monitor the specified program file, not the whole\n                        directory/tree\n  -C, --compile-only    just compile new .mpy files, don't copy to device or\n                        run any program\n  -e, --exclude EXCLUDE\n                        exclude specified directory or file from monitoring.\n                        Can specify this option multiple times. If you exclude\n                        a directory then all files/dirs below it are also\n                        excluded. Default excludes are \"main.py\" and\n                        \"boot.py\". Any specified runnable \"prog\" file is\n                        removed from the excludes list.\n  --map MAP             map specified source name to different target name\n                        when run as main prog, e.g. \"main:main1\" to map\n                        main.py -\u003e main1.mpy on target and \"main1\" will be\n                        run. Can specify this option multiple times, e.g. may\n                        want to map main.py and boot.py permanently for when\n                        you run either as prog.\n  -1, --once            run once only\n\naliases: xr\n```\n\n### Command `exec`\n\n```\nusage: mpr exec [-h] [-f] string [string ...]\n\nExecute the given strings on device.\n\npositional arguments:\n  string           string to execute\n\noptions:\n  -h, --help       show this help message and exit\n  -f, --no-follow  do not keep following output, return immediately\n\naliases: \u003cnone\u003e\n```\n\n### Command `eval`\n\n```\nusage: mpr eval [-h] string [string ...]\n\nEvaluate and print the given strings on device.\n\npositional arguments:\n  string      string to evaluate\n\noptions:\n  -h, --help  show this help message and exit\n\naliases: \u003cnone\u003e\n```\n\n### Command `mip`\n\n```\nusage: mpr mip [-h] [-n] [-t TARGET] [-i INDEX]\n                       {install,list} [package ...]\n\nInstall packages from micropython-lib or third-party sources.\n\npositional arguments:\n  {install,list}       mip command\n  package              package specifications, e.g. \"name\", \"name@version\",\n                       \"github.org/repo\", \"github.org/repo@branch\"\n\noptions:\n  -h, --help           show this help message and exit\n  -n, --no-mpy         download .py files, not compiled .mpy files\n  -t, --target TARGET  destination directory on device, default=\"/lib\"\n  -i, --index INDEX    package index to use, default=\"micropython-lib\"\n\naliases: m\n```\n\n### Command `bootloader`\n\n```\nusage: mpr bootloader [-h]\n\nEnter bootloader on device.\n\noptions:\n  -h, --help  show this help message and exit\n\naliases: \u003cnone\u003e\n```\n\n### Command `df`\n\n```\nusage: mpr df [-h]\n\nShow flash usage on device.\n\noptions:\n  -h, --help  show this help message and exit\n\naliases: \u003cnone\u003e\n```\n\n### Command `rtc`\n\n```\nusage: mpr rtc [-h] [-s]\n\nGet/set the Real Time Clock (RTC) time from/to device.\n\noptions:\n  -h, --help  show this help message and exit\n  -s, --set   set the RTC to the current PC time, default is to get the time\n\naliases: \u003cnone\u003e\n```\n\n### Command `version`\n\n```\nusage: mpr version [-h]\n\nShow mpremote version.\n\noptions:\n  -h, --help  show this help message and exit\n\naliases: \u003cnone\u003e\n```\n\n### Command `config`\n\n```\nusage: mpr config [-h]\n\nOpen the mpr configuration file with your editor.\n\noptions:\n  -h, --help  show this help message and exit\n\naliases: cf\n```\n\n## Compatibility Notes\n\nThis section describes differences that users transitioning from\n[mpremote][mpremote] to [mpr][mpr] should be aware of.\n\nThe usage/arguments of individual mpremote commands are not easily\ndiscoverable. mpr overcomes this by providing in-built full\n[usage](#usage) help for every individual command:\n\n```\n# See overall help:\n$ mpr (or mpr -h)\n\n# See help for a specific command:\n$ mpr mkdir -h\n```\n\nUnlike mpremote, mpr implements each command as a standard Pythog\n[Argparse\nsubparser](https://docs.python.org/3/library/argparse.html#sub-commands)\nwhich means the help output is automatically generated from the software\ncode so the user can be confident the help output is complete, and the\nindividual command descriptions are syntactically accurate.\n\nMost mpremote commands are available, but some are implemented in a\ndifferent manner. Commands can not be chained, but that is usually only\nrequired for the mpremote `connect` and `mount` commands. In mpr, these\ntwo commands are available as global command line options, not as\nexplicit commands. So for example, to connect to a specific device and\nmount your local directory before importing a module in mpremote you can\ndo the following:\n\n```\n$ mpremote connect id:0001 mount . exec 'import test'\n```\n\nThe equivalent mpr command is:\n\n```\n$ mpr -d id:0001 -m . exec 'import test'\n```\n\nAll device full path names and mpremote defined [shortcut\nnames](#device-shortcut-names) can be used for the `-d/--device`\noption. For convenience, you can type `mpr -d list` to print out the\nstandard mpremote device names and shortcuts.\n\nThe `cp` command in mpremote is implemented with explicit `get` and\n`put` commands in mpr so there is no need for the user to use a `:` char\nto infer direction.\n\nmpr provides shortcut aliases for the most commonly used longer\ncommands, e.g. `r` for `repl`, `p` for `put`, and `g` for `get`. See the\nmain help/usage for a list of all commands and their aliases. E.g,\nthe command `mpr put *.py /` can instead be tersely typed as: `mpr p *.py /`.\n\nNote that the mpr `get`, `put`, and `copy` commands always expect the\nspecified target argument to be a directory, so if you want to rename a\nfile when you copy it then you must explicitly indicate the target to be\na file using the `-f/--file` option, e.g.\n\n```\n$ mpr get file.py newfile.py\n\n# The above will fetch file.py to file.py/newfile.py which is not what\n# you want. Add -f switch to specify that the target is a file:\n\n$ mpr get -f file.py newfile.py\n```\n\nCommands `mkdir`, `rmdir`, and `rm` have a `-q/--quiet` option added to\nsuppress normal and error output. E.g. you could use this in a script to\nignore a `mkdir` error when the directory already exists.\n\nThe `fs` command is redundant in mpremote so is not implemented in mpr.\n\n`soft-reset` is implemented in mpr as `reset`. Hardware reset is\nimplemented in mpr as `reboot`. Mpr also adds global options to reset\n(`-x/--reset`) or reboot (`-b/--reboot`) after the specified command is\nrun.\n\nThe `cat` command is implemented differently. Instead type `mpr get\nfile.py -` to pipe a file to standard output.\n\nThe `disconnect`, `resume`, and `umount` commands are appropriate for\nuse with \"chained\" commands which are not relevant to mpr so are not\nimplemented.\n\nYou can not define shortcuts/macros with mpr, although all the standard\nmacros within mpremote are available in mpr. Of course you can create\nstandard shell based aliases and/or scripts invoking mpr if you want.\n\nThe `mip` command in mpremote currently only offers an `install`\nsub-command but `mpr` also offers a `list` sub-command which fetches all\npackage descriptions from micropython.org and then prints their names,\nversions, and descriptions.\n\n## Device Shortcut Names\n\n`mpremote` provides shortcut names, e.g:\n\n```\na0, a1, a2, a3 - connect to /dev/ttyACMn\nu0, u1, u2, u3 - connect to /dev/ttyUSBn\nc0, c1, c2, c3 - connect to COMn\n```\n\nHowever for mpremote this only works for those first 4 devices of each\ntype (as per this\n[bug](https://github.com/micropython/micropython/issues/11422)) so\ninstead `mpr` converts these shortcuts itself so you can use up to any\nnumber you want, e.g: `mpr -d u10 ls` is a shortcut for `mpr -d\n/dev/ttyUSB10 ls`.\n\nUse `mpr -d list` to remind yourself of device and shortcut names.\n\n## Recursive Deletion\n\n`mpremote` allows you to delete one or more specified files but does not\nprovide a mechanism to recursively delete a whole directory and it's\nfiles. Since this is commonly desired, `mpr` adds a `--rf` option to\nboth the `rm` and `rmdir` commands. The specified directory and it files\nare deleted recursively (although the top/root directory `/` is always\npreserved). Some examples:\n\n```\n# Remove all files and directories on the device (but preserve '/'):\n$ mpr rm --rf /\n\n# Remove /lib/ directory completely (including it's files/dirs):\n$ mpr rm --rf /lib\n\n# Remove the top level files but preserve any directories:\n$ mpr rm --rf --depth 1 /\n```\n\n## Remote Compilation and Development\n\n`mpremote` (and thus `mpr`) provides the `run` command to run a single\npython file on the connected device. However, this proves inadequate\nwhen developing any significant application which is comprised of\nmultiple files, and sometimes in various package directories. So `mpr`\nadds an `xrun` command (think extended `run`).\n\nRunning the `xrun` command in an application's directory runs that program and\ndisplays program output in your local terminal. In parallel, it waits watching\nfor edits/changes to Python source files in that directory tree on your host.\nWhen changes are detected then new `.mpy` bytecode files for changed files are\ncompiled using [`mpy-cross`][mpy-cross] in a hidden cache directory on your\nhost and then copied to the device. The specified program is then restarted and\nredisplayed in your local terminal. Command line arguments on the host can be\npassed to the program via `sys.argv` on the device. Only `.mpy` bytecode files\nare copied to the device, never `.py` source files, and the specified\n`prog[.py]` is imported to run as a `.mpy` file. So you run this utility in one\nterminal window while you edit your source files in other windows and your\nprogram will be automatically restarted and redisplayed each time you save your\nchanges. Since all bytecode compilation is done on your host, not on the remote\ndevice, your development workflow is faster to build, load, and run; and device\nmemory usage and fragmentation is significantly reduced.\n\nNote that `mpr` does not automatically create the required mirror of\ndirectories for your files on the device. You are expected to initially\ncreate/update these manually using the `mpr mkdir` and/or `mpr rmdir`\ncommands.\n\nNote that you can specify default options for the `xrun` command locally\nin your working directory in `mpr-xrun.conf`, or globally in\n`~/.config/mpr-xrun.conf`.\n\n## Default Options\n\nYou can set default global starting options for your user in\n`~/.config/mpr.conf`. E.g. use this to set a default\n`--path-to-mpremote` setting so it does not have to be specified each\ntime. Blank lines and anything after a `#` on any line is ignored.\n\nE.g. create `~/.config/mpr.conf` with contents:\n\n```\n--path-to-mpremote ~/.local/bin/mpremote\n```\n\nNow you need only specify the command, e.g. `mpr ls` and it will use\nthat specified `~/.local/bin/mpremote` program.\n\nYou can use the `mpr config` command to conveniently change this file\n(merely as a shortcut to explicitly specifying your editor and the path\nto the file). You can keep commented out configurations for a number of\ndifferent settings in your file (e.g. various `--device` and/or\n`--mount` options) and switch between them by un-commenting the lines\nyou want to use.\n\nNote that the `xrun` command can be independently set with it's own\ndefault options as described in the previous section.\n\n## Directory/Path Inference\n\nFor the following discussion, assume you have a project structured as\nfollows on your local machine and the same directory hierarchy is used\non your target device.\n\n```\n./\n├── file1.py\n├── file2.py\n└── mymodule/\n    ├── file3.py\n    ├── file4.py\n    └── templates/\n        ├── file5.tpl\n        └── file6.tpl\n```\n\nmpr automatically appends the target file name when appropriate, e.g.\nif you are sitting in the root of the above tree, you only need to type\n`mpr put file1.py /` instead of `mpr put file1.py /file1.py`. For this\nreason, you can copy multiple files with `mpr put file1.py file2.py /`\nor `mpr put *.py /`. Further to this, mpr can also infer the\nappropriate target directory as described next.\n\nIf you are currently sitting in the directory `mymodule/templates/` on\nyour local machine and you want to copy `file5.tpl` to the\n`/mymodule/templates/` on the target device then the command you would\nnaively use is:\n\n```\n$ mpr put file5.tpl /mymodule/templates\n```\n\nTo avoid this verbose typing, mpr allows you to instead use the\nfollowing shortcut because mpr can \"infer\" the full target path based on\nyour current local directory:\n\n```\n$ mpr put file5.tpl ///\n```\n\nTo then remove that same file from the target device:\n\n```\n$ mpr rm ///file5.tpl\n```\n\nI.e., mpr intercepts the two redundant lead slashes for the above two\ncases and automatically inserts the parent and current directory names\nin the path string (determined from the current directory on your local\nmachine). To be clear, if you are sitting one level above in the\n`mymodule` directory then the command to copy to that same directory on\nthe target device is:\n\n```\n$ mpr put file3.py //\n```\n\nYou can also use this shorthand for source files/dirs by inserting a\nsequence of leading slashes as a \"dummy\" argument. Once set, that dummy\nargument sets the default directory for the following arguments. E.g. if\nyou are sitting in the local `templates` directory then to delete all\nthe `*.tpl` files in the same directory on the target you can type:\n\n```\n$ mpr rm /// file5.tpl file6.tpl\n```\nor just:\n\n```\n$ mpr rm /// *.tpl\n```\n\nNote the 2nd \"trick\" above exploits the wildcard file list generated by\nyour shell to pass those local file names to the remote device. It\nassumes those same names exist in the analogous directory there (and\narguably this trick should be avoided!).\n\n## Path to mpremote\n\nMany using this program possibly also have downloaded the MicroPython\nsource tree for building firmware images. E.g. the source installed at\n`/opt/micropython/` also includes mpremote at\n`/opt/micropython/tools/mpremote/mpremote.py`. So for this reason mpr\ndoes not require mpremote to be explicitly installed as a formal\npackage.\n\nMpr first looks for a `mpremote` program in the same directory as it's\nown executable `mpr` self, otherwise mpr assumes `mpremote` is somewhere\nin your PATH (e.g. at `/usr/bin/mpremote`). Alternatively, you can\nspecify the option `--path-to-mpremote` to explicitly specify the path,\ne.g. if you have the MicroPython source installed somewhere then you\ndon't need to formally install mpremote and can instead just set e.g.\n`--path-to-mpremote /opt/micropython/tools/mpremote/mpremote.py` in your\n`~/.config/mpr.conf` as a [default option](#default-options) as\ndescribed in a previous [section](#default-options).\n\nNote, similar to above, you can also specify the path to the `mpy-cross`\nprogram using the `--path-to-mpy-cross` option.\n\n## Command Line Tab Completion\n\nCommand line shell [tab\ncompletion](https://en.wikipedia.org/wiki/Command-line_completion) is\nautomatically enabled on `mpr` commands and options using\n[`argcomplete`](https://github.com/kislyuk/argcomplete). You may need to\nfirst (once-only) [activate argcomplete global\ncompletion](https://github.com/kislyuk/argcomplete#global-completion).\n\n## Troubleshooting\n\nNote that mpr is essentially just a thin wrapper around mpremote and\nexists merely to provide a simpler, and hopefully more consistent and\nfamiliar command line interface, particularly for Linux shell command\nline users.\n\nThis means that most execution problems you may encounter will likely\ndue to mpremote, not mpr. So if you think your find a problem in mpr,\nalways run mpr with the `-v` option to see the command line being\nexecuted with mpremote. If that command line looks ok, but mpremote is\nnot doing what you expect, then run mpremote manually with those same\nmpremote options + arguments to prove to yourself that mpremote is\nexhibiting that issue, not mpr.\n\nIf you run mpr with the `-v` option and see a wrong or unexpected\nmpremote command being executed, then certainly raise an mpr [discussion\nthread](https://github.com/bulletmark/mpr/discussions), or\n[issue](https://github.com/bulletmark/mpr/issues) about that.\n\n## License\n\nCopyright (C) 2022 Mark Blakeney. This program is distributed under the\nterms of the GNU General Public License.\nThis program is free software: you can redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation, either version 3 of the License, or any later\nversion.\nThis program is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General\nPublic License at \u003chttp://www.gnu.org/licenses/\u003e for more details.\n\n[mpr]: https://github.com/bulletmark/mpr\n[upy]: https://micropython.org/\n[mpremote]: https://docs.micropython.org/en/latest/reference/mpremote.html\n[mpr-py]: https://pypi.org/project/mpr/\n[mpremote-py]: https://pypi.org/project/mpremote/\n[mpy-cross]: https://pypi.org/project/mpy-cross/\n[pipx]: https://github.com/pypa/pipx\n[pipxu]: https://github.com/bulletmark/pipxu\n[uvtool]: https://docs.astral.sh/uv/guides/tools/#installing-tools\n\n\u003c!-- vim: se ai syn=markdown: --\u003e\n","funding_links":[],"categories":["Development"],"sub_categories":["Shells"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbulletmark%2Fmpr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbulletmark%2Fmpr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbulletmark%2Fmpr/lists"}