Skip to content

Latest commit

 

History

History
172 lines (124 loc) · 7.05 KB

README.md

File metadata and controls

172 lines (124 loc) · 7.05 KB
Raw

micropython-lib

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

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

  • python-stdlib: Compatible versions of modules from The Python Standard Library. These should be drop-in replacements for the corresponding Python modules, although many have reduced functionality or missing methods or classes (which may not be an issue for most cases).

  • python-ecosys: Compatible, but reduced-functionality versions of packages from the wider Python ecosystem. For example, a package that might be found in the Python Package Index.

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

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

Usage

To install a micropython-lib package, there are four main options. For more information see the Package management documentation documentation.

On a network-enabled device

As of MicroPython v1.20 (and nightly builds since October 2022), boards with WiFi and Ethernet support include the mip package manager.

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

Using mpremote from your PC

mpremote is the officially-supported tool for interacting with a MicroPython device and, since v0.4.0, support for installing micropython-lib packages is provided by using the mip command.

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

See the mpremote documentation.

Freeze into your firmware

If you are building your own firmware, all packages in this repository include a manifest.py that can be included into your board manifest via the require() command. See Manifest files for more information.

Copy the files manually

Many micropython-lib packages are just single-file modules, and you can quickly get started by copying the relevant Python file to your device. For example, to add the base64 library, you can directly copy python-stdlib/base64/base64.py to the lib directory on your device.

This can be done using mpremote, 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 copy the directory instead. For example, to add collections.defaultdict, copy collections/collections/__init__.py and collections-defaultdict/collections/defaultdict.py to a directory named lib/collections on your device.

Note that unlike the other three approaches based on mip or manifest.py, you will need to manually resolve dependencies. You can inspect the relevant manifest.py file to view the list of dependencies for a given package.

Installing packages from forks

It is possible to use the mpremote mip install or mip.install() methods to install packages built from a fork of 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 under Publishing packages from forks.

After this has happened, each time someone pushes to a branch in t