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:

• install - Install a named module(s) onto the device.
• uninstall - Uninstall a named module(s) from the connected device.
• update - Update modules on the device.
• list - Lists all out of date modules found on the connected device.
• freeze - Output details of all the modules found on the connected.
• example - Copy named example(s) from a bundle onto the device.
• show - Show a list of available modules in the bundle.
• bundle-add, bundle-remove, bundle-show - Manage local bundles.

Argument / Command Order

Except for the --help argument, every other argument that is documented on this page needs to be passed prior to the command being being issued. 

Correct Examples (Arguments Before Command):

$ circup --host 192.168.1.188 --password Passw0rd install adafruit_display_text
$ circup --verbose install adafruit_display_text
$ circup --path my_project/ --cpy-version 9.0.0 install adafruit_display_text

$ circup --host 192.168.1.188 --password Passw0rd install adafruit_display_text
$ circup --verbose install adafruit_display_text
$ circup --path my_project/ --cpy-version 9.0.0 install adafruit_display_text

Incorrect Examples (Arguments After Command):

$ circup install adafruit_display_text --host 192.168.1.188 --password Passw0rd
$ circup install adafruit_display_text --path my_project/ --cpy-version 9.0.0
$ circup install adafruit_display_text --verbose

$ circup install adafruit_display_text --host 192.168.1.188 --password Passw0rd
$ circup install adafruit_display_text --path my_project/ --cpy-version 9.0.0
$ circup install adafruit_display_text --verbose

Informational Commands & Arguments

The following commands do not interact with a microcontroller. They can be used without a device plugged in.

• circup --help : Print the built-in documentation information into the terminal. If you don't specify any command then it will print an overview of all commands along with the general documentation
• circup [command] --help : Print the built-in documentation about the specified command i.e. circup install --help will print documentation and available arguments for the install command.
• circup --version : Print current version of the Circup utility that is installed.
• circup --verbose [command] : Print more verbose output when executing the specified command. Without the --verbose flag specified there is still more verbose information written to a log file, this flag prints that information to the terminal output in addition to the log file.

Web Workflow Arguments

The following arguments are used for interacting with a Circuitpython device via Web Workflow rather than the typical USB Disk Workflow. To connect to the web workflow two things are needed: the hostname or IP address of the device, and the web workflow password that is used to authenticate the requests. Optionally a timeout can be passed to configure how long the tool will wait while attempting to make a connection to the device.

• --host [hostname_or_ip] : The IP or Hostname of the CircuitPython device to connect to. If omitted Circup will attempt to use circuitpython.local and find unique hostname from the information returned by the workflow API. If there are multiple devices with web workflow enabled connected to the network then you'll need to specify one with this argument. examples:
  • circup --host 192.168.1.188 [rest of command]
  • circup --host cpy-59689c.local [rest of command]
• --password [password_value] : The password used to authenticate the web workflow requests. This is configured in settings.toml on the device. example:
  • circup --host 192.168.1.188 --password Passw0rd [rest of command]

  Alternatively you can set the environment variable CIRCUP_WEBWORKFLOW_PASSWORD with a value equal to the password. Circup will check for this environment variable and attempt to use it's value if it exists. If it doesn't exist, or if the value inside of it is incorrect then the --password argument is required to be passed with the correct password in order for Circup to function correctly. After setting the environment variable you can omit the --password argument from circup commands for the remainder of the terminal session example (Linux / Mac):

  • export CIRCUP_WEBWORKFLOW_PASSWORD=Passw0rd 
• --timeout [value] : The number of seconds to wait while attempting to connect to the Circuitpython device over the network. The default values is 30 seconds. example setting to 10 seconds:
  • circup --timeout 10 [rest of command]

Disk Path Location Argument

If you have changed your USB Storage device's label to something other than the default CIRCUITPY or if you'd like to use circup to manage libraries in a local project directory instead of directly on a circuitpython device you can use the --path argument.

• --path [path_value] : A local filepath pointing the local directory that you would like circup to treat as it would the circuitpython device root for the purposes of managing library files. Examples:
  • circup --path CUSTOMDRIVENAME/ [rest of command]
  • circup --path ~/projects/very_cool_project/ [rest of command]
  • circup --path c:\projects\very_cool_project\ [rest of command]

Local Project Directories

If you are using circup to manage libraries within a local project directory on your host PC rather than directly on a Circuitpython device you will also need to pass the --cpy-version argument with a value equal to a valid semantic version string that circup will use when determining which version of MPY file to load.

• --cpy-version [version] : The version number to use for the purpose of selecting MPY version of the library files. Example:
  
  • circup --path cool_project/ --cpy-version 9.0.0 [rest of command]

Troubleshooting

Possible Error Output:

Auto locating USB Disk based device failed. Please specify --path argument or ensure your device is connected and mounted under the name CIRCUITPY.
Could not find a connected CircuitPython device.

Auto locating USB Disk based device failed. Please specify --path argument or ensure your device is connected and mounted under the name CIRCUITPY.
Could not find a connected CircuitPython device.

Explanation

Circup was unable to automatically locate your device. There are a few possible causes of this.

If your device is connected with a USB cable then ensure that it is appearing to the host PC as the CIRCUITPY drive. If it's not appearing, make sure that you have a working USB cable with data lines. Some USB cables are charging only, and will not work with Circup.

If your device has a custom drive name other than CIRCUITPY then you will need to use the --path argument and pass the path pointing to your drive by it's name.

If your using web workflow then you need to include the --host and --password arguments and pass in the IP address or hostname, and webworkflow password respectively.