Merge branch 'adafruit:main' into main

Author: PontusO

.gitmodules

@@ -307,3 +307,6 @@
 [submodule "frozen/circuitpython_picoed"]
 	path = frozen/circuitpython_picoed
 	url = https://github.com/elecfreaks/circuitpython_picoed.git
+[submodule "ports/espressif/esp32-camera"]
+	path = ports/espressif/esp32-camera
+	url = https://github.com/adafruit/esp32-camera/

LICENSE

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2013-2022 Damien P. George
+Copyright (c) 2013-2022 Damien P. George and others
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,77 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-
---------------------------------------------------------------------------------
-
-Unless specified otherwise (see below), the above license and copyright applies
-to all files in this repository.
-
-Individual files may include additional copyright holders.
-
-The various ports of MicroPython may include third-party software that is
-licensed under different terms. These licenses are summarised in the tree
-below, please refer to these files and directories for further license and
-copyright information. Note that (L)GPL-licensed code listed below is only
-used during the build process and is not part of the compiled source code.
-
-/ (MIT)
-    /drivers
-        /cc3000 (BSD-3-clause)
-        /cc3100 (BSD-3-clause)
-        /wiznet5k (BSD-3-clause)
-    /lib
-        /asf4 (Apache-2.0)
-        /axtls (BSD-3-clause)
-            /config
-                /scripts
-                    /config (GPL-2.0-or-later)
-                /Rules.mak (GPL-2.0)
-        /berkeley-db-1xx (BSD-4-clause)
-        /btstack (See btstack/LICENSE)
-        /cmsis (BSD-3-clause)
-        /crypto-algorithms (NONE)
-        /libhydrogen (ISC)
-        /littlefs (BSD-3-clause)
-        /lwip (BSD-3-clause)
-        /mynewt-nimble (Apache-2.0)
-        /nrfx (BSD-3-clause)
-        /nxp_driver (BSD-3-Clause)
-        /oofatfs (BSD-1-clause)
-        /pico-sdk (BSD-3-clause)
-        /re15 (BSD-3-clause)
-        /stm32lib (BSD-3-clause)
-        /tinytest (BSD-3-clause)
-        /tinyusb (MIT)
-        /uzlib (Zlib)
-    /logo (uses OFL-1.1)
-    /ports
-        /cc3200
-            /hal (BSD-3-clause)
-            /simplelink (BSD-3-clause)
-            /FreeRTOS (GPL-2.0 with FreeRTOS exception)
-        /stm32
-            /usbd*.c (MCD-ST Liberty SW License Agreement V2)
-            /stm32_it.* (MIT + BSD-3-clause)
-            /system_stm32*.c (MIT + BSD-3-clause)
-            /boards
-                /startup_stm32*.s (BSD-3-clause)
-                /*/stm32*.h (BSD-3-clause)
-            /usbdev (MCD-ST Liberty SW License Agreement V2)
-            /usbhost (MCD-ST Liberty SW License Agreement V2)
-        /teensy
-            /core (PJRC.COM)
-        /zephyr
-            /src (Apache-2.0)
-    /tools
-        /dfu.py (LGPL-3.0-only)
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LICENSE_MicroPython

@@ -0,0 +1,85 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-2022 Damien P. George
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+Unless specified otherwise (see below), the above license and copyright applies
+to all files in this repository.
+
+Individual files may include additional copyright holders.
+
+The various ports of MicroPython may include third-party software that is
+licensed under different terms. These licenses are summarised in the tree
+below, please refer to these files and directories for further license and
+copyright information. Note that (L)GPL-licensed code listed below is only
+used during the build process and is not part of the compiled source code.
+
+/ (MIT)
+    /drivers
+        /cc3000 (BSD-3-clause)
+        /cc3100 (BSD-3-clause)
+        /wiznet5k (BSD-3-clause)
+    /lib
+        /asf4 (Apache-2.0)
+        /axtls (BSD-3-clause)
+            /config
+                /scripts
+                    /config (GPL-2.0-or-later)
+                /Rules.mak (GPL-2.0)
+        /berkeley-db-1xx (BSD-4-clause)
+        /btstack (See btstack/LICENSE)
+        /cmsis (BSD-3-clause)
+        /crypto-algorithms (NONE)
+        /libhydrogen (ISC)
+        /littlefs (BSD-3-clause)
+        /lwip (BSD-3-clause)
+        /mynewt-nimble (Apache-2.0)
+        /nrfx (BSD-3-clause)
+        /nxp_driver (BSD-3-Clause)
+        /oofatfs (BSD-1-clause)
+        /pico-sdk (BSD-3-clause)
+        /re15 (BSD-3-clause)
+        /stm32lib (BSD-3-clause)
+        /tinytest (BSD-3-clause)
+        /tinyusb (MIT)
+        /uzlib (Zlib)
+    /logo (uses OFL-1.1)
+    /ports
+        /cc3200
+            /hal (BSD-3-clause)
+            /simplelink (BSD-3-clause)
+            /FreeRTOS (GPL-2.0 with FreeRTOS exception)
+        /stm32
+            /usbd*.c (MCD-ST Liberty SW License Agreement V2)
+            /stm32_it.* (MIT + BSD-3-clause)
+            /system_stm32*.c (MIT + BSD-3-clause)
+            /boards
+                /startup_stm32*.s (BSD-3-clause)
+                /*/stm32*.h (BSD-3-clause)
+            /usbdev (MCD-ST Liberty SW License Agreement V2)
+            /usbhost (MCD-ST Liberty SW License Agreement V2)
+        /teensy
+            /core (PJRC.COM)
+        /zephyr
+            /src (Apache-2.0)
+    /tools
+        /dfu.py (LGPL-3.0-only)

conf.py

@@ -199,6 +199,7 @@ def autoapi_prepare_jinja_env(jinja_env):
                     "ports/cxd56/spresense-exported-sdk",
                     "ports/espressif/certificates",
                     "ports/espressif/esp-idf",
+                    "ports/espressif/esp32-camera",
                     "ports/espressif/.idf_tools",
                     "ports/espressif/peripherals",
                     "ports/litex/hw",

license.rst renamed to docs/LICENSE.md

@@ -1,9 +1,8 @@
-MicroPython & CircuitPython license information
-===============================================
+# MicroPython & CircuitPython License
 
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2013-2017 Damien P. George, and others
+Copyright (c) 2013-2022 Damien P. George and others
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -12,13 +11,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/design_guide.rst

@@ -141,7 +141,7 @@ statement will ensure hardware isn't enabled longer than needed.
 Verify your device
 --------------------------------------------------------------------------------
 
-Whenever possible, make sure device you are talking to is the device you expect.
+Whenever possible, make sure the device you are talking to is the device you expect.
 If not, raise a RuntimeError. Beware that I2C addresses can be identical on
 different devices so read registers you know to make sure they match your
 expectation. Validating this upfront will help catch mistakes.
@@ -202,7 +202,7 @@ interchangeably with the CPython name. This is confusing. Instead, think up a
 new name that is related to the extra functionality you are adding.
 
 For example, storage mounting and unmounting related functions were moved from
-``uos`` into a new `storage` module. Terminal related functions were moved into
+``uos`` into a new `storage` module. Terminal-related functions were moved into
 `multiterminal`. These names better match their functionality and do not
 conflict with CPython names. Make sure to check that you don't conflict with
 CPython libraries too. That way we can port the API to CPython in the future.
@@ -213,7 +213,7 @@ Example
 When adding extra functionality to CircuitPython to mimic what a normal
 operating system would do, either copy an existing CPython API (for example file
 writing) or create a separate module to achieve what you want. For example,
-mounting and unmount drives is not a part of CPython so it should be done in a
+mounting and unmounting drives is not a part of CPython so it should be done in a
 module, such as a new ``storage`` module, that is only available in CircuitPython.
 That way when someone moves the code to CPython they know what parts need to be
 adapted.
@@ -494,6 +494,45 @@ backticks  ``:class:`~adafruit_motor.servo.Servo```. You must also add the refer
 
     "adafruit_motor": ("https://circuitpython.readthedocs.io/projects/motor/en/latest/", None,),
 
+Use ``adafruit_register`` when possible
+--------------------------------------------------------------------------------
+`Register <https://github.com/adafruit/Adafruit_CircuitPython_Register>`_ is
+a foundational library that manages packing and unpacking data from I2C device
+registers. There is also `Register SPI <https://github.com/adafruit/Adafruit_CircuitPython_Register_SPI>`_
+for SPI devices. When possible, use one of these libraries for unpacking and
+packing registers. This ensures the packing code is shared amongst all
+registers (even across drivers). Furthermore, it simplifies device definitions
+by making them declarative (only data.)
+
+Values with non-consecutive bits in a register or that represent FIFO endpoints
+may not map well to existing register classes. In unique cases like these, it is
+ok to read and write the register directly.
+
+*Do not* add all registers from a datasheet upfront. Instead, only add the ones
+necessary for the functionality the driver exposes. Adding them all will lead to
+unnecessary file size and API clutter. See `this video about outside-in design
+from @tannewt <https://www.youtube.com/watch?v=3QewiyfBQh8>`_.
+
+I2C Example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+  from adafruit_register import i2c_bit
+  from adafruit_bus_device import i2c_device
+
+  class HelloWorldDevice:
+      """Device with two bits to control when the words 'hello' and 'world' are lit."""
+
+      hello = i2c_bit.RWBit(0x0, 0x0)
+      """Bit to indicate if hello is lit."""
+
+      world = i2c_bit.RWBit(0x1, 0x0)
+      """Bit to indicate if world is lit."""
+
+      def __init__(self, i2c, device_address=0x0):
+          self.i2c_device = i2c_device.I2CDevice(i2c, device_address)
+
 Use BusDevice
 --------------------------------------------------------------------------------
 
@@ -668,8 +707,24 @@ when using ``const()``, keep in mind these general guide lines:
 
 - Always use via an import, ex: ``from micropython import const``
 - Limit use to global (module level) variables only.
-- If user will not need access to variable, prefix name with a leading
-  underscore, ex: ``_SOME_CONST``.
+- Only used when the user will not need access to variable and prefix name with
+  a leading underscore, ex: ``_SOME_CONST``.
+
+Example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+  from adafruit_bus_device import i2c_device
+  from micropython import const
+
+  _DEFAULT_I2C_ADDR = const(0x42)
+
+  class Widget:
+      """A generic widget."""
+
+      def __init__(self, i2c, address=_DEFAULT_I2C_ADDR):
+          self.i2c_device = i2c_device.I2CDevice(i2c, address)
 
 Libraries Examples
 ------------------
@@ -751,6 +806,16 @@ properties.
 | ``sound_level``       | float                 | non-unit-specific sound level (monotonic but not actual decibels)       |
 +-----------------------+-----------------------+-------------------------------------------------------------------------+
 
+Driver constant naming
+--------------------------------------------------------------------------------
+
+When adding variables for constant values for a driver. Do not include the
+device's name in the variable name. For example, in ``adafruit_fancy123.py``,
+variables should not start with ``FANCY123_``. Adding this prefix increases RAM
+usage and .mpy file size because variable names are preserved. User code should
+refer to these constants as ``adafruit_fancy123.HELLO_WORLD`` for clarity.
+``adafruit_fancy123.FANCY123_HELLO_WORLD`` would be overly verbose.
+
 Adding native modules
 --------------------------------------------------------------------------------
 

docs/environment.rst

@@ -35,6 +35,12 @@ CIRCUITPY_BLE_NAME
 ~~~~~~~~~~~~~~~~~~
 Default BLE name the board advertises as, including for the BLE workflow.
 
+CIRCUITPY_RESERVED_PSRAM
+~~~~~~~~~~~~~~~~~~~~~~~~
+On boards with Espressif microcontrollers with PSRAM (also called SPIRAM), permanently reserve a portion of PSRAM for use by esp-idf.
+This storage is removed from the CircuitPython "heap" and is available for allocation by esp-idf routines in the core instead.
+Generally, only set this to a non-zero value when it is required by a specific core module.
+
 CIRCUITPY_WEB_API_PASSWORD
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 Password required to make modifications to the board from the Web Workflow.

docs/index.rst

@@ -48,7 +48,7 @@ Full Table of Contents
    ../CONTRIBUTING
    ../BUILDING
    ../CODE_OF_CONDUCT
-   ../license.rst
+   ../docs/LICENSE
    ../WEBUSB_README
 
 Indices and tables

docs/porting.rst

@@ -71,7 +71,7 @@ as a natural "TODO" list. An example minimal build list is shown below:
     CIRCUITPY_SDCARDIO = 0
     CIRCUITPY_FRAMEBUFFERIO = 0
     CIRCUITPY_FREQUENCYIO = 0
-    CIRCUITPY_I2CPERIPHERAL = 0
+    CIRCUITPY_I2CTARGET = 0
     # Requires SPI, PulseIO (stub ok):
     CIRCUITPY_DISPLAYIO = 0
 

docs/shared_bindings_matrix.py

@@ -40,7 +40,6 @@
     "pybadge": ["edgebadge"],
     "pyportal": ["pyportal_pynt"],
     "gemma_m0": ["gemma_m0_pycon2018"],
-    "pewpew10": ["pewpew13"],
 }
 
 ALIASES_BRAND_NAMES = {
@@ -54,8 +53,6 @@
         "Adafruit PyPortal Pynt",
     "gemma_m0_pycon2018":
         "Adafruit Gemma M0 PyCon 2018",
-    "pewpew13":
-        "PewPew 13",
 }
 
 ADDITIONAL_MODULES = {