Merge branch 'main' into stm-alarm

Author: hierophect

.gitattributes

@@ -11,6 +11,7 @@
 *.bat text eol=crlf
 
 # These are binary so should never be modified by git.
+*.a binary
 *.png binary
 *.jpg binary
 *.dxf binary

.github/workflows/build.yml

@@ -209,6 +209,7 @@ jobs:
         - "clue_nrf52840_express"
         - "cp32-m4"
         - "cp_sapling_m0"
+        - "cp_sapling_m0_revb"
         - "cp_sapling_m0_spiflash"
         - "datalore_ip_m4"
         - "datum_distance"

.gitignore

@@ -28,11 +28,12 @@ dist/
 ######################
 *.swp
 
-# Build directory
+# Build directories
 ######################
 build/
 bin/
 circuitpython-stubs/
+build-*/
 
 # Test failure outputs
 ######################

ACKNOWLEDGEMENTS

@@ -762,7 +762,6 @@ today.  The names appear in order of pledging.
  1642 Udine
  1643 Simon Critchley
  1644 Sven Haiges, Germany
- 1645 Yi Qing Sim
  1646 "silicium" ("silicium_one", if "silicium" is busy)
  1648 Andy O'Malia, @andyomalia
  1650 RedCamelApps.com

devices/ble_hci/common-hal/_bleio/PacketBuffer.c

@@ -245,8 +245,8 @@ mp_int_t common_hal_bleio_packet_buffer_get_outgoing_packet_length(bleio_packet_
             bleio_connection_internal_t *connection = bleio_conn_handle_to_connection(self->conn_handle);
             if (connection) {
                 return MIN(MIN(common_hal_bleio_connection_get_max_packet_length(connection),
-                               self->max_packet_size),
-                           self->characteristic->max_length);
+                    self->max_packet_size),
+                    self->characteristic->max_length);
             }
         }
         // There's no current connection, so we don't know the MTU, and

docs/design_guide.rst

@@ -238,11 +238,34 @@ Module description
 After the license comment::
 
     """
-    `<module name>` - <Short description>
+    `<module name>`
     =================================================
-    <Longer description.>
+
+    <Longer description>
+
+    * Author(s):
+
+    Implementation Notes
+    --------------------
+
+
+    **Hardware:**
+
+    * Adafruit `Device Description
+      <hyperlink>`_ (Product ID: <Product Number>)
+
+    **Software and Dependencies:**
+
+    * Adafruit CircuitPython firmware for the supported boards:
+      https://circuitpython.org/downloads
+    * Adafruit's Bus Device library:
+      https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
+    * Adafruit's Register library:
+      https://github.com/adafruit/Adafruit_CircuitPython_Register
+
     """
 
+
 Class description
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -269,6 +292,58 @@ Renders as:
     :param ~busio.I2C i2c_bus: The I2C bus the DS3231 is connected to.
     :param int address: The I2C address of the device. Defaults to :const:`0x40`
 
+
+Documenting Parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Although there are different ways to document class and functions definitions in Python,
+the following is the prevalent method of documenting parameters
+for CircuitPython libraries. When documenting class parameters you should use the
+following structure:
+
+.. code-block:: sh
+
+    :param param_type param_name: Parameter_description
+
+
+param_type
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The type of the parameter. This could be among other `int`, `float`, `str` `bool`, etc.
+To document an object in the CircuitPython domain, you need to include a ``~`` before the
+definition as shown in the following example:
+
+.. code-block:: sh
+
+    :param ~busio.I2C i2c_bus: The I2C bus the DS3231 is connected to.
+
+
+To include references to CircuitPython modules, cookiecutter creates an entry in the
+intersphinx_mapping section in the ``conf.py`` file located within the ``docs`` directory.
+To add different types outside CircuitPython you need to include them in the intersphinx_mapping::
+
+
+    intersphinx_mapping = {
+        "python": ("https://docs.python.org/3.4", None),
+        "BusDevice":("https://circuitpython.readthedocs.io/projects/busdevice/en/latest/", None,),
+        "CircuitPython": ("https://circuitpython.readthedocs.io/en/latest/", None),
+    }
+
+The intersphinx_mapping above includes references to Python, BusDevice and CircuitPython
+Documentation
+
+
+param_name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Parameter name used in the class or method definition
+
+
+Parameter_description
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Parameter description. When the parameter defaults to a particular value, it is good
+practice to include the default::
+
+    :param int pitch: Pitch value for the servo. Defaults to :const:`4500`
+
+
 Attributes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -383,6 +458,14 @@ Renders as:
 
   :param float degrees: Degrees to turn right
 
+Documentation References to other Libraries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When you need to make references to documentation in other libraries you should refer the class using single
+backticks  ``:class:`~adafruit_motor.servo.Servo```. You must also add the reference in the ``conf.py`` file in the
+``intersphinx_mapping section`` by adding a new entry::
+
+    "adafruit_motor": ("https://circuitpython.readthedocs.io/projects/motor/en/latest/", None,),
+
 Use BusDevice
 --------------------------------------------------------------------------------
 

docs/library/array.rst

@@ -1,5 +1,5 @@
 :mod:`array` -- arrays of numeric data
-======================================
+=======================================
 
 .. module:: array
    :synopsis: efficient arrays of numeric data
@@ -13,7 +13,7 @@ floating-point support).
 Classes
 -------
 
-.. class:: array.array(typecode, [iterable])
+.. class:: array(typecode, [iterable])
 
     Create array with elements of given type. Initial contents of the
     array are given by an `iterable`. If it is not provided, an empty

docs/library/framebuf.rst

@@ -21,7 +21,7 @@ For example::
     import framebuf
 
     # FrameBuffer needs 2 bytes for every RGB565 pixel
-    fbuf = FrameBuffer(bytearray(10 * 100 * 2), 10, 100, framebuf.RGB565)
+    fbuf = framebuf.FrameBuffer(bytearray(10 * 100 * 2), 10, 100, framebuf.RGB565)
 
     fbuf.fill(0)
     fbuf.text('MicroPython!', 0, 0, 0xffff)

docs/library/micropython.rst

@@ -94,3 +94,36 @@ Functions
    This function can be used to prevent the capturing of Ctrl-C on the
    incoming stream of characters that is usually used for the REPL, in case
    that stream is used for other purposes.
+
+.. function:: schedule(func, arg)
+
+   Schedule the function *func* to be executed "very soon".  The function
+   is passed the value *arg* as its single argument.  "Very soon" means that
+   the MicroPython runtime will do its best to execute the function at the
+   earliest possible time, given that it is also trying to be efficient, and
+   that the following conditions hold:
+
+   - A scheduled function will never preempt another scheduled function.
+   - Scheduled functions are always executed "between opcodes" which means
+     that all fundamental Python operations (such as appending to a list)
+     are guaranteed to be atomic.
+   - A given port may define "critical regions" within which scheduled
+     functions will never be executed.  Functions may be scheduled within
+     a critical region but they will not be executed until that region
+     is exited.  An example of a critical region is a preempting interrupt
+     handler (an IRQ).
+
+   A use for this function is to schedule a callback from a preempting IRQ.
+   Such an IRQ puts restrictions on the code that runs in the IRQ (for example
+   the heap may be locked) and scheduling a function to call later will lift
+   those restrictions.
+
+   Note: If `schedule()` is called from a preempting IRQ, when memory
+   allocation is not allowed and the callback to be passed to `schedule()` is
+   a bound method, passing this directly will fail. This is because creating a
+   reference to a bound method causes memory allocation. A solution is to
+   create a reference to the method in the class constructor and to pass that
+   reference to `schedule()`.
+
+   There is a finite queue to hold the scheduled functions and `schedule()`
+   will raise a `RuntimeError` if the queue is full.

docs/library/sys.rst

@@ -17,20 +17,6 @@ Functions
    function raise as `SystemExit` exception. If an argument is given, its
    value given as an argument to `SystemExit`.
 
-.. function:: print_exception(exc, file=sys.stdout)
-
-   Print exception with a traceback to a file-like object *file* (or
-   `sys.stdout` by default).
-
-   .. admonition:: Difference to CPython
-      :class: attention
-
-      This is simplified version of a function which appears in the
-      ``traceback`` module in CPython. Unlike ``traceback.print_exception()``,
-      this function takes just exception value instead of exception type,
-      exception value, and traceback object; *file* argument should be
-      positional; further arguments are not supported.
-
 Constants
 ---------
 
@@ -122,3 +108,9 @@ Constants
 .. data:: version_info
 
    Python language version that this implementation conforms to, as a tuple of ints.
+
+    .. admonition:: Difference to CPython
+      :class: attention
+
+      Only the first three version numbers (major, minor, micro) are supported and
+      they can be referenced only by index, not by name.