How to Use the Command 'circup' (with Examples)

Circup is a command-line tool designed to streamline the process of managing libraries on CircuitPython-compatible devices. This tool, developed by Adafruit, allows users to update, install, search, and manage libraries efficiently. It is an essential utility for anyone working with CircuitPython, as it simplifies the management of libraries directly on a connected device. By automating these tasks, circup saves time and reduces the potential for errors, making it easier for developers to focus on their projects rather than library maintenance.

Use Case 1: Interactively Update Modules on a Device

Code:

circup update

Motivation: Keeping libraries up-to-date ensures access to the latest features, improvements, and bug fixes. By using this command, developers can ensure that their projects benefit from the latest developments in the libraries they rely on. This is especially important in a rapidly evolving environment, where using outdated libraries might lead to compatibility issues or missing out on new functionalities.

Explanation: The circup update command checks all modules installed on the connected CircuitPython device and interactively guides the user to update any outdated modules. It ensures that the device is running the most recent versions available in the CircuitPython bundle.

Example Output:

Checking for updates to libraries...
Found update for adafruit_requests: 1.0.0 -> 1.0.1
Would you like to update this library? [Y/n] y
Updating adafruit_requests...
Update complete.

Use Case 2: Install a New Library

Code:

circup install library_name

Motivation: Installing new libraries allows developers to extend their projects with more capabilities and functionalities. Whether integrating a sensor, using a new API, or improving graphics, this command makes it easy to bring in new components by installing the necessary libraries with a single simple command.

Explanation: The circup install library_name command is used to download and install a specified library onto the connected CircuitPython device. Replace library_name with the name of the library you want to install. This functionality is crucial when starting a project or adding new features that require additional libraries.

Example Output:

Searching for library 'adafruit_display_text'...
Library found. Installing...
Library 'adafruit_display_text' installed successfully.

Use Case 3: Search for a Library

Code:

circup show partial_name

Motivation: When working on a project, developers may need a particular library but might not remember the exact name. Using the search feature of circup allows them to locate potential libraries quickly, easing the discovery process and facilitating the addition of relevant libraries to their projects.

Explanation: The circup show partial_name command searches through available libraries for any matches or approximate matches to the partial_name provided. This is helpful in identifying the correct library to use without knowing its exact name.

Example Output:

Searching libraries for 'display'...
Found libraries:
   - adafruit_display_text
   - adafruit_displayio_ssd1306
   - adafruit_display_shapes

Use Case 4: List All Libraries on a Connected Device in requirements.txt Format

Code:

circup freeze

Motivation: Documenting the libraries in use on a CircuitPython device is crucial for project reproducibility and collaboration. Using circup freeze, developers can generate a list of libraries in a familiar requirements.txt format, making it easy to share their setup with others or ensure consistency across multiple devices.

Explanation: The circup freeze command lists all libraries currently installed on the connected CircuitPython device in a format similar to Python’s requirements.txt. This output can be used to recreate the same environment on another device.

Example Output:

adafruit_display_text==1.0.5
adafruit_requests==1.0.1
adafruit_circuitplayground==2.3.3

Use Case 5: Save All Libraries on a Connected Device in the Current Directory

Code:

circup freeze -r

Motivation: Sometimes, developers might want to back up all libraries from their CircuitPython device for version control or troubleshooting purposes. Saving these libraries locally allows inspection, modification, or sharing without the need to reconnect and download all libraries individually.

Explanation: The circup freeze -r command not only lists the libraries as circup freeze does but also saves a copy of each library onto the local system in the current directory. The -r flag indicates that the command should perform a recursive download of all libraries.

Example Output:

Libraries saved to local directory:
adafruit_display_text/
adafruit_requests/
adafruit_circuitplayground/

Conclusion:

Circup is a powerful tool that assists developers in efficiently managing CircuitPython libraries directly on their devices. Through interactive updating, library installation, search capabilities, listing, and local saving options, circup simplifies the workflow of keeping circuit boards tailored and up to date, encouraging more efficient and error-free project development. With these examples, developers can make the most of circup’s capabilities to enhance their work with CircuitPython.