1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
.. _micropython_lib:
MicroPython libraries
=====================
.. warning::
Important summary of this section
* MicroPython provides built-in modules that mirror the functionality of the
:ref:`Python standard library <micropython_lib_python>` (e.g. :mod:`os`,
:mod:`time`), as well as :ref:`MicroPython-specific modules <micropython_lib_micropython>`
(e.g. :mod:`bluetooth`, :mod:`machine`).
* Most Python standard library modules implement a subset of the
functionality of the equivalent Python module, and in a few cases provide
some MicroPython-specific extensions (e.g. :mod:`array`, :mod:`os`)
* Due to resource constraints or other limitations, some ports or firmware
versions may not include all the functionality documented here.
* To allow for extensibility, some built-in modules can be
:ref:`extended from Python code <micropython_lib_extending>` loaded onto
the device filesystem.
This chapter describes modules (function and class libraries) which are built
into MicroPython. This documentation in general aspires to describe all modules
and functions/classes which are implemented in the MicroPython project.
However, MicroPython is highly configurable, and each port to a particular
board/embedded system may include only a subset of the available MicroPython
libraries.
With that in mind, please be warned that some functions/classes in a module (or
even the entire module) described in this documentation **may be unavailable**
in a particular build of MicroPython on a particular system. The best place to
find general information of the availability/non-availability of a particular
feature is the "General Information" section which contains information
pertaining to a specific :term:`MicroPython port`.
On some ports you are able to discover the available, built-in libraries that
can be imported by entering the following at the :term:`REPL`::
help('modules')
Beyond the built-in libraries described in this documentation, many more
modules from the Python standard library, as well as further MicroPython
extensions to it, can be found in :term:`micropython-lib`.
.. _micropython_lib_python:
Python standard libraries and micro-libraries
---------------------------------------------
The following standard Python libraries have been "micro-ified" to fit in with
the philosophy of MicroPython. They provide the core functionality of that
module and are intended to be a drop-in replacement for the standard Python
library.
.. toctree::
:maxdepth: 1
array.rst
binascii.rst
builtins.rst
cmath.rst
collections.rst
errno.rst
gc.rst
hashlib.rst
heapq.rst
io.rst
json.rst
math.rst
os.rst
random.rst
re.rst
select.rst
socket.rst
ssl.rst
struct.rst
sys.rst
time.rst
uasyncio.rst
zlib.rst
_thread.rst
.. _micropython_lib_micropython:
MicroPython-specific libraries
------------------------------
Functionality specific to the MicroPython implementation is available in
the following libraries.
.. toctree::
:maxdepth: 1
bluetooth.rst
btree.rst
cryptolib.rst
framebuf.rst
machine.rst
micropython.rst
neopixel.rst
network.rst
uctypes.rst
The following libraries provide drivers for hardware components.
.. toctree::
:maxdepth: 1
wm8960.rst
Port-specific libraries
-----------------------
In some cases the following port/board-specific libraries have functions or
classes similar to those in the :mod:`machine` library. Where this occurs, the
entry in the port specific library exposes hardware functionality unique to
that platform.
To write portable code use functions and classes from the :mod:`machine` module.
To access platform-specific hardware use the appropriate library, e.g.
:mod:`pyb` in the case of the Pyboard.
Libraries specific to the pyboard
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following libraries are specific to the pyboard.
.. toctree::
:maxdepth: 2
pyb.rst
stm.rst
lcd160cr.rst
Libraries specific to the WiPy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following libraries and classes are specific to the WiPy.
.. toctree::
:maxdepth: 2
wipy.rst
machine.ADCWiPy.rst
machine.TimerWiPy.rst
Libraries specific to the ESP8266 and ESP32
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following libraries are specific to the ESP8266 and ESP32.
.. toctree::
:maxdepth: 2
esp.rst
esp32.rst
.. toctree::
:maxdepth: 1
espnow.rst
Libraries specific to the RP2040
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following libraries are specific to the RP2040, as used in the Raspberry Pi Pico.
.. toctree::
:maxdepth: 2
rp2.rst
Libraries specific to Zephyr
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following libraries are specific to the Zephyr port.
.. toctree::
:maxdepth: 2
zephyr.rst
.. _micropython_lib_extending:
Extending built-in libraries from Python
----------------------------------------
Many built-in modules are actually named ``umodule`` rather than ``module``, but
MicroPython will alias any module prefixed with a ``u`` to the non-``u``
version. This means that, for example, ``import time`` will first attempt to
resolve from the filesystem, and then failing that will fall back to the
built-in ``utime``. On the other hand, ``import utime`` will always go directly
to the built-in.
This allows the user to provide an extended implementation of a built-in library
(perhaps to provide additional CPython compatibility or missing functionality).
The user-provided module (in ``module.py``) can still use the built-in
functionality by importing ``umodule`` directly (e.g. typically an extension
module ``time.py`` will do ``from utime import *``). This is used extensively
in :term:`micropython-lib`. See :ref:`packages` for more information.
This extensibility applies to the following Python standard library modules
which are built-in to the firmware: ``array``, ``binascii``, ``collections``,
``errno``, ``hashlib``, ``heapq``, ``io``, ``json``, ``os``, ``platform``,
``random``, ``re``, ``select``, ``socket``, ``ssl``, ``struct``, ``sys``,
``time``, ``zlib``, as well as the MicroPython-specific libraries: ``bluepy``,
``bluetooth``, ``machine``, ``timeq``, ``websocket``. All other built-in
modules cannot be extended from the filesystem.
*Other than when you specifically want to force the use of the built-in module,
we recommend always using* ``import module`` *rather than* ``import umodule``.
**Note:** In MicroPython v1.21.0 and higher, it is now possible to force an
import of the built-in module by clearing ``sys.path`` during the import. For
example, in ``time.py``, you can write::
_path = sys.path
sys.path = ()
try:
from time import *
finally:
sys.path = _path
del _path
This is now the preferred way (instead of ``from utime import *``), as the
``u``-prefix will be removed from the names of built-in modules in a future
version of MicroPython.
|