We've created a couple library bundles for CircuitPython. The idea is that one can download all available libraries once and then copy them onto the CIRCUITPY drive as needed.
Another advantage of the bundle is that it makes it easy to find a list of all libraries. Even if you can't store all of the libraries on the drive, for example the Gemma M0 is only 64kb, the bundle makes it easy to copy over what you need when you need it.
It also helps CircuitPython devs keep track of libraries and update them as things change.
So, lets get our example library into the community bundle. To do so, we'll make a pull request on GitHub. First, lets fork the community bundle.
After the fork is done, the repo will look the same except the repo name will be different at the top left.
Next we'll clone the repo to our computer. See this guide for detailed instructions on cloning and submitting a pull request. Consider this a quickstart.
When cloning, make sure that you add --recursive to get all of the submodules too.
Adding the submodule to the Library Bundle
Now to add our library to the bundle we'll do:
git submodule add URL_TO_LIBRARY_INCLUDING.git libraries/SUBFOLDER/lowercase_library_name
You'll change the following:
-
URL_TO_LIBRARY_INCLUDING.git- This will be the full URL to the library including the.giton the end. To get this URL, click on "Clone" in the GitHub repo, choose HTTPS, and copy that URL. Or you can copy the URL from the repo and add the.git.
- Example:
https://github.com/adafruit/Adafruit_CircuitPython_PyPortal.git
- Example:
-
SUBFOLDER- The subfolder will behelpersordrivers. Choose which based on your library. Is it a driver? Choosedrivers. Is it a helper? Choosehelpers.- Example:
libraries/helpers/orlibraries/drivers/
- Example:
-
lowercase_library_name- This is the name of your library, minus theAdafruit_CircuitPython_, in lowercase letters.- Example:
pyportal
- Example:
FULL EXAMPLE:
git submodule add https://github.com/adafruit/Adafruit_CircuitPython_PyPortal.git libraries/drivers/pyportal
And then we'll verify it worked by looking at the build log and versions file.
Updating the Library List
Before we submit a pull request with our new library, lets update the bundle documentation to include a link to the documentation for our library. Use whichever method you wish to open /docs/drivers.rst for the Adafruit bundle or circuitpython_community_library_list.md for the community bundle.
In library listing, choose one of the categories to place your documentation link. The current categories are: Board-specific Helpers, Helper, Blinky, Displays, Real-time Clocks, Motion Sensors, Environmental Sensors, Light Sensors, Distance Sensors, Radio, IO Expansion, and Miscellaneous. Or, you can create a new category if that best describes your library.
With your category chosen, simply add a new line to that section using the file's hyperlink format. The easiest way, is to copy an existing line and edit it to change both the link text and the URL.
Next, lets do our normal commit and push process for a new branch.
Going to GitHub will show an easy prompt to create the pull request.
Follow that to see a differences. Make sure that at the top you are comparing against adafruit/CircuitPython_Community_Bundle as the base fork and your branch as the head fork. Make sure at the bottom left that maintainers can edit it (for simple fixes before they submit). Then click Create pull request at the bottom right.
This is the last step you need to do. One of the maintainers will come and respond on the pull request. Once they are happy with the request, it will be merged into the bundle and go out with the next release. It'll show up as purple once accepted.
After a library has been merged into the bundle, the version included will be automatically updated once a day. You don't need to make any other changes to the bundle repo. Simply release new versions in the library repository, and within 24 hours the bundle will be updated and released with the new version.
Page last edited March 08, 2024
Text editor powered by tinymce.
