Nobody Pays (for) Magazines

    micropython-ctl
    TypeScript icon, indicating that this package has built-in type declarations

    1.13.4 • Public • Published

    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:

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

    Keywords

    none

    Install

    npm i micropython-ctl

    DownloadsWeekly Downloads

    27

    Version

    1.13.4

    License

    MIT

    Unpacked Size

    645 kB

    Total Files

    98

    Last publish

    Collaborators

    • metachris