circuitpython/docs/library/index.rst

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

234 lines
6.8 KiB
ReStructuredText
Raw Normal View History

.. _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
esp32,esp8266: Add support for the Espressif ESP-NOW protocol. ESP-NOW is a proprietary wireless communication protocol which supports connectionless communication between ESP32 and ESP8266 devices, using vendor specific WiFi frames. This commit adds support for this protocol through a new `espnow` module. This commit builds on original work done by @nickzoic, @shawwwn and with contributions from @zoland. Features include: - Use of (extended) ring buffers in py/ringbuf.[ch] for robust IO. - Signal strength (RSSI) monitoring. - Core support in `_espnow` C module, extended by `espnow.py` module. - Asyncio support via `aioespnow.py` module (separate to this commit). - Docs provided at `docs/library/espnow.rst`. Methods available in espnow.ESPNow class are: - active(True/False) - config(): set rx buffer size, read timeout and tx rate - recv()/irecv()/recvinto() to read incoming messages from peers - send() to send messages to peer devices - any() to test if a message is ready to read - irq() to set callback for received messages - stats() returns transfer stats: (tx_pkts, tx_pkt_responses, tx_failures, rx_pkts, lost_rx_pkts) - add_peer(mac, ...) registers a peer before sending messages - get_peer(mac) returns peer info: (mac, lmk, channel, ifidx, encrypt) - mod_peer(mac, ...) changes peer info parameters - get_peers() returns all peer info tuples - peers_table supports RSSI signal monitoring for received messages: {peer1: [rssi, time_ms], peer2: [rssi, time_ms], ...} ESP8266 is a pared down version of the ESP32 ESPNow support due to code size restrictions and differences in the low-level API. See docs for details. Also included is a test suite in tests/multi_espnow. This tests basic espnow data transfer, multiple transfers, various message sizes, encrypted messages (pmk and lmk), and asyncio support. Initial work is from https://github.com/micropython/micropython/pull/4115. Initial import of code is from: https://github.com/nickzoic/micropython/tree/espnow-4115.
2020-09-24 01:37:04 -04:00
.. 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.