Repository files navigation

This is a repository of packages designed to be useful for writing MicroPythonapplications.

The packages here fall into categories corresponding to the four top-leveldirectories:

• python-stdlib: Compatible versions of modules fromThe Python StandardLibrary. These should be drop-inreplacements for the corresponding Python modules, although many havereduced functionality or missing methods or classes (which may not be anissue for most cases).

• python-ecosys: Compatible, but reduced-functionality versions ofpackages from the wider Python ecosystem. For example, a package thatmight be found in thePython Package Index.

• micropython: MicroPython-specific packages that do not have equivalentsin other Python environments. This includes drivers for hardware(e.g. sensors, peripherals, or displays), libraries to work withembedded functionality (e.g. bluetooth), or MicroPython-specificpackages that do not have equivalents in CPython.

• unix-ffi: These packages are specifically for the MicroPython Unix portand provide access to operating-system and third-party libraries via FFI,or functionality that is not useful for non-Unix ports.

To install a micropython-lib package, there are four main options. For moreinformation see thePackage management documentationdocumentation.

As of MicroPython v1.20 (and nightly builds since October 2022), boardswith WiFi and Ethernet support include themip package manager.

>>>importmip>>>mip.install("package-name")

mpremote is the officially-supported tool for interacting with a MicroPythondevice and, since v0.4.0, support for installing micropython-lib packages isprovided by using themip command.

$ mpremote connect /dev/ttyUSB0 mip install package-name

See thempremote documentation.

If you are building your own firmware, all packages in this repository includeamanifest.py that can be included into your board manifest via therequire() command. SeeManifest files formore information.

Many micropython-lib packages are just single-file modules, and you canquickly get started by copying the relevant Python file to your device. Forexample, to add thebase64 library, you can directly copypython-stdlib/base64/base64.py to thelib directory on your device.

This can be done usingmpremote, for example:

$ mpremote connect /dev/ttyUSB0 cp python-stdlib/base64/base64.py :/lib

For packages that are implemented as a package directory, you'll need to copythe directory instead. For example, to addcollections.defaultdict, copycollections/collections/__init__.py andcollections-defaultdict/collections/defaultdict.py to a directory namedlib/collections on your device.

Note that unlike the other three approaches based onmip ormanifest.py,you will need to manually resolve dependencies. You can inspect the relevantmanifest.py file to view the list of dependencies for a given package.

It is possible to use thempremote mip install ormip.install() methods toinstall packages built from aforkof micropython-lib, if the fork's owner has opted in.

This can be useful to install packages from a pending Pull Request, for example.

First, the owner of the fork must opt-in as described underPublishing packages from forks.

After this has happened, each time someone pushes to a branch in that fork thenGitHub Actions will automatically publish the packages to a GitHub Pages site.

To install these packages, use commands such as:

$ mpremote connect /dev/ttyUSB0 mip install --index https://USERNAME.github.io/micropython-lib/mip/BRANCH_NAME PACKAGE_NAME

Or from a networked device:

importmipmip.install(PACKAGE_NAME,index="https://USERNAME.github.io/micropython-lib/mip/BRANCH_NAME")

(WhereUSERNAME,BRANCH_NAME andPACKAGE_NAME are replaced with the ownerof the fork, the branch the packages were built from, and the package name.)

We useGitHub Discussionsas our forum, andDiscord for chat. Theseare great places to ask questions and advice from the community or to discuss yourMicroPython-based projects.

TheMicroPython Wiki isalso used for micropython-lib.

For bugs and feature requests, pleaseraise an issue.

We welcome pull requests to add new packages, fix bugs, or add features.Please be sure to follow theContributor's Guidelines & Code Conventions. Note thatMicroPython is licensed under theMIT license and all contributionsshould follow this license.

• Develop a set of example programs using these packages.
• Develop more MicroPython packages for common tasks.
• Expand unit testing coverage.
• Add support for referencing remote/third-party repositories.

The termslibrary,package, andmodule are overloaded and lead to someconfusion. The interpretation used in by the MicroPython project is that:

Alibrary is a collection of installable packages, e.g.The Python StandardLibrary, or micropython-lib.

Apackage can refer to two things. The first meaning, "library package", issomething that can be installed from a library, e.g. viamip (orpip inCPython/PyPI). Packages providemodules that can be imported. The ambiguityhere is that the module provided by the package does not necessarily have tohave the same name, e.g. thepyjwt package provides thejwt module. InCPython, thepyserial package providing theserial module is anothercommon example.

Amodule is something that can be imported. For example, "theos module".

A module can be implemented either as a single file, typically also calledamodule or "single-file module", or as apackage (the second meaning),which in this context means a directory containing multiple.py files(usually at least an__init__.py).

In micropython-lib, we also have the concept of anextension package whichis a library package that extends the functionality of another package, byadding additional files to the same package directory. These packages havehyphenated names. For example, thecollections-defaultdict package extendsthecollections package to add thedefaultdict class to thecollectionsmodule.