How to use the command `circup` (with examples)
circup is a command-line tool used for managing and updating libraries in CircuitPython projects. It provides a convenient way to interactively update modules on a device, install new libraries, search for libraries, and list or save libraries on a connected device.
Use case 1: Interactively update modules on a device
Code:
circup update
Motivation: This use case is beneficial when you want to update all the installed libraries on your CircuitPython device to their latest versions. It ensures that your device has the most up-to-date features and bug fixes available.
Explanation: The update command updates all libraries on your CircuitPython device to their latest versions. It checks the installed libraries against the latest versions available on the CircuitPython library bundle and updates the ones that have newer versions.
Example output:
Updating Adafruit_CircuitPython_Bundle...
Updated Adafruit_CircuitPython_Bundle from v5.3.0 to v5.4.0
Updating Adafruit_BLE...
Updated Adafruit_BLE from v0.9.1 to v1.0.0
Updating Adafruit_BluefruitLE...
Up-to-date: Adafruit_BluefruitLE (v0.18.0)
...
Use case 2: Install a new library
Code:
circup install library_name
Motivation: Installing a new library is necessary when you want to add additional functionality or features to your CircuitPython project. The install command makes it easy to download and install libraries from the CircuitPython library bundle directly to your device.
Explanation: The install command installs the specified library_name from the CircuitPython library bundle onto your device. It fetches the latest version of the library and installs it for immediate use.
Example output:
Installing Adafruit_BME280...
Installed Adafruit_BME280 v2.11.0
Use case 3: Search for a library
Code:
circup show partial_name
Motivation: Searching for a library is handy when you want to find specific libraries related to a particular functionality or feature required for your CircuitPython project.
Explanation: The show command searches for libraries with names containing the specified partial_name. It provides a list of libraries that match the search term, along with their version numbers.
Example output:
- Adafruit_BNO055 (v2.5.2)
- Adafruit_NeoPixel (v6.0.0)
- Adafruit_PCA9685 (v2.3.1)
...
Use case 4: List all libraries on a connected device in requirements.txt format
Code:
circup freeze
Motivation: Listing all libraries on a connected CircuitPython device in requirements.txt format is helpful when you want to document and manage the libraries used in your project. It allows easy sharing of the libraries needed to replicate your project.
Explanation: The freeze command lists all libraries installed on the connected CircuitPython device in requirements.txt format, which is a common format used for specifying library dependencies in Python projects.
Example output:
Adafruit_BNO055==2.5.2
Adafruit_NeoPixel==6.0.0
Adafruit_PCA9685==2.3.1
...
Use case 5: Save all libraries on a connected device in the current directory
Code:
circup freeze -r
Motivation: Saving all libraries on a connected CircuitPython device in the current directory is beneficial when you want to backup or document the libraries used in your project. It provides a convenient way to have a local copy of the libraries for offline access or version control.
Explanation: The freeze -r command saves all libraries installed on the connected CircuitPython device in the current directory. Each library is saved as a separate .mpy file, including its dependencies, allowing you to easily access and manage the libraries locally.
Example output:
Saving Adafruit_BNO055...
Saving Adafruit_NeoPixel...
Saving Adafruit_PCA9685...
...
Conclusion:
The circup command-line tool offers a wide range of capabilities for managing and updating libraries in CircuitPython projects. Whether you need to update, install, search, list, or save libraries, circup provides a convenient interface to streamline library management in your CircuitPython development workflow.
