MicroPython-Ctl: TypeScript ❤️ MicroPython
Talk to MicroPython devices from websites/webapps, Node.js programs, Electron applications, VS Code extensions, the terminal, and more.
Usage
const micropython = new MicroPythonDevice()
await micropython.connectNetwork('DEVICE_IP', 'WEBREPL_PASSWORD')
await micropython.connectSerial('/dev/ttyUSB0')
const output = await micropython.runScript('import os; print(os.listdir())')
console.log('runScript output:', output)
const files = await micropython.listFiles()
console.log('files:', files)
const fileContents = await micropython.getFile('boot.py')
console.log(fileContents)
micropython.onTerminalData = (data) => process.stdout.write(data)
micropython.sendData('\x03\x02')
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:
import { MicroPythonDevice } from 'micropython-ctl'
(async () => {
const micropython = new MicroPythonDevice()
await micropython.connectNetwork('YOUR_IP', 'WEBREPL_PASSWORD')
const output = await micropython.runScript('import os; print(os.listdir())')
console.log('runScript output:', output)
const files = await micropython.listFiles()
console.log('files:', files)
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
:
- ⚠ 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: