{"id":15061545,"url":"https://github.com/metachris/micropython-ctl","last_synced_at":"2025-08-23T19:46:44.840Z","repository":{"id":44619593,"uuid":"324833077","full_name":"metachris/micropython-ctl","owner":"metachris","description":"TypeScript library for talking to MicroPython devices from websites/webapps, Node.js and Electron apps","archived":false,"fork":false,"pushed_at":"2022-03-28T09:07:12.000Z","size":1292,"stargazers_count":29,"open_issues_count":8,"forks_count":9,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-05-01T12:17:05.631Z","etag":null,"topics":["micropython","typescript","webrepl"],"latest_commit_sha":null,"homepage":"https://metachris.github.io/micropython-ctl/","language":"TypeScript","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/metachris.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}},"created_at":"2020-12-27T19:25:02.000Z","updated_at":"2024-04-01T18:07:04.000Z","dependencies_parsed_at":"2022-08-27T12:21:26.516Z","dependency_job_id":null,"html_url":"https://github.com/metachris/micropython-ctl","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metachris%2Fmicropython-ctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metachris%2Fmicropython-ctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metachris%2Fmicropython-ctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metachris%2Fmicropython-ctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metachris","download_url":"https://codeload.github.com/metachris/micropython-ctl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247645340,"owners_count":20972456,"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":["micropython","typescript","webrepl"],"created_at":"2024-09-24T23:21:10.990Z","updated_at":"2025-04-10T08:58:54.328Z","avatar_url":"https://github.com/metachris.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MicroPython-Ctl: TypeScript ❤️ MicroPython\n\nTalk to MicroPython devices from websites/webapps, Node.js programs, Electron applications, VS Code extensions, the terminal, and more.\n\n[![Build and test status](https://github.com/metachris/micropython-ctl/workflows/Build%20and%20test/badge.svg)](https://github.com/metachris/micropython-ctl/actions?query=workflow%3A%22Build+and+test%22)\n\n* Modern TypeScript library and [command-line interface](https://github.com/metachris/micropython-ctl/blob/master/cli)\n* Connect to devices over serial and network (REPL and WebREPL)\n* Functionality:\n  * Run Python scripts, await the output\n  * Manipulate files and directories\n  * Terminal (REPL) interaction\n  * [`mctl` command line utility](https://github.com/metachris/micropython-ctl/blob/master/cli)\n* See all the features in the [documentation](https://metachris.github.io/micropython-ctl/classes/micropythondevice.html), [examples](https://github.com/metachris/micropython-ctl/tree/master/examples) and [`cli/`](https://github.com/metachris/micropython-ctl/blob/master/cli)\n* Typed and fully async (use `await` with any command).\n* Works on Linux, macOS and Windows. Tested with ESP32, ESP8266, [Raspberry Pi Pico](https://www.raspberrypi.org/documentation/pico/getting-started/)\n* Main code files: [`main.ts`](https://github.com/metachris/micropython-ctl/blob/master/src/main.ts), [`cli/index.ts`](https://github.com/metachris/micropython-ctl/blob/master/cli/index.ts)\n* Links: [Github](https://github.com/metachris/micropython-ctl), [Documentation](https://metachris.github.io/micropython-ctl/), [npm package](https://www.npmjs.com/package/micropython-ctl)\n\n\n# Usage\n\n```js\nconst micropython = new MicroPythonDevice()\n\n// Connect to micropython device over network\nawait micropython.connectNetwork('DEVICE_IP', 'WEBREPL_PASSWORD')\n\n// Or connect to micropython device over serial interface\nawait micropython.connectSerial('/dev/ttyUSB0')\n\n// Run a Python script and capture the output\nconst output = await micropython.runScript('import os; print(os.listdir())')\nconsole.log('runScript output:', output)\n\n// List all files in the root\nconst files = await micropython.listFiles()\nconsole.log('files:', files)\n\n// Get file contents\nconst fileContents = await micropython.getFile('boot.py')\nconsole.log(fileContents)\n\n// Set a terminal (REPL) data handler, and send data to the REPL\nmicropython.onTerminalData = (data) =\u003e process.stdout.write(data)\nmicropython.sendData('\\x03\\x02')  // Ctrl+C and Ctrl+B to enter friendly repl and print version\n```\n\nSee also: [MicroPythonDevice docs](https://metachris.github.io/micropython-ctl/classes/micropythondevice.html)\n\nNote: to connect over the network, you need to enable it on the device first, through the serial REPL: `import webrepl_setup` (see [docs](https://docs.micropython.org/en/latest/esp8266/tutorial/repl.html#webrepl-a-prompt-over-wifi)). Also, make sure you can ping the device first.\n\n\n**Code examples:**\n\n* [examples/basic.ts](https://github.com/metachris/micropython-ctl/blob/master/examples/basic.ts) (run with `yarn ts-node examples/basic.ts`)\n* [examples/web-example.html](https://github.com/metachris/micropython-ctl/blob/master/examples/web-example.html) (open the file in a browser, or view it [live here](http://current.at/micropython-ctl/examples/web-example.html))\n* [examples/web-example2-terminal.html](https://github.com/metachris/micropython-ctl/blob/master/examples/web-example2-terminal.html) (open the file in a browser, or view it [live here](http://current.at/micropython-ctl/examples/web-example2-terminal.html))\n* [examples/terminal.ts](https://github.com/metachris/micropython-ctl/blob/master/examples/terminal.ts) (run with `yarn ts-node examples/terminal.ts`)\n* [cli/index.ts](https://github.com/metachris/micropython-ctl/blob/master/cli/index.ts) (run with `yarn mctl`)\n\n## Browser / Webapps\n\nIn websites/webapps, simply include the latest release via CDN (~13kb gzipped):\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/micropython-ctl@1.10.0/dist-browser/main.js\"\u003e\u003c/script\u003e\n```\n\nThen you can use it like this:\n\n```js\nconst micropython = new MicroPythonCtl.MicroPythonDevice()\nawait micropython.connectNetwork(host, password)\n```\n\n**Usage example:**\n\n* [examples/web-example.html](https://github.com/metachris/micropython-ctl/blob/master/examples/web-example.html#L89-L113) - [live here](http://current.at/micropython-ctl/examples/web-example.html)\n* [examples/web-example2-terminal.html](https://github.com/metachris/micropython-ctl/blob/master/examples/web-example2-terminal.html#L112-L130) - [live here](http://current.at/micropython-ctl/examples/web-example2-terminal.html)\n\n**Notes:**\n\n* Browsers don't allow access to USB/serial ports.\n* You can enable debug output by opening the console and entering `window.DEBUG = 1`\n* You can download the zipped bundle here: [main.js.gz](https://cdn.jsdelivr.net/npm/micropython-ctl@1.5.2/dist-browser/main.js.gz)\n\n## Node.js\n\nInstallation:\n\n```shell\n# If you use yarn\nyarn add micropython-ctl\n\n# Alternatively, if you use npm\nnpm install micropython-ctl\n```\n\nUsage:\n\n```js\n// Node.js with TypeScript:\nimport { MicroPythonDevice } from 'micropython-ctl'\n\n// Node.js without TypeScript:\n// const MicroPythonDevice = require('micropython-ctl').MicroPythonDevice\n\n(async () =\u003e {\n  const micropython = new MicroPythonDevice()\n\n  // Connect to micropython device\n  await micropython.connectNetwork('YOUR_IP', 'WEBREPL_PASSWORD')\n  // await micropython.connectSerial('/dev/ttyUSB0')\n\n  // Run a Python script and capture the output\n  const output = await micropython.runScript('import os; print(os.listdir())')\n  console.log('runScript output:', output)\n\n  // List all files in the root\n  const files = await micropython.listFiles()\n  console.log('files:', files)\n\n  // Close\n  await micropython.close()\n})()\n```\n\n## Examples\n\nFind more examples in [`/examples/`](https://github.com/metachris/micropython-ctl/tree/master/examples). You can run them like this: `yarn ts-node examples/basic.ts`\n\n* [examples/basic.ts](https://github.com/metachris/micropython-ctl/blob/master/examples/basic.ts) (run with `yarn ts-node examples/basic.ts`)\n* [examples/web-example.html](https://github.com/metachris/micropython-ctl/blob/master/examples/web-example.html) (open the file in a browser, or view it [live here](http://current.at/micropython-ctl/examples/web-example.html))\n* [examples/web-example2-terminal.html](https://github.com/metachris/micropython-ctl/blob/master/examples/web-example2-terminal.html) (open the file in a browser, or view it [live here](http://current.at/micropython-ctl/examples/web-example2-terminal.html))\n* [examples/terminal.ts](https://github.com/metachris/micropython-ctl/blob/master/examples/terminal.ts) (run with `yarn ts-node examples/terminal.ts`)\n* [cli/index.ts](https://github.com/metachris/micropython-ctl/blob/master/cli/index.ts) (run with `yarn mctl`)\n\n\n## Building the code\n\n```shell\n$ git clone https://github.com/metachris/micropython-ctl.git\n$ cd micropython-ctl\n$ yarn\n$ yarn build\n$ yarn lint\n$ yarn doc\n\n# Compile and run mctl\n$ yarn mctl\n\n# Run a TypeScript example\n$ yarn ts-node examples/basic.ts\n\n# Run the test suite (needs a micropython device)\n$ yarn test --help\n\n# Experimental: build with esbuild\n$ yarn esbuild\n```\n\n---\n\nEnjoy and do cool things with this code! 🚀\n\n---\n\n## Reach out\n\nI'm happy about feedback, please reach out:\n\n* chris@linuxuser.at\n* https://twitter.com/metachris\n\n\n## Inspiration \u0026 References\n\n* https://github.com/micropython/webrepl ([original JS implementation](https://github.com/micropython/webrepl/blob/master/webrepl.html))\n* https://github.com/scientifichackers/ampy/blob/master/ampy/files.py\n* https://github.com/dhylands/rshell#commands\n* https://pycopy.readthedocs.io/en/latest/esp32/quickref.html\n* https://github.com/micropython/micropython/pull/6375/files (mpr: fs mount PR)\n\n\n## Future work\n\nCode library:\n\n* Benchmark putFile vs. ampy, rshell, webrepl, pymakr\n* Support new raw-paste mode: https://github.com/micropython/micropython/blob/master/docs/reference/repl.rst#raw-mode-and-raw-paste-mode (only in master, should be part of MicroPython 1.14)\n* [WebSerial](https://web.dev/serial/) integration, to allow browser version to connect to serial (see [MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/serial))\n* Improve webserver/node-fetch import (currently require in try..catch to not fail in browser): https://github.com/metachris/micropython-ctl/blob/proxy-mode/src/main.ts#L17\n* put/get\n  * via network: switch to webrepl protocol instead of manual up- and download\n  * `getFile` via serial improvement - currently it fills the device RAM and probably works badly with large file\n* More examples in the documentation (in [main.ts](https://github.com/metachris/micropython-ctl/blob/master/src/main.ts))\n\n`mctl`:\n\n* `mctl reset` error: `Error: timeout in readUntil '\u003e\u003e\u003e'`\n* ⚠ Check for issues when alternating `mctl` and pymakr\n* flash-erase, flash-backup, flash-restore\n* `get` with wildcards: `get '*.py'`\n* wifi status, connect, disconnect\n* device aliases ([like here](https://github.com/micropython/micropython/pull/6375/files#diff-abc52a08e256524f287eeb9711417e389265743c68c47cb8badc575f0aebfd02R69))\n\nTests:\n\n* `getFileHash`, `isFileTheSame`, `listFiles` with and without hash\n* Tests for `mctl` commands: `get -r .`, `put -r .`, ..\n* automated browser testing (selenium [[1](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Cross_browser_testing/Your_own_automation_environment)])\n* Run tests against a local micropython instance in CI (eg by using [utelnetserver](https://github.com/cpopp/MicroTelnetServer) to connect serial-like (webrepl is not available in host builds))\n\nVarious:\n\n* Webapp examples: drag \u0026 drop files to upload\n* Electron example app\n* Vue.js example with hot-reload\n\nMaybe (not sure it's needed, don't rush into implementing):\n\n* A slim version for the browser with minimal footprint (only core code, no listfiles etc.)\n* mount related: testing, mount + repl, enable proxy webserver\n\n---\n\n## Release process\n\n#### Testing\n\n- Run the tests with a Device: `yarn test`\n- Test package installation:\n  - Prepare: `yarn build \u0026\u0026 yarn pack`\n  - macOS \u0026 Linux: run `tests/test-package-installation.sh`\n  - Windows: run `E:/tests/test-package-installation.bat`\n- Test web examples: In the html files, change imports to local and open in Browser\n\n#### Release\n\n```shell\n# Update CHANGELOG\ncode CHANGELOG.md\n\n# Update cli README\nyarn mctl help\ncode cli/README.md\n\n# make sure all is committed in git\ngit status\n\n# update version number and create a git tag\nyarn version\n\n# create the builds for node and browser\n./build.sh\n\n# check the final package\nyarn pack \u0026\u0026 tar -xvf micropython-ctl-v* \u0026\u0026 ll package/\nrm -rf package/ micropython-ctl-v*\n\n# publish 'latest'\nyarn publish\n\n# or publish 'beta'\nyarn publish --tag beta\n\n# push to git\ngit push \u0026\u0026 git push --tags\n```\n\nPerhaps update the `mctl` npm package too (using `cli/package.json`).\n\nUpdate live web examples with code from Github `master` branch:\n\n```\nssh nova \"cd /server/websites/current.at/micropython-ctl \u0026\u0026 git pull\"\n```\n\nTest the live web examples with Chrome, Firefox, Safari, Edge (on OSX, Linux, Windows and Mobile):\n\n* [web-example.html](http://current.at/micropython-ctl/examples/web-example.html)\n* [web-example2-terminal.html](http://current.at/micropython-ctl/examples/web-example2-terminal.html)\n\n\nNotes:\n\n* Help for writing release notes: https://github.com/metachris/micropython-ctl/compare\n* Purge CDN cache: https://purge.jsdelivr.net/npm/micropython-ctl@latest\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetachris%2Fmicropython-ctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetachris%2Fmicropython-ctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetachris%2Fmicropython-ctl/lists"}