micropython: add micropython component

components/language/micropython/docs/library/index.rst

@@ -0,0 +1,198 @@
+.. _micropython_lib:
+
+MicroPython libraries
+=====================
+
+.. warning::
+
+   Important summary of this section
+
+   * MicroPython provides built-in modules that mirror the functionality of the
+     Python standard library (e.g. :mod:`os`, :mod:`time`), as well as
+     MicroPython-specific modules (e.g. :mod:`bluetooth`, :mod:`machine`).
+   * Most 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, the built-in modules can be extended from
+     Python code loaded onto the device.
+
+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`.
+
+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-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
+
+
+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
+
+Extending built-in libraries from Python
+----------------------------------------
+
+In most cases, the above modules are actually named ``umodule`` rather than
+``module``, but MicroPython will alias any module prefixed with a ``u`` to the
+non-``u`` version. However a file (or :term:`frozen module`) named
+``module.py`` will take precedence over this alias.
+
+This allows the user to provide an extended implementation of a built-in library
+(perhaps to provide additional CPython compatibility). The user-provided module
+(in ``module.py``) can still use the built-in functionality by importing
+``umodule`` directly. This is used extensively in :term:`micropython-lib`. See
+:ref:`packages` for more information.
+
+This applies to both the Python standard libraries (e.g. ``os``, ``time``, etc),
+but also the MicroPython libraries too (e.g. ``machine``, ``bluetooth``, etc).
+The main exception is the port-specific libraries (``pyb``, ``esp``, etc).
+
+*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``.*