Limitations

The utility is still in its infancy and comes with some limitations:

  • The device drive name must be named CIRCUITPY. It's possible that this will change in a future release.
  • It only works with the first CircuitPython device plugged in. Plugging in another one and unplugging the first does not work.

Everyone is welcome to submit Issues and Pull Requests to the Circup Repository to request features or fix bugs.

Let's Go!

Once you have CircUp installed, using it involves just typing a few of the available commands.

You can now use CircUp with either PY and MPY files.

Options

Let's start by reviewing the options available. Some of the options are intended to be run with commands and some without commands.

Display the Command Options

You can display the help information, which will summarize the options that are available. To display this, you can either pass in the --help option without a command or just run circup without any options or commands.

circup

or

circup --help

Display the Version

You can display the current version of circup that you're running. To display this, you simply pass the --version option without a command.

circup --version

Show all Error/Informational Messages

To display all of the raw error and other useful informational messages for a command, you can provide the --verbose flag along with the command.  For it to work properly, it need to be given before the command.

circup --verbose [command]

Commands

Here's a list of commands that you can type. For all of the commands, you can pass the --verbose option to see all output.

Display All Libraries and Version

To figure out all of the currently installed libraries and detected version on your CircuitPython device, type:

circup freeze

You may notice some of the older libraries have None listed for the version number and this is because some of the older CircuitPython libraries were missing version numbers in the actual file until we got a Cookie cutter in place. There's also a high probability that these files are also missing a link to the Repository with the latest releases and won't be updatable automatically.

If the version says 0.0.0-auto.0, then it means it came directly from one of our CircuitPython driver Repos and not from a release or bundle. The version is filled in automatically with a release. These files are completely updatable as long as they are recent enough to contain a link to the Repository.

List all of the Outdated Libraries

You can list all of the outdated libraries and the current/latest versions of each. You do that by typing the following:

circup list

Just like with freeze, you may see unknown or 0.0.0-auto.0.

Show All Available Libraries

To show all the CircuitPython libraries as a list that are available for installation, you can type the following:

circup show

Install a Library with CircUp

To install a library with CircUp, first you need to know the name of the library. You can do that with the circup show command (see above). First make sure you have your CircuitPython-powered device plugged in and then type in the following:

circup install [library_name]

If you would like to install a library in uncompiled byte code, you can also pass it the --py flag like the following:

circup install [library_name] --py

Interactively Update all Libraries

To interactively update all of the libraries on your CircuitPython device, you can type the following:

circup update

If you have some of the older drivers, you may get errors updating such as the repository link missing and those drivers will need to be manually updated. The latest drivers should now all have their links and version numbers added, so after that updating should be easy.

Automatically Update All Libraries

To automatically update all of the libraries on your CircuitPython device, you can type the following:

circup update --all

This guide was first published on Sep 18, 2019. It was last updated on Sep 18, 2019.
This page (Usage) was last updated on Jun 03, 2020.