{"id":13500238,"url":"https://github.com/wendlers/mpfshell","last_synced_at":"2025-05-15T01:05:29.019Z","repository":{"id":49471988,"uuid":"54068794","full_name":"wendlers/mpfshell","owner":"wendlers","description":"A simple shell based file explorer for ESP8266 Micropython based devices ⛺","archived":false,"fork":false,"pushed_at":"2025-01-09T14:53:46.000Z","size":254,"stargazers_count":407,"open_issues_count":27,"forks_count":87,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-04-13T22:39:25.209Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wendlers.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2016-03-16T21:47:01.000Z","updated_at":"2025-02-10T07:31:00.000Z","dependencies_parsed_at":"2025-02-08T05:12:57.568Z","dependency_job_id":null,"html_url":"https://github.com/wendlers/mpfshell","commit_stats":{"total_commits":146,"total_committers":25,"mean_commits":5.84,"dds":0.4452054794520548,"last_synced_commit":"b4e47ffa9bbf0dcbbff4c498361f6169d670da49"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wendlers%2Fmpfshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wendlers%2Fmpfshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wendlers%2Fmpfshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wendlers%2Fmpfshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wendlers","download_url":"https://codeload.github.com/wendlers/mpfshell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254254039,"owners_count":22039792,"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":[],"created_at":"2024-07-31T22:00:53.954Z","updated_at":"2025-05-15T01:05:29.003Z","avatar_url":"https://github.com/wendlers.png","language":"Python","readme":"# mpfshell\n\n[![](https://www.codeshelter.co/static/badges/badge-plastic.9800c3f706ba.svg)](https://www.codeshelter.co/)\n\n[![PyPI version](https://badge.fury.io/py/mpfshell.svg)](https://badge.fury.io/py/mpfshell)\n\n2016-06-21, sw@kaltpost.de\n\nA simple shell based file explorer for ESP8266 and WiPy\n[Micropython](https://github.com/micropython/micropython) based devices.\n\nThe shell is a helper for up/downloading files to the ESP8266 (over serial line and Websockets)\nand WiPy (serial line and telnet). It basically offers commands to list and upload/download\nfiles on the flash FS of the device.\n\n![mpfshell](./doc/screenshot.png)\n\nMain features:\n\n* Support for serial connections (ESP8266 and WiPy)\n* Support for websockets (via WebREPL) connections (ESP8266 only)\n* Support for telnet connections (WiPy only)\n* Full directory handling (enter, create, remove)\n* Transfer (upload/download) of multiple files matching a reg.-exp.\n* All files are transferred in binary mode, and thus it should be\n  possible to also upload pre-compiled code (.mpy) too.\n* You can compile and upload files with one command.\n* Integrated REPL (supporting a workflow like: upload changed files, enter REPL, test, exit REPL, upload ...)\n* Fully scriptable\n* Tab-completion\n* Command history\n* Best of all: it comes with color\n\n\n__Note__: The software is mainly tested on Ubuntu 16.04 LTS. However, there is basic Windows support\n(tested with Python 3.5 and PySerial 3.1), but some of the keys (e.g. Tab) are note working as\nexpected yet.\n\n## Requirements\n\nGeneral:\n\n* ESP8266 or WiPy board running latest [Micropython](https://github.com/micropython/micropython)\n* For the ESP8266 firmware build from the repository, please note, that WebREPL is not started\n  by default. For more information see the [quickstart](http://micropython.org/resources/docs/en/latest/esp8266/esp8266/quickref.html#webrepl-web-browser-interactive-prompt).\n* For the WiPy, please note, that you need to enable REPL on UART if you intend to connect\n  via serial line to the WiPy (see [here](http://micropython.org/resources/docs/en/latest/wipy/wipy/tutorial/repl.html))\n\nFor the shell:\n\n* Python \u003e= 2.7 or Python \u003e= 3.4\n* The PySerial, colorama, and websocket-client packages (`pip install -r requirements.txt`)\n\n__IMPORTANT__: It is highly recommended to use PySerial version 3.x on Python 2 and 3.\n\n__Note__: The tools only work if the REPL is accessible on the device!\n\n## Installing\n\n### From PyPi\n\nTo install the latest release from PyPi:\n\n    sudo pip install mpfshell\n\n### From Source\n\nClone this repository:\n\n    git clone https://github.com/wendlers/mpfshell\n\nTo install for __Python 2__, execute the following:\n\n    sudo pip install -r requirements.txt\n    sudo python setup.py install\n\nTo install for __Python 3__, execute the following:\n\n\tsudo pip3 install -r requirements.txt\n    sudo python3 setup.py install\n\n## Known Issues\n\n* For PySerial 2.6 the REPL is deactivated since Miniterm (which comes with 2.6)\n    seems broken.\n\n## General\n\n### TAB Completion\n\nThe shell supports TAB completion for commands and file names.\nSo it's totally worth pressing TAB-TAB every now and then :-)\n\n### File/Directory Names\n\nFile names including whitespaces are supported, but such names need to be enclosed\nin quotes. E.g. accessing a file named \"with white space.txt\" needs to quoted:\n\n    get \"with white space.txt\"\n    put \"with white space.txt\" without-white-space.txt\n    put without-white-space.txt \"with white space.txt\"\n\nThe following characters are accepted for file and directory names:\n\n    A-Za-z0-9 _%#~@/\\$!\\*\\.\\+\\-\n\n## Shell Usage\n\n__Note:__ Since version 0.7.1, the shell offers caching for file and\ndirectory names. It is now enabled by default. To disable caching,\nadd the `--nocache` flag on the command line.\n\nStart the shell with:\n\n    mpfshell\n\nAt the shell prompt, first connect to the device. E.g. to connect\nvia serial line:\n\n    mpfs\u003e open ttyUSB0\n\nOr connect via websocket (ESP8266 only) with the password \"python\":\n\n    mpfs\u003e open ws:192.168.1.1,python\n\nOr connect vial telnet (WiPy only) with username \"micro\" and password \"python\":\n\n    mpfs\u003e open tn:192.168.1.1,micro,python\n\n__Note__: Login and password are optional. If left out, they will be asked for.\n\nNow you can list the files on the device with:\n\n    mpfs\u003e ls\n\nTo upload e.g. the local file \"boot.py\" to the device use:\n\n    mpfs\u003e put boot.py\n\nIf you like to use a different filename on the device, you could use this:\n\n    mpfs\u003e put boot.py main.py\n\nTo compile before uploading and upload the compiled file (you need mpy-cross in your path):\n\n    mpfs \u003e putc boot.py\n\nOr to upload all files that match a regular expression from the\ncurrent local directory to the current remote directory:\n\n    mpfs\u003e mput .*\\.py\n\nAnd to download e.g. the file \"boot.py\" from the device use:\n\n    mpfs\u003e get boot.py\n\nUsing a different local file name:\n\n    mpfs\u003e get boot.py my_boot.py\n\nOr to download all files that match a regular expression from the\ncurrent remote directory to the current local directory:\n\n    mpfs\u003e mget .*\\.py\n\nTo remove a file (or directory) on the device use:\n\n    mpfs\u003e rm boot.py\n\nOr remove all remote files that match a regular expression:\n\n    mpfs\u003e mrm test.*\\.py\n\nTo create a new remote directory:\n\n    mpfs\u003e md test\n\nTo navigate remote directories:\n\n    mpfs\u003e cd test\n    mpfs\u003e cd ..\n    mpfs\u003e cd /some/full/path\n\nSee which is the current remote directory:\n\n    mpfs\u003e pwd\n\nRemove a remote directory:\n\n    mpfs\u003e rm test\n\n__Note__: The directory to delete needs to be empty!\n\nTo navigate on the local filesystem, use:\n\n    lls, lcd lpwd\n\nEnter REPL:\n\n    repl\n\nTo exit REPL and return to the file shell use Ctrl+]\n\nFor a full list of commands use:\n\n    mpfs\u003e help\n    mpfs\u003e help \u003ccommand\u003e\n\nThe shell is also scriptable.\n\nE.g. to execute a command, and then enter the shell:\n\n    mpfshell -c \"open ttyUSB0\"\n\nOr to copy the file \"boot.py\" to the device, and don't enter the shell at all:\n\n    mpfshell -n -c \"open ttyUSB0; put boot.py\"\n\nIt is also possible to put a bunch of shell commands in a file, and then execute\nthem from that file.\n\nE.g. creating a file called \"myscript.mpf\":\n\n    open ttyUSB0\n    put boot.py\n    put main.py\n    ls\n\nAnd execute it with:\n\n    mpfshell -s myscript.mpf\n\n\n## Running the Shell in a Virtual Environment\n\nSomtimes the easiest way to satisfy the requirements is to setup a virtual environment. \nE.g. on Debian Jessie (which still has PySerial 2.6), this could be\ndone like so (assuming you are within the `mpfshell` base directory):\n\nInstall support for virtual environments:\n\n    sudo apt-get install python3-venv\n\nCreate a new virtual environment:\n\n    pyvenv venv\n\nOr you could use `python3 -m virtualenv venv` instead of `pyvenv`.\n\nActivate it (so every following `pip install` goes to the new virtual environment):\n\n    source venv/bin/activate\n\nNow install the dependencies to the virtual environment:\n\n    pip install -r requirements.txt\n    python setup.py install\n\nNow run the shell with the following command:\n\n    python -m mp.mpfshell\n\n__Note:__ The environment always has to be activated with the above command before using it.\n","funding_links":[],"categories":["Python","Util","Development"],"sub_categories":["Shells"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwendlers%2Fmpfshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwendlers%2Fmpfshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwendlers%2Fmpfshell/lists"}