micropython · dpgeorge · Nov 19, 2024 · Oct 2, 2024 · Oct 2, 2024 · Oct 2, 2024
diff --git a/docs/esp32/tutorial/index.rst b/docs/esp32/tutorial/index.rst
@@ -21,3 +21,4 @@ to `<https://www.python.org>`__.
    intro.rst
    pwm.rst
    peripheral_access.rst
+   reset.rst
diff --git a/docs/esp32/tutorial/intro.rst b/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
 ----------------------
 

diff --git a/docs/esp32/tutorial/reset.rst b/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
diff --git a/docs/esp8266/general.rst b/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
 ------------

diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst
@@ -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::

diff --git a/docs/library/builtins.rst b/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`.

diff --git a/docs/library/machine.RTC.rst b/docs/library/machine.RTC.rst
@@ -83,7 +83,7 @@ Methods
    a `bytes` object.
 
    Data written to RTC user memory is persistent across restarts, including
-   `machine.soft_reset()` and `machine.deepsleep()`.
+   :ref:`soft_reset` and `machine.deepsleep()`.
 
    The maximum length of RTC user memory is 2048 bytes by default on esp32,
    and 492 bytes on esp8266.

diff --git a/docs/library/machine.USBDevice.rst b/docs/library/machine.USBDevice.rst
@@ -32,10 +32,10 @@ Managing a runtime USB interface can be tricky, especially if you are communicat
 with MicroPython over a built-in USB-CDC serial port that's part of the same USB
 device.
 
-- A MicroPython soft reset will always clear all runtime USB interfaces, which
-  results in the entire USB device disconnecting from the host. If MicroPython
-  is also providing a built-in USB-CDC serial port then this will re-appear
-  after the soft reset.
+- A MicroPython :ref:`soft reset <soft_reset>` will always clear all runtime USB
+  interfaces, which results in the entire USB device disconnecting from the
+  host. If MicroPython is also providing a built-in USB-CDC serial port then
+  this will re-appear after the soft reset.
 
   This means some functions (like ``mpremote run``) that target the USB-CDC
   serial port will immediately fail if a runtime USB interface is active,
@@ -44,9 +44,9 @@ device.
   no more runtime USB interface.
 
 - To configure a runtime USB device on every boot, it's recommended to place the
-  configuration code in the ``boot.py`` file on the :ref:`device VFS
+  configuration code in the :ref:`boot.py` file on the :ref:`device VFS
   <filesystem>`. On each reset this file is executed before the USB subsystem is
-  initialised (and before ``main.py``), so it allows the board to come up with the runtime
+  initialised (and before :ref:`main.py`), so it allows the board to come up with the runtime
   USB device immediately.
 
 - For development or debugging, it may be convenient to connect a hardware

diff --git a/docs/library/machine.rst b/docs/library/machine.rst
@@ -62,14 +62,13 @@ Reset related functions
 
 .. function:: reset()
 
-   Resets the device in a manner similar to pushing the external RESET
-   button.
+   :ref:`Hard resets <hard_reset>` the device in a manner similar to pushing the
+   external RESET button.
 
 .. function:: soft_reset()
 
-   Performs a soft reset of the interpreter, deleting all Python objects and
-   resetting the Python heap.  It tries to retain the method by which the user
-   is connected to the MicroPython REPL (eg serial, USB, Wifi).
+   Performs a :ref:`soft reset <soft_reset>` of the interpreter, deleting all
+   Python objects and resetting the Python heap.
 
 .. function:: reset_cause()
 

diff --git a/docs/library/pyb.rst b/docs/library/pyb.rst
@@ -147,10 +147,10 @@ Power related functions
    (internal oscillator) directly.  The higher frequencies use the HSE to
    drive the PLL (phase locked loop), and then use the output of the PLL.
 
-   Note that if you change the frequency while the USB is enabled then
-   the USB may become unreliable.  It is best to change the frequency
-   in boot.py, before the USB peripheral is started.  Also note that sysclk
-   frequencies below 36MHz do not allow the USB to function correctly.
+   Note that if you change the frequency while the USB is enabled then the USB
+   may become unreliable. It is best to change the frequency in :ref:`boot.py`,
+   before the USB peripheral is started. Also note that sysclk frequencies below
+   36MHz do not allow the USB to function correctly.
 
 .. function:: wfi()
 
@@ -205,8 +205,9 @@ Miscellaneous functions
 
 .. function:: main(filename)
 
-   Set the filename of the main script to run after boot.py is finished.  If
-   this function is not called then the default file main.py will be executed.
+   Set the filename of the main script to run after :ref:`boot.py` is finished.
+   If this function is not called then the default file :ref:`main.py` will be
+   executed.
 
    It only makes sense to call this function from within boot.py.
 

diff --git a/docs/library/sys.rst b/docs/library/sys.rst
@@ -12,9 +12,12 @@ Functions
 .. function:: exit(retval=0, /)
 
    Terminate current program with a given exit code. Underlyingly, this
-   function raise as `SystemExit` exception. If an argument is given, its
+   function raises a `SystemExit` exception. If an argument is given, its
    value given as an argument to `SystemExit`.
 
+   On embedded ports (i.e. all ports but Windows and Unix), an unhandled
+   `SystemExit` currently causes a :ref:`soft_reset` of MicroPython.
+
 .. function:: atexit(func)
 
    Register *func* to be called upon termination.  *func* must be a callable

diff --git a/docs/pyboard/tutorial/reset.rst b/docs/pyboard/tutorial/reset.rst
@@ -10,6 +10,8 @@ execution of ``boot.py`` and ``main.py`` and gives default USB settings.
 If you have problems with the filesystem you can do a factory reset,
 which restores the filesystem to its original state.
 
+For more information, see :doc:`/reference/reset_boot`.
+
 Safe mode
 ---------
 

diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -21,6 +21,7 @@ implementation and the best practices to use them.
 
    glossary.rst
    repl.rst
+   reset_boot.rst
    mpremote.rst
    mpyfiles.rst
    isr_rules.rst

diff --git a/docs/reference/mpremote.rst b/docs/reference/mpremote.rst
@@ -547,9 +547,9 @@ device at ``/dev/ttyACM1``, printing each result.
 
   mpremote resume exec "print_state_info()" soft-reset
 
-Connect to the device without triggering a soft reset and execute the
-``print_state_info()`` function (e.g. to find out information about the current
-program state), then trigger a soft reset.
+Connect to the device without triggering a :ref:`soft reset <soft_reset>` and
+execute the ``print_state_info()`` function (e.g. to find out information about
+the current program state), then trigger a soft reset.
 
 .. code-block:: bash
 

diff --git a/docs/reference/repl.rst b/docs/reference/repl.rst
@@ -143,10 +143,12 @@ the auto-indent feature, and changes the prompt from ``>>>`` to ``===``. For exa
 Paste Mode allows blank lines to be pasted. The pasted text is compiled as if
 it were a file. Pressing Ctrl-D exits paste mode and initiates the compilation.
 
+.. _repl_soft_reset:
+
 Soft reset
 ----------
 
-A soft reset will reset the python interpreter, but tries not to reset the
+A :ref:`soft_reset` will reset the python interpreter, but tries not to reset the
 method by which you're connected to the MicroPython board (USB-serial, or Wifi).
 
 You can perform a soft reset from the REPL by pressing Ctrl-D, or from your python
@@ -182,6 +184,9 @@ variables no longer exist:
     ['__name__', 'pyb']
     >>>
 
+For more information about reset types and the startup process, see
+:doc:`/reference/reset_boot`.
+
 The special variable _ (underscore)
 -----------------------------------
 
@@ -196,6 +201,8 @@ So you can use the underscore to save the result in a variable. For example:
     15
     >>>
 
+.. _raw_repl:
+
 Raw mode and raw-paste mode
 ---------------------------