micropython-samples/micropip/README.md

0. Installing MicroPython library modules

Paul Sokolovsky, the author of most of the micropython library and major contributor to MicroPython, has forked the MicroPython project. This is the pycopy fork.

Official firmware may be found on micropython.org. Each firmware build has its own library. Some modules in the Pycopy library are incompatible with the official firmware.

Libraries may be installed by copying files from the appropriate library repository to the target device. However this requires some attention to detail where there are dependencies or where modules are organised as Python packages.

Each fork has applications for installing library and user contributed modules modelled on Python's pip. These handle dependencies and build the correct directory structure on the target.

Note that pip and pip3 cannot be used for MicroPython modules. This is because the file format is nonstandard. The file format was chosen to enable the installer to run on targets with minimal resources.

1. Contents

0. Installing MicroPython library modules
1. Contents
2. Users of Pycopy firmware
3. Users of official MicroPython
   3.1 The installers
   3.1.1 upip_m upip replacement runs on target hardware
   3.1.2 micropip Runs on a PC
4. Overriding built in library modules

Main README

2. Users of Pycopy firmware

The library for the pycopy fork may be found here. Library modules located on PyPi are correct for the pycopy firmware.

The preferred installation tool is upip.py which may be found in the tools directory of MicroPython. It is installed by default on network enabled hardware such as Pyboard D, ESP8266 and ESP32.

For hardware which is not network enabled, upip may be run under the Unix build of MicroPython to install to an arbitrary directory on a PC. The resultant directory structure is then copied to the target using a utility such as rshell.

Usage of upip is documented in the official docs.

3. Users of official MicroPython

The library at micropython-lib is compatible with the official firmware. Unfortunately for users of official firmware its README is misleading, not least because the advocated upip module may produce an incorrect result. This is because it installs from PyPi and some modules there require the pycopy firmware.

Two (unofficial) utilities are provided for users of the official firmware. Where a library module is to be installed, these will locate a compatible version. User contributed modules located on PyPi will be handled as normal.

• upip_m.py A modified version of upip.py. For network enabled targets.
• micropip.py Installs modules to a PC for copying to the target device. This is primarily for non-networked targets and for targets with insufficient RAM to run upip_m.py. Requires CPython 3.2 or later.

3.1 The installers

These have the same invocation details as upip and the official docs should be consulted for usage information.

3.1.1 upip_m

The file upip_m.py should be copied to the target device. If upip is not available on the target upip_utarfile.py must also be copied.

Alternatively and more efficiently these files may be frozen as bytecode. The method of doing this is documented here.

Users of the ESP8266 are unlikely to be able to use upip_m unless it is frozen as bytecode. An alternative is to use micropip.py to install to a PC and then to use rshell or other utility to copy the directory structure to the device.

3.1.2 micropip

This is a version of upip_m which runs under Python 3.2 or above. Library and user modules are installed to the PC for transfer to the target. It is cross platform and has been tested under Linux, Windows and OSX.

Help may be accessed with

micropip.py --help

or

python3 -m micropip --help

Example invocation line:

$ micropip.py install -p ~/rats micropython-uasyncio

Contents

4. Overriding built in library modules

Some firmware builds include library modules as frozen bytecode. On occasion it may be necessary to replace such a module with an updated or modified alternative. The most RAM-efficient solution is to rebuild the firmware with the replacement implemented as frozen bytecode.

For users not wishing to recompile there is an alternative. The module search order is defined in sys.path.

>>> import sys
>>> sys.path
['', '/flash', '/flash/lib']

The '' entry indicates that frozen modules will be found before those in the filesystem. This may be overridden by issuing:

>>> import sys
>>> sys.path.append(sys.path.pop(0))

This has the following outcome:

>>> sys.path
['/flash', '/flash/lib', '']

Now modules in the filesystem will be compiled and executed in preference to those frozen as bytecode.

Contents

Main README