Merge remote-tracking branch 'upstream/master' into PWM_and_Time_hard…

…ware_pulse_and_Test

.github/workflows/ports_windows.yml

@@ -110,6 +110,11 @@ jobs:
       run:
         shell: msys2 {0}
     steps:
+    - uses: actions/setup-python@v5
+      # note: can go back to installing mingw-w64-${{ matrix.env }}-python after
+      # MSYS2 updates to Python >3.12 (due to settrace compatibility issue)
+      with:
+        python-version: '3.11'
     - uses: msys2/setup-msys2@v2
       with:
         msystem: ${{ matrix.sys }}
@@ -118,9 +123,9 @@ jobs:
           make
           mingw-w64-${{ matrix.env }}-gcc
           pkg-config
-          mingw-w64-${{ matrix.env }}-python3
           git
           diffutils
+        path-type: inherit  # Remove when setup-python is removed
     - uses: actions/checkout@v4
     - name: Build mpy-cross.exe
       run: make -C mpy-cross -j2

docs/conf.py

@@ -36,6 +36,9 @@
     "is_release": micropy_version != "latest",
 }
 
+# Authors used in various parts of the documentation.
+micropy_authors = "MicroPython authors and contributors"
+
 
 # -- General configuration ------------------------------------------------
 
@@ -68,7 +71,7 @@
 
 # General information about the project.
 project = "MicroPython"
-copyright = "- The MicroPython Documentation is Copyright © 2014-2024, Damien P. George, Paul Sokolovsky, and contributors"
+copyright = "- The MicroPython Documentation is Copyright © 2014-2024, " + micropy_authors
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -244,7 +247,7 @@
         master_doc,
         "MicroPython.tex",
         "MicroPython Documentation",
-        "Damien P. George, Paul Sokolovsky, and contributors",
+        micropy_authors,
         "manual",
     ),
 ]
@@ -281,7 +284,7 @@
         "index",
         "micropython",
         "MicroPython Documentation",
-        ["Damien P. George, Paul Sokolovsky, and contributors"],
+        [micropy_authors],
         1,
     ),
 ]
@@ -300,7 +303,7 @@
         master_doc,
         "MicroPython",
         "MicroPython Documentation",
-        "Damien P. George, Paul Sokolovsky, and contributors",
+        micropy_authors,
         "MicroPython",
         "One line description of project.",
         "Miscellaneous",

docs/esp32/quickref.rst

@@ -79,19 +79,19 @@ Networking
 WLAN
 ^^^^
 
-The :mod:`network` module::
+The :class:`network.WLAN` class in the :mod:`network` module::
 
     import network
 
-    wlan = network.WLAN(network.STA_IF) # create station interface
+    wlan = network.WLAN(network.WLAN.IF_STA) # create station interface
     wlan.active(True)       # activate the interface
     wlan.scan()             # scan for access points
     wlan.isconnected()      # check if the station is connected to an AP
     wlan.connect('ssid', 'key') # connect to an AP
     wlan.config('mac')      # get the interface's MAC address
     wlan.ipconfig('addr4')  # get the interface's IPv4 addresses
 
-    ap = network.WLAN(network.AP_IF) # create access-point interface
+    ap = network.WLAN(network.WLAN.IF_AP) # create access-point interface
     ap.config(ssid='ESP-AP') # set the SSID of the access point
     ap.config(max_clients=10) # set how many clients can connect to the network
     ap.active(True)         # activate the interface
@@ -100,7 +100,7 @@ A useful function for connecting to your local WiFi network is::
 
     def do_connect():
         import network
-        wlan = network.WLAN(network.STA_IF)
+        wlan = network.WLAN(network.WLAN.IF_STA)
         wlan.active(True)
         if not wlan.isconnected():
             print('connecting to network...')
@@ -124,7 +124,8 @@ to reconnect forever).
 LAN
 ^^^
 
-To use the wired interfaces one has to specify the pins and mode ::
+To use the wired interfaces via :class:`network.LAN` one has to specify the pins
+and mode ::
 
     import network
 
@@ -770,20 +771,33 @@ APA102 (DotStar) uses a different driver as it has an additional clock pin.
 Capacitive touch
 ----------------
 
-Use the ``TouchPad`` class in the ``machine`` module::
+ESP32, ESP32-S2 and ESP32-S3 support capacitive touch via the ``TouchPad`` class
+in the ``machine`` module::
 
     from machine import TouchPad, Pin
 
     t = TouchPad(Pin(14))
     t.read()              # Returns a smaller number when touched
 
-``TouchPad.read`` returns a value relative to the capacitive variation. Small numbers (typically in
-the *tens*) are common when a pin is touched, larger numbers (above *one thousand*) when
-no touch is present. However the values are *relative* and can vary depending on the board
-and surrounding composition so some calibration may be required.
-
-There are ten capacitive touch-enabled pins that can be used on the ESP32: 0, 2, 4, 12, 13
-14, 15, 27, 32, 33. Trying to assign to any other pins will result in a ``ValueError``.
+``TouchPad.read`` returns a value proportional to the capacitance between the
+pin and the board's Ground connection. On ESP32 the number becomes smaller when
+the pin (or connected touch pad) is touched, on ESP32-S2 and ESP32-S3 the number
+becomes larger when the pin is touched.
+
+In all cases, a touch causes a significant change in the return value. Note the
+returned values are *relative* and can vary depending on the board and
+surrounding environment so some calibration (i.e. comparison to a baseline or
+rolling average) may be required.
+
+========= ==============================================
+Chip      Touch-enabled pins
+--------- ----------------------------------------------
+ESP32     0, 2, 4, 12, 13, 14, 15, 27, 32, 33
+ESP32-S2  1 to 14 inclusive
+ESP32-S3  1 to 14 inclusive
+========= ==============================================
+
+Trying to assign to any other pins will result in a ``ValueError``.
 
 Note that TouchPads can be used to wake an ESP32 from sleep::
 

docs/esp32/tutorial/index.rst

@@ -21,3 +21,4 @@ to `<https://www.python.org>`__.
    intro.rst
    pwm.rst
    peripheral_access.rst
+   reset.rst

docs/esp32/tutorial/intro.rst

@@ -50,6 +50,8 @@ features, there are daily builds.  If your board has SPIRAM support you can
 use either the standard firmware or the firmware with SPIRAM support, and in
 the latter case you will have access to more RAM for Python objects.
 
+.. _esp32_flashing:
+
 Deploying the firmware
 ----------------------
 

docs/esp32/tutorial/reset.rst

@@ -0,0 +1,25 @@
+Factory reset
+=============
+
+If something unexpected happens and your ESP32-based board no longer boots
+MicroPython, then you may have to factory reset it. For more details, see
+:ref:`soft_bricking`.
+
+Factory resetting the MicroPython esp32 port involves fully erasing the flash
+and resetting the flash memory, so you will need to re-flash the MicroPython
+firmware afterwards and copy any Python files to the filesystem again.
+
+1. You will need the Espressif `esptool`_ installed on your system. This is the
+   same tool that you may have used to initially install MicroPython on your
+   board (see :ref:`installation instructions <esp32_flashing>`).
+2. Find the serial port name of your board, and then use esptool to erase the
+   entire flash contents::
+
+       esptool.py -p PORTNAME erase_flash
+
+3. Use esptool to flash the MicroPython file to your board again. If needed,
+   this file and flashing instructions can be found on the `MicroPython
+   downloads page`_.
+
+.. _esptool: https://github.com/espressif/esptool
+.. _MicroPython downloads page: https://micropython.org/download/?port=esp32

docs/esp8266/general.rst

@@ -74,40 +74,7 @@ as possible after use.
 Boot process
 ------------
 
-On boot, MicroPython EPS8266 port executes ``_boot.py`` script from internal
-frozen modules. It mounts filesystem in FlashROM, or if it's not available,
-performs first-time setup of the module and creates the filesystem. This
-part of the boot process is considered fixed, and not available for customization
-for end users (even if you build from source, please refrain from changes to
-it; customization of early boot process is available only to advanced users
-and developers, who can diagnose themselves any issues arising from
-modifying the standard process).
-
-Once the filesystem is mounted, ``boot.py`` is executed from it. The standard
-version of this file is created during first-time module set up and has
-commands to start a WebREPL daemon (disabled by default, configurable
-with ``webrepl_setup`` module), etc. This
-file is customizable by end users (for example, you may want to set some
-parameters or add other services which should be run on
-a module start-up). But keep in mind that incorrect modifications to boot.py
-may still lead to boot loops or lock ups, requiring to reflash a module
-from scratch. (In particular, it's recommended that you use either
-``webrepl_setup`` module or manual editing to configure WebREPL, but not
-both).
-
-As a final step of boot procedure, ``main.py`` is executed from filesystem,
-if exists. This file is a hook to start up a user application each time
-on boot (instead of going to REPL). For small test applications, you may
-name them directly as ``main.py``, and upload to module, but instead it's
-recommended to keep your application(s) in separate files, and have just
-the following in ``main.py``::
-
-    import my_app
-    my_app.main()
-
-This will allow to keep the structure of your application clear, as well as
-allow to install multiple applications on a board, and switch among them.
-
+See :doc:`/reference/reset_boot`.
 
 Known Issues
 ------------

docs/esp8266/quickref.rst

@@ -49,27 +49,27 @@ The :mod:`esp` module::
 Networking
 ----------
 
-The :mod:`network` module::
+The :class:`network.WLAN` class in the :mod:`network` module::
 
     import network
 
-    wlan = network.WLAN(network.STA_IF) # create station interface
+    wlan = network.WLAN(network.WLAN.IF_STA) # create station interface
     wlan.active(True)       # activate the interface
     wlan.scan()             # scan for access points
     wlan.isconnected()      # check if the station is connected to an AP
     wlan.connect('ssid', 'key') # connect to an AP
     wlan.config('mac')      # get the interface's MAC address
     wlan.ipconfig('addr4')  # get the interface's IPv4 addresses
 
-    ap = network.WLAN(network.AP_IF) # create access-point interface
+    ap = network.WLAN(network.WLAN.IF_AP) # create access-point interface
     ap.active(True)         # activate the interface
     ap.config(ssid='ESP-AP') # set the SSID of the access point
 
 A useful function for connecting to your local WiFi network is::
 
     def do_connect():
         import network
-        wlan = network.WLAN(network.STA_IF)
+        wlan = network.WLAN(network.WLAN.IF_STA)
         wlan.active(True)
         if not wlan.isconnected():
             print('connecting to network...')
@@ -163,10 +163,10 @@ sys.stdin.read() if it's needed to read characters from the UART(0)
 while it's also used for the REPL (or detach, read, then reattach).
 When detached the UART(0) can be used for other purposes.
 
-If there are no objects in any of the dupterm slots when the REPL is
-started (on hard or soft reset) then UART(0) is automatically attached.
-Without this, the only way to recover a board without a REPL would be to
-completely erase and reflash (which would install the default boot.py which
+If there are no objects in any of the dupterm slots when the REPL is started (on
+:doc:`hard or soft reset </reference/reset_boot>`) then UART(0) is automatically
+attached. Without this, the only way to recover a board without a REPL would be
+to completely erase and reflash (which would install the default boot.py which
 attaches the REPL).
 
 To detach the REPL from UART0, use::

docs/esp8266/tutorial/network_basics.rst

@@ -1,14 +1,15 @@
 Network basics
 ==============
 
-The network module is used to configure the WiFi connection.  There are two WiFi
-interfaces, one for the station (when the ESP8266 connects to a router) and one
-for the access point (for other devices to connect to the ESP8266).  Create
+The :class:`network.WLAN` class in the :mod:`network` module is used to
+configure the WiFi connection.  There are two WiFi interfaces, one for
+the station (when the ESP8266 connects to a router) and one for the
+access point (for other devices to connect to the ESP8266).  Create
 instances of these objects using::
 
     >>> import network
-    >>> sta_if = network.WLAN(network.STA_IF)
-    >>> ap_if = network.WLAN(network.AP_IF)
+    >>> sta_if = network.WLAN(network.WLAN.IF_STA)
+    >>> ap_if = network.WLAN(network.WLAN.IF_AP)
 
 You can check if the interfaces are active by::
 
@@ -57,7 +58,7 @@ connect to your WiFi network::
 
     def do_connect():
         import network
-        sta_if = network.WLAN(network.STA_IF)
+        sta_if = network.WLAN(network.WLAN.IF_STA)
         if not sta_if.isconnected():
             print('connecting to network...')
             sta_if.active(True)

docs/library/builtins.rst

@@ -170,6 +170,10 @@ Exceptions
 
 .. exception:: KeyboardInterrupt
 
+   |see_cpython| `python:KeyboardInterrupt`.
+
+   See also in the context of :ref:`soft_bricking`.
+
 .. exception:: KeyError
 
 .. exception:: MemoryError
@@ -190,6 +194,12 @@ Exceptions
 
     |see_cpython| `python:SystemExit`.
 
+    On non-embedded ports (i.e. Windows and Unix), an unhandled ``SystemExit``
+    exits the MicroPython process in a similar way to CPython.
+
+    On embedded ports, an unhandled ``SystemExit`` currently causes a
+    :ref:`soft_reset` of MicroPython.
+
 .. exception:: TypeError
 
     |see_cpython| `python:TypeError`.