Merge branch 'micropython:master' into esp32_bitstream

Author: ricksorensen

.github/workflows/ruff.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    # ruff version should be kept in sync with .pre-commit-config.yaml
-    - run: pipx install ruff==0.9.6
+    # ruff version should be kept in sync with .pre-commit-config.yaml & also micropython-lib
+    - run: pipx install ruff==0.11.6
     - run: ruff check --output-format=github .
     - run: ruff format --diff .

.pre-commit-config.yaml

@@ -12,8 +12,8 @@ repos:
         verbose: true
         stages: [commit-msg]
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    # Version should be kept in sync with .github/workflows/ruff.yml
-    rev: v0.9.6
+    # Version should be kept in sync with .github/workflows/ruff.yml & also micropython-lib
+    rev: v0.11.6
     hooks:
       - id: ruff
       - id: ruff-format

CODECONVENTIONS.md

@@ -206,33 +206,65 @@ adhere to the existing style and use `tools/codeformat.py` to check any changes.
 The main conventions, and things not enforceable via the auto-formatter, are
 described below.
 
-White space:
+As the MicroPython code base is over ten years old, not every source file
+conforms fully to these conventions. If making small changes to existing code,
+then it's usually acceptable to follow the existing code's style. New code or
+major changes should follow the conventions described here.
+
+## White space
+
 - Expand tabs to 4 spaces.
 - Don't leave trailing whitespace at the end of a line.
 - For control blocks (if, for, while), put 1 space between the
   keyword and the opening parenthesis.
 - Put 1 space after a comma, and 1 space around operators.
 
-Braces:
+## Braces
+
 - Use braces for all blocks, even no-line and single-line pieces of
   code.
 - Put opening braces on the end of the line it belongs to, not on
   a new line.
 - For else-statements, put the else on the same line as the previous
   closing brace.
 
-Header files:
+## Header files
+
 - Header files should be protected from multiple inclusion with #if
   directives. See an existing header for naming convention.
 
-Names:
+## Names
+
 - Use underscore_case, not camelCase for all names.
 - Use CAPS_WITH_UNDERSCORE for enums and macros.
 - When defining a type use underscore_case and put '_t' after it.
 
-Integer types: MicroPython runs on 16, 32, and 64 bit machines, so it's
-important to use the correctly-sized (and signed) integer types.  The
-general guidelines are:
+### Public names (declared in headers)
+
+- MicroPython-specific names (especially any declared in `py/` and `extmod/`
+  directories) should generally start with `mp_` or `MP_`.
+- Functions and variables declared in a header should generally share a longer
+  common prefix. Usually the prefix matches the file name (i.e. items defined in
+  `py/obj.c` are declared in `py/obj.h` and should be prefixed `mp_obj_`). There
+  are exceptions, for example where one header file contains declarations
+  implemented in multiple source files for expediency.
+
+### Private names (specific to a single .c file)
+
+- For static functions and variables exposed to Python (i.e. a static C function
+  that is wrapped in `MP_DEFINE_CONST_FUN_...` and attached to a module), use
+  the file-level shared common prefix, i.e. name them as if the function or
+  variable was not static.
+- Other static definitions in source files (i.e. functions or variables defined
+  in a .c file that are only used within that .c file) don't need any prefix
+  (specifically: no `s_` or `_` prefix, and generally avoid adding the
+  file-level common prefix).
+
+## Integer types
+
+MicroPython runs on 16, 32, and 64 bit machines, so it's important to use the
+correctly-sized (and signed) integer types. The general guidelines are:
+
 - For most cases use mp_int_t for signed and mp_uint_t for unsigned
   integer values.  These are guaranteed to be machine-word sized and
   therefore big enough to hold the value from a MicroPython small-int
@@ -241,11 +273,13 @@ general guidelines are:
 - You can use int/uint, but remember that they may be 16-bits wide.
 - If in doubt, use mp_int_t/mp_uint_t.
 
-Comments:
+## Comments
+
 - Be concise and only write comments for things that are not obvious.
 - Use `// ` prefix, NOT `/* ... */`. No extra fluff.
 
-Memory allocation:
+## Memory allocation
+
 - Use m_new, m_renew, m_del (and friends) to allocate and free heap memory.
   These macros are defined in py/misc.h.
 

docs/library/wm8960.rst

@@ -358,13 +358,13 @@ Run WM8960 on a MIMXRT10xx_DEV board in secondary mode (default)::
         sysclk_source=wm8960.SYSCLK_MCLK)
 
 
-Record with a Sparkfun WM8960 breakout board with Teensy in secondary mode (default)::
+Record with a SparkFun WM8960 breakout board with Teensy in secondary mode (default)::
 
     # Micro_python WM8960 Codec driver
     #
     # The breakout board uses a fixed 24MHz MCLK. Therefore the internal
     # PLL must be used as sysclk, which is the master audio clock.
-    # The Sparkfun board has the WS pins for RX and TX connected on the
+    # The SparkFun board has the WS pins for RX and TX connected on the
     # board. Therefore adc_sync must be set to sync_adc, to configure
     # it's ADCLRC pin as input.
     #
@@ -379,11 +379,11 @@ Record with a Sparkfun WM8960 breakout board with Teensy in secondary mode (defa
         right_input=wm8960.INPUT_CLOSED)
 
 
-Play with a Sparkfun WM8960 breakout board with Teensy in secondary mode (default)::
+Play with a SparkFun WM8960 breakout board with Teensy in secondary mode (default)::
 
     # The breakout board uses a fixed 24MHz MCLK. Therefore the internal
     # PLL must be used as sysclk, which is the master audio clock.
-    # The Sparkfun board has the WS pins for RX and TX connected on the
+    # The SparkFun board has the WS pins for RX and TX connected on the
     # board. Therefore adc_sync must be set to sync_adc, to configure
     # it's ADCLRC pin as input.
 

docs/library/zephyr.rst

@@ -22,9 +22,10 @@ Functions
 
    Returns the thread id of the current thread, which is used to reference the thread.
 
-.. function:: thread_analyze()
+.. function:: thread_analyze(cpu)
 
-   Runs the Zephyr debug thread analyzer on the current thread and prints stack size statistics in the format:
+   Runs the Zephyr debug thread analyzer on the current thread on the given cpu
+   and prints stack size statistics in the format:
 
     "``thread_name``-20s: STACK: unused ``available_stack_space`` usage ``stack_space_used``
     / ``stack_size`` (``percent_stack_space_used`` %); CPU: ``cpu_utilization`` %"
@@ -35,6 +36,9 @@ Functions
    For more information, see documentation for Zephyr `thread analyzer
    <https://docs.zephyrproject.org/latest/guides/debug_tools/thread-analyzer.html#thread-analyzer>`_.
 
+   Note that the ``cpu`` argument is only used in Zephyr v4.0.0 and
+   newer and ignored otherwise.
+
 .. function:: shell_exec(cmd_in)
 
    Executes the given command on an UART backend. This function can only be accessed if ``CONFIG_SHELL_BACKEND_SERIAL``

docs/samd/pinout.rst

@@ -892,7 +892,7 @@ Default pin assignments:
 
 There seems to be no default pin assignment for this board.
 
-Sparkfun SAMD51 Thing Plus pin assignment table
+SparkFun SAMD51 Thing Plus pin assignment table
 ------------------------------------------------
 
 === ==== ============ ==== ==== ==== ====== ====== ===== ===== =====

docs/zephyr/quickref.rst

@@ -56,6 +56,21 @@ Use the :ref:`machine.Pin <machine.Pin>` class::
     switch = Pin(("gpioc", 6), Pin.IN)            # create input pin for a switch
     switch.irq(lambda t: print("SW2 changed"))    # enable an interrupt when switch state is changed
 
+PWM
+---
+
+Use the :ref:`machine.PWM <machine.PWM>` class::
+
+    from machine import PWM
+
+    pwm = PWM(("pwm0", 0), freq=3921568, duty_ns=200, invert=True)    # create pwm on PWM0
+    print(pwm)                                                        # print pwm
+
+    print(pwm.duty_ns())                                              # print pwm duty cycle in nanoseconds
+    pwm.duty_ns(255)                                                  # set new pwm duty cycle in nanoseconds
+
+    pwm.deinit()
+
 Hardware I2C bus
 ----------------
 
@@ -138,6 +153,8 @@ Use the :ref:`zephyr.FlashArea <zephyr.FlashArea>` class to support filesystem::
         f.write('Hello world')                  # write to the file
     print(open('/flash/hello.txt').read())      # print contents of the file
 
+The FlashAreas' IDs that are available are listed in the FlashArea module, as ID_*.
+
 Sensor
 ------
 

docs/zephyr/tutorial/repl.rst

@@ -31,7 +31,7 @@ With your serial program open (PuTTY, screen, picocom, etc) you may see a
 blank screen with a flashing cursor. Press Enter (or reset the board) and
 you should be presented with the following text::
 
-        *** Booting Zephyr OS build v3.7.0 ***
+        *** Booting Zephyr OS build v4.0.0 ***
         MicroPython v1.24.0-preview.179.g5b85b24bd on 2024-08-05; zephyr-frdm_k64f with mk64f12
         Type "help()" for more information.
         >>>