Do you have one or more devices running CircuitPython and you find all the frequent library updates by the hard-working Adafruit folks and community members hard to keep up with? Well then CircUp may just be the tool for you.

CircUp is a utility written by Nicholas Tollervey that looks at all the libraries inside of the lib folder on your connected CircuitPython device. It can tell you what version each of them is, if there are any out of date libraries, and if they are out of date, it can automatically go to the repo, download and update the library for you. It's still in the early stages of development, but already works quite well.

This kind of utility is especially useful with some of our M4 CircuitPython devices that can handle lots of libraries such as the Adafruit Grand Central M4 Express.

Are you ready? Really ready? Cause here comes the Adafruit Grand Central featuring the Microchip ATSAMD51. This dev board is so big, it's not...
$37.50
In Stock

The PyPortal is packed with so many features, that it uses a lot of libraries, making this tool especially useful.

PyPortal, our easy-to-use IoT device that allows you to create all the things for the “Internet of Things” in minutes. Make custom touch screen interface...
Out of Stock

Our PyGamer and PyBadge also use quite a few libraries.

What fits in your pocket, is fully Open Source, and can run CircuitPython, MakeCode Arcade or Arduino games you write yourself? That's right, it's the Adafruit...
$39.95
In Stock
What's the size of a credit card and can run CircuitPython, MakeCode Arcade or Arduino? That's right, its the Adafruit PyBadge! We wanted to see how much we...
$34.95
In Stock

Another very popular option is the Adafruit Feather M4 Express.

It's what you've been waiting for, the Feather M4 Express featuring ATSAMD51. This Feather is fast like a swift, smart like an owl, strong like a ox-bird (it's half ox,...
$22.95
In Stock

If you would like something in between, you can go with the Adafruit Metro M4 Express.

Are you ready? Really ready? Cause here comes the fastest, most powerful Metro ever. The Adafruit Metro M4 featuring the Microchip ATSAMD51. This...
$27.50
In Stock

If you need a Metro M4 that can also do WiFi, you may like the Adafruit Metro M4 Express Airlift Lite.

Give your next project a lift with AirLift - our witty name for the ESP32 co-processor that graces this Metro M4. You already know about the Adafruit Metro...
Out of Stock
CircUp runs on your desktop computer (and modifies/updates the files on your CircuitPython board).

Requirements

You will need to have Python 3.6 or higher, Pip, and git installed in order to install CircUp. At the time of writing this guide there are currently no releases, so when there are, installation may be a bit different.

Windows Installation

You can verify that you have Python correctly installed by typing python3 --version at the command prompt and checking that you are running Python 3.6 or higher. If you have Windows 10 and don't currently have it installed, Python is available in the Windows store.

Next, we check that Pip is installed by typing pip3 --version. This should have been installed with Python, but if not, you will need to download and install it. Make sure you are running the latest version of pip by typing pip3 install --upgrade pip.

Finally, make sure git is installed by typing git --version. If this isn't installed, you will need to install a version that you can run from the command line such as git-scm.

After we have verified that we have all the requirements, let's update the Path variable. Getting to this can vary by windows versions, but it's often in the Environment Variable setting dialog, which can be accessed through the System Properties.

To figure out the correct path to add, type the following at the command line:

python3 -m site --user-base

Then copy the path that is returned and add \Python37\Scripts onto the and add that to the end of your path. If your path varies due to having a different version of Python, change it accordingly.

Now continue on to the CircUp installation.

MacOS Installation

You can verify that you have Python correctly installed by typing python3 --version at the command prompt and checking that you are running Python 3.6 or higher. If you don't currently have it installed, Python can easily be installed through a utility called Homebrew.

Next, we check that Pip is installed by typing pip3 --version. This should have been installed with Python, but if not, you will need to download and install it. Make sure you are running the latest version of pip by typing pip3 install --upgrade pip.

Finally, make sure git is installed by typing git --version. If this isn't installed, this can also easily be installed with Homebrew.

Now continue on to the CircUp installation.

Linux Installation

You can easily make sure all three requirements are installed with the following command on a Debian or Ubuntu system:

sudo apt-get install -y python3 git python3-pip

Make sure you are running the latest version of pip by typing pip3 install --upgrade pip.

Now continue on to the CircUp installation.

CircUp runs on your desktop computer (and modifies/updates the files on your CircuitPython board).

After we have verified that we have all the requirements, it's time to install CircUp. Now that it's on PyPI, installation is a snap. Just open up the command line and type the following:

pip install circup

If you have Python 2 set as your default Python version, you may need to use pip3

That's it. After that type circup --version and it should return the version that it's running on. If it returns the version successfully, you should be good to go.

Upgrading to the latest Version

If you already have an older version of CircUp installed through PyPI, you can update to the latest version by typing:

pip install --upgrade circup

Contributing

The utility is still growing and you can check out the GitHub Repo for any outstanding issues. 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.