/micropython-ctl

TypeScript library for talking to MicroPython devices from websites/webapps, Node.js and Electron apps

Primary LanguageTypeScriptMIT LicenseMIT

MicroPython-Ctl: TypeScript ❤️ MicroPython

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

Build and test status

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:

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:

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

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:

Inspiration & References

Future work

Code library:

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):

Notes: