npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

mctl

v1.13.7

Published

mctl: MicroPython-Ctl command line utility

Downloads

25

Readme

mctl: Command-line Interface for MicroPython Devices

  • Connect to devices over serial or network (WebREPL)
  • List all serial devices: mctl devices
  • Enter the REPL: mctl repl
  • Manipulate files and directories: mctl ls, mctl rm, mctl put, mctl get, mctl mkdir
  • Synchronize a folder onto the device: mctl sync (only uploads changed files)
  • Edit a file and upload if changed: mctl edit <filename>
  • Reset the device: mctl reset
  • Run Python scripts: mctl run <script_or_file>
  • Reuse a mctl repl connection to run mctl commands in another terminal at the same time
  • Mount the device into the local filesystem: mctl mount (experimental!)
  • More: see mctl help

Code: cli/index.ts

Installation

mctl is included in the micropython-ctl npm package. You can also install it via the mctl npm package:

npm install -g mctl

Usage

$ mctl help
Usage: index [options] [command]

Options:
  -t, --tty <device>                                      Connect over serial interface (eg. /dev/tty.SLAB_USBtoUART)
  -h, --host <host>                                       Connect over network to hostname or IP of device
  -p, --password <password>                               Password for network device
  -s, --silent                                            Hide unnecessary output
  --help                                                  display help for command

Commands:
  devices                                                 List serial devices
  repl                                                    Open a REPL terminal
  run <fileOrCommand>                                     Execute a Python file or command
  info [options]                                          Get information about the board (versions, unique id, space, memory)
  ls [options] [directory]                                List files on a device
  cat <filename>                                          Print content of a file on the device
  get <file_or_dirname> [out_file_or_dirname]             Download a file or directory from the device. Download everything with 'get /'
  put [options] <file_or_dirname> [dest_file_or_dirname]  Upload a file or directory onto the device
  sync [directory]                                        Sync a local directory onto the device root (upload new/changes files, delete missing)
  edit <filename>                                         Edit a file, and if changed upload afterwards
  mkdir <name>                                            Create a directory
  rm [options] <path>                                     Delete a file or directory
  mv <oldPath> <newPath>                                  Rename a file or directory
  sha256 <filename>                                       Get the SHA256 hash of a file
  reset [options]                                         Reset the MicroPython device
  mount [targetPath]                                      Mount a MicroPython device (over serial or network)
  run-tests                                               Run micropython-ctl tests on a device
  version                                                 Print the version of mctl
  help [command]                                          display help for command

Device connection logic:

  1. --host or --tty option
  2. MCTL_TTY env var: serial connection
  3. MCTL_HOST env var: network connection
  4. AMPY_PORT env var: serial connection
  5. WEBREPL_HOST env var: network connection

For network connection passwords, the env vars MCTL_PASSWORD and WEBREPL_PASSWORD can be used.

Examples

Set target device

# List serial devices
mctl devices

# By default connect to first serial device
mctl info

# Connect over specific serial device
mctl -t /dev/USB0 info

# Connect over network
mctl -h DEVICE_IP -p WEBREPL_PASSWORD info

Get information, REPL, list and read files

# Get information about the board
mctl info

# Enter the REPL
mctl repl

# List files
mctl ls  # list all files in /
mctl ls foo/  # list all files in /foo/
mctl ls -r  # recursively list all files and directories
mctl ls -r --json  # output as json
mctl ls -r --include-hash --json  # output as json, include sha256 hash of each file

# Print contents of boot.py
mctl cat boot.py

Upload and download files

# Download all files and directories recursively, into the current directory
mctl get /

# Download all files and directories recursively, into /tmp/
mctl get / /tmp/

# Upload a file
mctl put boot.py

# Upload all Python scripts
mctl put "*.py"

# Upload everything recursively
mctl put .

# Synchronize current local directory onto the device (upload only changed files, remove deleted files)
mctl sync

# Synchronize specific current local directory onto the device
mctl sync <directory>

# Edit a file and upload only if changed
mctl edit boot.py

Example Output

ls -r --json --include-hash:

[
    {
        "filename": "/",
        "size": 0,
        "isDir": true,
        "mTime": 0
    },
    {
        "filename": "/boot.py",
        "size": 139,
        "isDir": false,
        "mTime": 0,
        "sha256": "16f5b4bcb120e9a032242b47967e649a0cc577b41939e81ef7d4b4da181bd17f"
    },
    {
        "filename": "/main.py",
        "size": 1810,
        "isDir": false,
        "mTime": 14,
        "sha256": "936d92994d0b86eb0e60efd053e12d009d718af3894d7f5c16303b1d7c526306"
    }
]

Experimental

# Mount device onto local filesystem (experimental, only works with python files)
mctl mount

Notes

mctl mount

  • Mounts the device filesystem into the local filesystem. Highly experimental! Doesn't yet work well with binary files, and Windows. Not recommended for production use. Might result in data loss.
  • Should work for Python (.py) files on macOS and Linux.
  • macOS, Linux: works, using fuse-native
  • Windows: experimental, might be buggy. Uses node-fuse-bindings and Dokany
  • Keeps the device connection open, which means you cannot connect to it in parallel
  • If you encounter problems or have feedback, please post here: https://github.com/metachris/micropython-ctl/issues/3