Install packages

mcuctl installs with mip on MicroPython and circup on CircuitPython, chosen by the interpreter it detected.

mcuctl mip github:org/repo                  # MicroPython; installs to /lib by default
mcuctl mip NAME --index https://lib.omnipython.org
mcuctl omip NAME                            # MicroPython; an OmniPython package and what it needs
mcuctl circup adafruit_display_text         # CircuitPython; installs to /lib

In the editor and the browser interface, mcuctl: Install Package asks whether to use omip or mip on MicroPython, then for the name; on CircuitPython it runs circup.

Install an OmniPython package

mcuctl omip NAME looks on the OmniPython index and then on micropython-lib, and brings what the package names from micropython-lib as well. mip can’t do that: it takes every file from the one index it was given, so mcuctl mip keeps doing what mip does. The computer does the fetching, so the board needs no network.

mcuctl omip palettes
mcuctl omip fnmatch --no-mpy --target /flash/lib

An app package names its own folder in its package.json, as Home does with "target": "apps/home". That folder goes beside a --target named lib and inside any other, and what the app needs goes in a lib folder: --target /flash puts Home in /flash/apps/home and its libraries in /flash/lib, the same places omip.install on the board puts them.

Everything is downloaded before the first file is written, so a package that can’t be found leaves the board as it was. --index looks for the package on that index alone; what it needs from micropython-lib still comes from there.

To let the board install for itself, put omip.py on it:

mcuctl omip --self

Then, on the board, with Wi-Fi:

import omip
omip.install("palettes")

mcuctl omip --self works on CircuitPython too, through the drive when it is mounted. Naming a package there is refused: on CircuitPython, install from the computer with mcuctl circup.

Find a package

If you don’t know the exact name, search by words from its name or description:

mcuctl search display text --text

The first hit looks like this:

adafruit_display_text 5.0.6  [Adafruit CircuitPython Bundle] — Displays text using CircuitPython's displayio.
    mcuctl circup adafruit_display_text

Search needs no board. It covers micropython-lib, the OmniPython index and the CircuitPython bundles (Adafruit and community); with a board connected it keeps to the indexes that board installs from. In the editor it is mcuctl: Search Packages…, and also in the ⋯ menu of the File Transfer view and the browser interface. An OmniPython package installs with mcuctl omip. A package on both indexes is listed from each, with its own version.

Without --text the answer is JSON: each result has name, source, version, description and an install with the command to run. Pass --interpreter to keep to what one interpreter can install, --source to search one index and --limit to change the 25 results it shows. The indexes are cached for six hours under ~/.mcuctl/package-cache; --refresh fetches them again, and with no network the search runs on the cached copies and says so.

How CircuitPython installs

mcuctl circup picks the fastest route available:

  1. With CIRCUITPY mounted, circup --path writes to the drive.

  2. Otherwise, if Wi-Fi is up and /settings.toml holds CIRCUITPY_WIFI_* and CIRCUITPY_WEB_API_PASSWORD, and the filesystem is writable over the web workflow, circup --host installs over Wi-Fi. While USB storage is enabled, CircuitPython keeps the filesystem read-only to the board, so the host “Eject” button isn’t enough; use the mounted drive, or call storage.disable_usb_drive() in boot.py if you want the web workflow with the cable plugged in.

  3. Otherwise, mcuctl stages the package on the host and copies it over serial.

circup has to be installed on the same Python as mcuctl’s sidecar.