MicroPython-Ctl: TypeScript ❤️ MicroPython

Talk to MicroPython devices from websites/webapps, Node.js programs, Electron applications, VS Code extensions, the terminal, and more.

• Modern TypeScript library and command-line interface
• Connect to devices over serial and network (REPL and WebREPL)
• Functionality:
  • Run Python scripts, await the output
  • Manipulate files and directories
  • Terminal (REPL) interaction
  • mctl command line utility
• See all the features in the documentation, examples and cli/
• Typed and fully async (use await with any command).
• Works on Linux, macOS and Windows. Tested with ESP32, ESP8266, Raspberry Pi Pico
• Main code files: main.ts, cli/index.ts
• Links: Github, Documentation, npm package

Usage

const micropython = new MicroPythonDevice()

// Connect to micropython device over network
await micropython.connectNetwork('DEVICE_IP', 'WEBREPL_PASSWORD')

// Or connect to micropython device over serial interface
await micropython.connectSerial('/dev/ttyUSB0')

// Run a Python script and capture the output
const output = await micropython.runScript('import os; print(os.listdir())')
console.log('runScript output:', output)

// List all files in the root
const files = await micropython.listFiles()
console.log('files:', files)

// Get file contents
const fileContents = await micropython.getFile('boot.py')
console.log(fileContents)

// Set a terminal (REPL) data handler, and send data to the REPL
micropython.onTerminalData = (data) => process.stdout.write(data)
micropython.sendData('\x03\x02')  // Ctrl+C and Ctrl+B to enter friendly repl and print version

See also: MicroPythonDevice docs

Note: to connect over the network, you need to enable it on the device first, through the serial REPL: import webrepl_setup (see docs). Also, make sure you can ping the device first.

Code examples:

• examples/basic.ts (run with yarn ts-node examples/basic.ts)
• examples/web-example.html (open the file in a browser, or view it live here)
• examples/web-example2-terminal.html (open the file in a browser, or view it live here)
• examples/terminal.ts (run with yarn ts-node examples/terminal.ts)
• cli/index.ts (run with yarn mctl)

Browser / Webapps

In websites/webapps, simply include the latest release via CDN (~13kb gzipped):

<script src="https://cdn.jsdelivr.net/npm/micropython-ctl@1.10.0/dist-browser/main.js"></script>

Then you can use it like this:

const micropython = new MicroPythonCtl.MicroPythonDevice()
await micropython.connectNetwork(host, password)

Usage example:

• examples/web-example.html - live here
• examples/web-example2-terminal.html - live here

Notes:

• Browsers don't allow access to USB/serial ports.
• You can enable debug output by opening the console and entering window.DEBUG = 1
• You can download the zipped bundle here: main.js.gz

Node.js

Installation:

# If you use yarn
yarn add micropython-ctl

# Alternatively, if you use npm
npm install micropython-ctl

Usage:

// Node.js with TypeScript:
import { MicroPythonDevice } from 'micropython-ctl'

// Node.js without TypeScript:
// const MicroPythonDevice = require('micropython-ctl').MicroPythonDevice

(async () => {
  const micropython = new MicroPythonDevice()

  // Connect to micropython device
  await micropython.connectNetwork('YOUR_IP', 'WEBREPL_PASSWORD')
  // await micropython.connectSerial('/dev/ttyUSB0')

  // Run a Python script and capture the output
  const output = await micropython.runScript('import os; print(os.listdir())')
  console.log('runScript output:', output)

  // List all files in the root
  const files = await micropython.listFiles()
  console.log('files:', files)

  // Close
  await micropython.close()
})()

Examples

Find more examples in /examples/. You can run them like this: yarn ts-node examples/basic.ts

• examples/basic.ts (run with yarn ts-node examples/basic.ts)
• examples/web-example.html (open the file in a browser, or view it live here)
• examples/web-example2-terminal.html (open the file in a browser, or view it live here)
• examples/terminal.ts (run with yarn ts-node examples/terminal.ts)
• cli/index.ts (run with yarn mctl)

Building the code

$ git clone https://github.com/metachris/micropython-ctl.git
$ cd micropython-ctl
$ yarn
$ yarn build
$ yarn lint
$ yarn doc

# Compile and run mctl
$ yarn mctl

# Run a TypeScript example
$ yarn ts-node examples/basic.ts

# Run the test suite (needs a micropython device)
$ yarn test --help

# Experimental: build with esbuild
$ yarn esbuild

---

Enjoy and do cool things with this code! 🚀

---

Reach out

I'm happy about feedback, please reach out:

• chris@linuxuser.at
• https://twitter.com/metachris

Inspiration & References

• https://github.com/micropython/webrepl (original JS implementation)
• https://github.com/scientifichackers/ampy/blob/master/ampy/files.py
• https://github.com/dhylands/rshell#commands
• https://pycopy.readthedocs.io/en/latest/esp32/quickref.html
• https://github.com/micropython/micropython/pull/6375/files (mpr: fs mount PR)

Future work

Code library:

• Benchmark putFile vs. ampy, rshell, webrepl, pymakr
• 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)
• WebSerial integration, to allow browser version to connect to serial (see MDN docs)
• 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
• put/get
  • via network: switch to webrepl protocol instead of manual up- and download
  • getFile via serial improvement - currently it fills the device RAM and probably works badly with large file
• More examples in the documentation (in main.ts)

mctl:

• mctl reset error: Error: timeout in readUntil '>>>'
• ⚠ Check for issues when alternating mctl and pymakr
• flash-erase, flash-backup, flash-restore
• get with wildcards: get '*.py'
• wifi status, connect, disconnect
• device aliases (like here)

Tests:

• getFileHash, isFileTheSame, listFiles with and without hash
• Tests for mctl commands: get -r ., put -r ., ..
• automated browser testing (selenium [1])
• Run tests against a local micropython instance in CI (eg by using utelnetserver to connect serial-like (webrepl is not available in host builds))

Various:

• Webapp examples: drag & drop files to upload
• Electron example app
• Vue.js example with hot-reload

Maybe (not sure it's needed, don't rush into implementing):

• A slim version for the browser with minimal footprint (only core code, no listfiles etc.)
• mount related: testing, mount + repl, enable proxy webserver

---

Release process

Testing

• Run the tests with a Device: yarn test
• Test package installation:
  • Prepare: yarn build && yarn pack
  • macOS & Linux: run tests/test-package-installation.sh
  • Windows: run E:/tests/test-package-installation.bat
• Test web examples: In the html files, change imports to local and open in Browser

Release

# Update CHANGELOG
code CHANGELOG.md

# Update cli README
yarn mctl help
code cli/README.md

# make sure all is committed in git
git status

# update version number and create a git tag
yarn version

# create the builds for node and browser
./build.sh

# check the final package
yarn pack && tar -xvf micropython-ctl-v* && ll package/
rm -rf package/ micropython-ctl-v*

# publish 'latest'
yarn publish

# or publish 'beta'
yarn publish --tag beta

# push to git
git push && git push --tags

Perhaps update the mctl npm package too (using cli/package.json).

Update live web examples with code from Github master branch:

ssh nova "cd /server/websites/current.at/micropython-ctl && git pull"

Test the live web examples with Chrome, Firefox, Safari, Edge (on OSX, Linux, Windows and Mobile):

• web-example.html
• web-example2-terminal.html

Notes:

• Help for writing release notes: https://github.com/metachris/micropython-ctl/compare
• Purge CDN cache: https://purge.jsdelivr.net/npm/micropython-ctl@latest