MicroPython libraries
Warning
Important summary of this section
MicroPython provides built-in modules that mirror the functionality of thePython standard library (e.g.
os,time), as well asMicroPython-specific modules(e.g.bluetooth,machine).Most Python standard library modules implement a subset of thefunctionality of the equivalent Python module, and in a few cases providesome MicroPython-specific extensions (e.g.
array,os)Due to resource constraints or other limitations, some ports or firmwareversions may not include all the functionality documented here.
To allow for extensibility, some built-in modules can beextended from Python code loaded ontothe device filesystem.
This chapter describes modules (function and class libraries) which are builtinto MicroPython. This documentation in general aspires to describe all modulesand functions/classes which are implemented in the MicroPython project.However, MicroPython is highly configurable, and each port to a particularboard/embedded system may include only a subset of the available MicroPythonlibraries.
With that in mind, please be warned that some functions/classes in a module (oreven the entire module) described in this documentationmay be unavailablein a particular build of MicroPython on a particular system. The best place tofind general information of the availability/non-availability of a particularfeature is the “General Information” section which contains informationpertaining to a specificMicroPython port.
On some ports you are able to discover the available, built-in libraries thatcan be imported by entering the following at theREPL:
help('modules')
Beyond the built-in libraries described in this documentation, many moremodules from the Python standard library, as well as further MicroPythonextensions to it, can be found inmicropython-lib.
Python standard libraries and micro-libraries
The following standard Python libraries have been “micro-ified” to fit in withthe philosophy of MicroPython. They provide the core functionality of thatmodule and are intended to be a drop-in replacement for the standard Pythonlibrary.
array– arrays of numeric dataasyncio— asynchronous I/O schedulerbinascii– binary/ASCII conversionsbuiltins– builtin functions and exceptionscmath– mathematical functions for complex numberscollections– collection and container typeserrno– system error codesgc– control the garbage collectorgzip– gzip compression & decompressionhashlib– hashing algorithmsheapq– heap queue algorithmio– input/output streamsjson– JSON encoding and decodingmarshal– Python object serializationmath– mathematical functionsos– basic “operating system” servicesplatform– access to underlying platform’s identifying datarandom– generate random numbersre– simple regular expressionsselect– wait for events on a set of streamssocket– socket modulessl– SSL/TLS modulestruct– pack and unpack primitive data typessys– system specific functionstime– time related functionszlib– zlib compression & decompression_thread– multithreading support
MicroPython-specific libraries
Functionality specific to the MicroPython implementation is available inthe following libraries.
bluetooth— low-level Bluetoothbtree– simple BTree databasecryptolib– cryptographic ciphersdeflate– deflate compression & decompressionframebuf— frame buffer manipulationmachine— functions related to the hardwaremicropython– access and control MicroPython internalsneopixel— control of WS2812 / NeoPixel LEDsnetwork— network configurationopenamp– provides standard Asymmetric Multiprocessing (AMP) supportuctypes– access binary data in a structured wayvfs– virtual filesystem control
The following libraries provide drivers for hardware components.
Port-specific libraries
In some cases the following port/board-specific libraries have functions orclasses similar to those in themachine library. Where this occurs, theentry in the port specific library exposes hardware functionality unique tothat platform.
To write portable code use functions and classes from themachine module.To access platform-specific hardware use the appropriate library, e.g.pyb in the case of the Pyboard.
Libraries specific to the pyboard
The following libraries are specific to the pyboard.
Libraries specific to the WiPy
The following libraries and classes are specific to the WiPy.
Libraries specific to the ESP8266 and ESP32
The following libraries are specific to the ESP8266 and ESP32.
Libraries specific to the RP2040
The following libraries are specific to the RP2040, as used in the Raspberry Pi Pico.
Libraries specific to Zephyr
The following libraries are specific to the Zephyr port.
Extending built-in libraries from Python
A subset of the built-in modules are able to be extended by Python code byproviding a module of the same name in the filesystem. This extensibilityapplies to the following Python standard library modules which are built-in tothe firmware:array,binascii,collections,errno,gzip,hashlib,heapq,io,json,os,platform,random,re,select,socket,ssl,struct,timezlib, as wellas the MicroPython-specificmachine module. All other built-in modulescannot be extended from the filesystem.
This allows the user to provide an extended implementation of a built-in library(perhaps to provide additional CPython compatibility or missing functionality).This is used extensively inmicropython-lib, seePackage management formore information. The filesystem module will typically do a wildcard import ofthe built-in module in order to inherit all the globals (classes, functions andvariables) from the built-in.
In MicroPython v1.21.0 and higher, to prevent the filesystem module fromimporting itself, it can force an import of the built-in module it bytemporarily clearingsys.path during the import. For example, to extend thetime module from Python, a file namedtime.py on the filesystem woulddo the following:
_path=sys.pathsys.path=()try:fromtimeimport*finally:sys.path=_pathdel_pathdefextra_method():pass
The result is thattime.py contains all the globals of the built-intimemodule, but addsextra_method.
In earlier versions of MicroPython, you can force an import of a built-in moduleby appending au to the start of its name. For example,importutimeinstead ofimporttime. For example,time.py on the filesystem couldlook like:
fromutimeimport*defextra_method():pass
This way is still supported, but thesys.path method described above is nowpreferred as theu-prefix will be removed from the names of built-inmodules in a future version of MicroPython.
Other than when it specifically needs to force the use of the built-in module,code should always useimportmodulerather thanimportumodule.