CircuitPython-Bundle-Manager

A Python program that makes it easy to manage modules on a CircuitPython device!

Problems? Please file an issue or even better, a pull request if you can fix it!

Need help/don't understand something? Join the Adafruit Discord server and ping @Ckyiu on there!

Note: If you are viewing this file offline, the HTML generated from this markdown isn't perfect. It is highly recommended that you view this file on GitHub, as it has been tuned for GitHub-style markdown.

Check out my other projects related to CircuitPython: (Oh look shameless self-promotion again)

• CircuitPython-Project-Manager: A Python program that will copy files to a CircuitPython device, basically eliminating the risk of losing code from the CircuitPython drive being corrupted and allows for version-control systems!

Table of Contents

1. Installing
   1. Release notes for v1.1.0
   2. Installing from a binary
   3. Installing from source
2. Running
3. How to use
   1. First use
   2. Selecting a device
   3. Managing modules
   4. Keeping the bundle updated
   5. Automatically detecting imported modules
   6. Other
4. Options

Installing

Binaries are now available for Windows and Linux! (macOS users are going to have to wait a bit as I get a working VM) Check it out here.

Release notes for v1.1.0

You can get the v1.1.0 release here.

Changes:

• Added a new Detect tab to automatically detect dependencies, saving a couple clicks! (Still very new, so report an issue if there are problems!)

Back to table of contents

Installing from a binary

No installation is required! (Well, there is no installer. You are still going to have to create a shortcut/symlink to it somewhere and extract it if you are using the directory-based executable)

These binaries were built with PyInstaller.

Using the one executable:

1. Download the latest binary from here.
2. Put it somewhere. On Windows, I would put it in C:\Program Files\CircuitPython Bundle Manager. On Linux, I would put it in /usr/bin.
3. Create a shortcut/symlink to it on the desktop!

Note: If you are having trouble with the one-executable, try the one directory method!

Pros of the one-executable

• Convenient - you only need to deal with one executable.
• Easy to install - just place the executable somewhere and create a shortcut.

Cons of the one-executable

• Takes quite a while to start compared to the one-directory method.
• Needs to execute code out of the temporary directory, which sometimes isn't allowed on Linux.
• If the application crashes, the support code won't be deleted, so it will take up disk space until the OS clears it.
• Needs more space than the one-directory method.

Using the one directory:

1. Download the zip/tar.gz file from here.
2. Extract it.
3. Place the directory somewhere convenient. On Windows, I would put the extracted files and directories in C:\Program Files\CircuitPython Bundle Manager.
4. Create a shortcut/symlink to CircuitPython Bundle Manager.exe. (CircuitPython Bundle Manager on Linux) It is in the top directory.

Pros of the one directory:

• Fast - all the support files are ready, no need to extract them like in the one-executable method.
• Less space - needs less disk space then the one-executable method.

Cons of the one directory:

• Slightly annoying to install.

You can find a detailed description of the one-directory method here and a description of how the one-file method works here.

Back to table of contents

Installing from source

1. Download and install Git. It does not matter what editor you use for Git's default.

   1. Or...download this repo via the Download ZIP option under the green Code button, shown in Figure 1.1:

   

2. Download and install Python 3.9. (Because I use type definitions, but 3.8 seems to work too)

   1. Make sure to check Add Python 3.x to PATH, as shown in Figure 1.2:

      

   2. Make sure to also install Tk/Tcl support! If you can access the IDLE, then Tk/Tcl is installed, as shown in Figure 1.3: (Only applies if you are using the Customize installation option in the installer)

      

      If you are building Python, here is a guide on building Python on Debian I found helpful. Before building, you may need to install a bunch of packages using apt: sudo apt install libbz2-dev libgdbm-dev libgdbm-compat-dev liblzma-dev libsqlite3-dev libssl-dev uuid-dev libreadline-dev zlib1g-dev tk-dev libffi-dev.

3. If you are on Windows, I would also install the Windows Terminal while you are at it.

4. If you installed Git, cd into a convenient directory (like the home directory or the desktop) and run:

   git clone https://github.com/UnsignedArduino/CircuitPython-Bundle-Manager
   cd CircuitPython-Bundle-Manager
   

   1. If you downloaded the ZIP, move the downloaded ZIP to somewhere convenient (ex. home directory or desktop), extract it, open a terminal and cd into the extracted directory.

5. If you run dir (or ls on Mac and Linux) you should get something like this:

   1. dir (Windows):

   01/18/2021  08:11 PM    <DIR>          .
   01/18/2021  08:11 PM    <DIR>          ..
   01/18/2021  08:11 PM    <DIR>          bundle_tools
   01/18/2021  08:11 PM            39,625 gui.py
   01/18/2021  08:11 PM    <DIR>          gui_tools
   01/18/2021  08:11 PM               329 main.py
   01/18/2021  08:11 PM             1,949 README.md
   01/18/2021  08:11 PM                18 requirements.txt
                  4 File(s)         41,921 bytes
                  4 Dir(s)  x bytes free
   

   2. ls (macOS and Linux):

   bundle_tools  gui.py  gui_tools  main.py  README.md  requirements.txt
   

6. If you are going to use a virtual environment, run the following commands:

   1. Windows:

   python -m venv .venv
   ".venv/Scripts/activate.bat"
   

   2. macOS and Linux:

   python3 -m venv
   source .venv/bin/activate
   

7. Install the packages:

   1. Windows:

   pip install -r requirements.txt
   

   2. macOS and Linux:

   pip3 install -r requirements.txt
   

8. You should now be able to run it!

   1. Windows:

   python main.py
   

   2. macOS and Linux:

   python3 main.py
   

Back to table of contents

Running

If you installed from a binary, then just run the CircuitPython Bundle Manager.exe (CircuitPython Bundle Manager macOS and Linux) file. You may want to create a shortcut/symlink to it on the desktop or create a menu entry. If you would like to submit an icon, you can open an issue for it with the icon.

If you install from source and you are not using a virtual environment, then you can just create a .bat file containing python \path\to\the\main.py (python3, forward slashes, and use .sh for the extension on macOS and Linux) on the desktop for convenience. Otherwise, you will need to re-activate the virtual environment everytime you want to run it. I highly recommend using these shell scripts:

1. Windows:

:: Replace this with the path to the directory of the CircuitPython Bundle Manager, should have main.py in it
cd path\to\the\CircuitPython-Bundle-Manager
:: You can use python.exe or pythonw.exe - the w one will just supress output of the program
".venv\Scripts\pythonw.exe" main.py

2. macOS and Linux:

# Replace with the path to the CircuitPython Bundle Manager
cd path/to/the/CircuitPython-Bundle-Manager
.venv/bin/python3 main.py

Don't forget to give the .sh file execute permission! (chmod +x shell_file.sh)

Back to table of contents

How to use

First run

On run, you should get something like this:

If the GUI looks different from these images, it's because I don't want to update all these images. I will only update the relevant images. (So if I add something in the example, Bundle Manager, then I will include new instructions on how to use it, I won't be updating all the images that show the Bundle Manager.) The functionality should still be the same.

Figure 2.1: Start up on Windows.

Figure 2.2: Start up on Debian. (To be honest, Tk doesn't look that great on Linux...)

Note: From now on, I will be exclusively showing pictures of the CircuitPython Bundle Manager on Windows unless there are Linux-specific instructions. The interface is exactly the same.

What you want to do is to authenticate yourself and update the bundle so you can install modules. You can do it several ways:

1. Use your username and password
2. Use a GitHub token
3. Use a GitHub Enterprise URL and a login/token

Use the radio buttons (boxed in Figure 1.3) to select your method of authentication.

Figure 2.3: The radio buttons used to select the method of authentication.

If you used your username and password, type in your username and password. (Labeled 1 in Figure 1.4)

If you used a GitHub access token, paste it in. (Labeled 2 in Figure 1.4)

If you used a GitHub Enterprise URL and a login/token, paste those in. (Labled 3 in Figure 1.4)

Figure 2.4: The methods of authentication labeled. Since I selected Username and password in the authentication method selector, I can only type in the Username and Password boxes.

Once you fill those in, make sure the version listbox (boxed in figure 2.5) has the correct version of CircuitPython you plan to use. If it does not exist or is too old, you will get an error shown in figure 2.6. If you input some bad credentials, you will get an error shown in figure 2.7.

Figure 2.5: The version listbox boxed.

Figure 2.6: The error you get when inputting a bad version. Sadly, CircuitPython 7 doesn't exist. (yet)

Figure 2.7: The error you get when inputting bad credentials.

Press Update bundle, and if all goes well, you should get a happy info message shown in Figure 1.8:

Note: You will need a working internet connection for this!

Figure 2.8: The info box when the bundle updates successfully.

That is it! Continue to selecting a device.

Back to table of contents

Selecting a device

At the bottom of the UI, there is a section which will be shown regardless of the tab selected. This is where you can select your CircuitPython device, as shown in Figure 2.9:

Figure 2.9: The drive selector highlighted.

If you click on the downwards facing arrow in the entry box (labeled 1 in Figure 2.10) a small menu will pop up. It will most likely be empty unless you have a CircuitPython device connected, or you have Show all drives? checked. (Labeled 3 in Figure 2.10, and shown in Figure 2.11) The reload button (labeled 2 in Figure 2.10 reloads a handful of things, including what drives are connected, so if you don't see your drive, click it!)

Figure 2.10: Various parts of the drive selector labeled.

Figure 2.11: More drives are shown with the Show all drives? checkbox checked. You will most likely not need this checked.

On Linux (and macOS too - I think) it will look slightly different. Instead of drive letters, a path will be shown, like in Figure 2.12:

Figure 2.12: The drive selector on Linux.

The CircuitPython Bundle Manager searches for drives in /media. If your OS does not mount drives there, follow these instructions:

1. Connect a CircuitPython device.

2. Mount the device if necessary.

3. Get the path of where the device was mounted. For example, /media/pi/CIRCUITPY.

4. Switch to the Other tab and click on Open config file.

5. Change the value of unix_drive_mount_point to the parent directory of the path of the device.

   Figure 2.13: My configuration file after modifying it:

   

6. Click the refresh button

7. Select the device!

That is it! Continue to managing modules.

Back to table of contents

Managing modules

This is the fun part! (Well, not really) Here you can view the modules you can install and the modules already installed on the selected CircutiPython device! Figure 2.14 shows an anatomy of the Bundle Manager tab:

Figure 2.14: An anatomy of theBundle Manager tab.

1. (Blue) This is the search bar - typing in it will filter out modules that don't have that string inside it. (Uses Python's in keyword)
2. (Green) This is where you where can scroll through the list of modules you can install - will reflect the contents of the most recent bundle on your machine. If it's blank, try pressing the reload button and updating the bundle!
3. (Red) This is the list of installed modules on the selected CircutiPython device - after selecting a new one, press refresh!
4. (Orange) If a module is selected in the bundle and there is a selected device, then you can install to it!
5. (Pink) If a module is selected in the list of installed modules and there is a selected device, you can uninstall it!

Let's say I wanted to install the simpleio.mpy module . First, I could either scroll through the list to find simpleio or use the search bar to search up simpleio, like in Figure 2.15:

Figure 2.15: Using the search bar to find the simpleio.mpy files.

If it succeeds, you get an information box like in Figure 2.16:

Figure 2.16: Success!

And in Figure 2.17, you can see it successfully installed!

Figure 2.17: Look, it's in the list of installed modules now!

Oh never mind, we didn't need the simpleio module. To uninstall it, click on simpleio.mpy in the list of installed modules and press Uninstall!

Figure 2.18: Uninstalling the simpleio.mpy file.

Figure 2.19: We see that it has been successfully uninstalled!

That is it! Continue to keeping the bundle updated.

Back to table of contents

Keeping the bundle updated

Follow the instructions provided in first run. You only need to do this once a day, since the bundle is updated once a day at ~12PM EST.

TL;DR:

1. Make sure you have a working internet connection.
2. Select method of authentication.
3. Input credentials.
4. Select CircuitPython version.
5. Press Update!

Back to table of contents

Automatically detecting imported modules

Note: This feature is still very new! Problems? Report an issue!

Instead of scrolling through the bundle or using the search bar, why not save a couple more steps and have the CircuitPython Bundle Manager automatically detect dependencies for you? Figure 2.20 shows the Detect tab:

Figure 2.20: The Detect tab in the CircuitPython Bundle Manager.

If you have a CircuitPython device selected and there is a valid code file (One of code.txt, code.py, main.txt, main.py) you can press the Detect button to have the CircuitPython Bundle Manager parse the code files and look at your import statements. I'm using this example from the Adafruit Airlift Featherwing Internet Connect guide from the Adafruit Learn site. If you click on one of the modules and it's in the bundle, the Find in bundle button will light up. Pressing it will teleport you to the Bundle Manager allowing you to click Install!

Figure 2.21: After clicking on adafruit_requests in the listbox and pressing Find in bundle, I was teleported here!

Back to table of contents

Other

Figure 2.22: The Other tab in the CircuitPython Bundle Manager. The interface may change and I will probably forget to change this too.

• Open README file opens this file locally with the default .html/.md program. If it cannot find it, it will attempt to download it from GitHub.
• Convert to HTML will decide whether to convert the markdown to HTML before showing it to you.
• Open README file location opens the location of the README file in the default file manager.
• Open config file opens the configuration file in the default .json program.
• Reset config file resets the config file but only after you confirm doing so.
• Open config file location opens the location of the config file in the default file manager.
• Open log file opens the log file in the default .log program.
• Open log file location opens the location of the log file in the default file manager.
• Open GitHub repo link opens the repository in the default browser.
• Copy GitHub repo link copies the link to this repository on GitHub to the clipboard.
• Open an issue opens the new issue panel in the default browser.
• Copy link to open issue copies the link to the new issue panel.

Back to table of contents

Options

You can find these options in config.json, which is in the same directory as main.py, and should be auto-generated upon first run. In case it does not happen, (file a issue?) this is the default JSON file:

{
    "last_auth_method_used": "username and password",
    "last_circuit_python_bundle_version": 6,
    "show_traceback_in_error_messages": false,
    "unix_drive_mount_point": "/media"
}

• last_auth_method_used should be a string of username and password, access token, or enterprise. This is the last method of authentication you used.
• last_circuitpython_bundle_version should be a number. This is the last CircuitPython version you used.
• show_traceback_in_error_messages should be a boolean. (Either true or false) This will control whether stack traces will appear in error messages.
• unix_drive_mount_point should be a string of a path that points to the place where your distro automatically mounts drives. Only applies to Unix-based systems.

If you want to reset the config file, there is a button to reset the configuration file in the Other tab. If you want to reset just one option, remove it from the configuration file.

Back to table of contents