063c02d607 | ||
---|---|---|
.. | ||
README.md | ||
micropip.py | ||
upip_m.py | ||
upip_utarfile.py |
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 means of 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
- Installing MicroPython library modules
- Contents
- Users of Pycopy firmware
- Users of official MicroPython
3.1 The installers
3.1.1 upip_m
3.1.2 micropip - 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 some library modules on
PyPi 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 ofupip.py
. For network enabled targets.micropip.py
Installs modules to a PC for copying to the target device. For non-networked targets and for targets with too little RAM to runupip_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
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.