Docstrings: Google sections and cross-references; licence headers on every file

build_mp.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Build PyDevices MicroPython firmware with one command.
 
     ./build_mp.py --port esp32 --board ESP32_GENERIC_P4 --variant C6_WIFI \\

docs/conf.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Sphinx configuration for the micropython-pydevices documentation.
 
 Everything shared by the PyDevices documentation projects (theme, top bar,

modules/all/manifest.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 # Every module beside this one, except those that say they are opt-in: a
 # module with an OPT_IN file (its text says why) is built only when named.
 # Otherwise all means all, and a module leaves "all" only by leaving modules/.

modules/audiocomponents/manifest.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 # audiocomponents is the old name for audioinstruments plus audioeffects,
 # kept so `--modules audiocomponents` still builds both.
 include("../audioinstruments")

modules/audioeffects/manifest.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 # audioeffects, from omnipython-lib: the effect classes, which the library
 # builds from the PyDevices/audioeffects repository at the tag its
 # lib-lock.json pins. They import ulab and audiodsp, so name those too (or

modules/audioif/manifest.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 # Freeze manifest for this repo. Nothing Python to freeze here; the line below
 # names the C module so a build that includes this manifest compiles it
 # (MicroPython 1.29 c_module()).

modules/audioif/tests/busio_probe.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """`audiobusio.I2SOut` against what CircuitPython documents it to do.
 
 Everything here is a CircuitPython behaviour taken off

modules/audioif/tests/cp_example_probe.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """The CircuitPython `audiobusio` docstring example, run unmodified.
 
 This is the program in CircuitPython 10.3.0's own

modules/audioif/tests/i2sin_probe.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """`audioi2sin.I2SIn` against what CircuitPython documents it to do.
 
 Every leg is a behaviour taken off CircuitPython's

modules/audioif/tests/p4_starved_probe.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """`I2SOut.starved()` on a board: 0 while nothing starves, and it moves when
 the pump really falls behind.
 

modules/audioif/tests/s3_drift.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """audioif#5: do the T-Embed's two I2S ports drift, over an hour?
 
 Forty seconds said no -- `rx - tx` stayed at 0 bytes at a 4 x 128 ring. Two

modules/audioif/tests/s3_stall_witness.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Does a flash erase stall the I2S DMA itself, or only the pump?
 
     mpftp put -d COM12 tests/s3_stall_witness.py /lib/s3_stall_witness.py

modules/audioif/tests/sink_probe.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """The driver's file sink hands over exactly what the engine pulled.
 
     <interpreter> tests/sink_probe.py [scratch-dir] [--fault WHICH]

modules/audioif/tests/tone_check.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Is there a tone at `hz` in this recording? Asked through `audiometer`.
 
     from tone_check import tone_check

modules/audioif/tests/wasapi_ring_probe.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """A WASAPI microphone feeding an audiopump.Ring on its own thread holds pace.
 
     micropython.exe tests/wasapi_ring_probe.py [secs=30] [in=ID] [out=ID]

modules/audioinstruments/manifest.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 # audioinstruments, from omnipython-lib: the rack and its instruments, which
 # the library builds from the PyDevices/audioinstruments repository at the tag
 # its lib-lock.json pins. They import ulab and audiodsp, so name those too (or

modules/cameraif/manifest.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 # MicroPython manifest for cameraif: deliberately empty.
 #
 # cameraif is a native module with no Python half. Its whole surface is the

modules/cameraif/tests/hardware/espcamera_controls.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Every espcamera control name on a real camera, checked against its driver.
 
 Reads each of espcamera's control names, and for the ones the sensor offers,

modules/cameraif/tests/hardware/judge_espcamera_controls.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Judge espcamera_controls.py's output against the OV5647 driver's own source.
 
 The expectation comes from esp_cam_sensor's ov5647.c (which parameter ids its

modules/castif/manifest.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 # castif: C only, ESP32-P4 only. The cast's RTP, pacing and audio; the
 # encoding is h264enc's and the MPEG-TS tsmux's (name all three modules).
 c_module(".")

modules/castif/tests/check_castif_hls.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """ffprobe decodes what test_castif_hls served: each kept segment alone and
 the playlist, and /stats parses as JSON. A planted fault (a segment cut in
 half) must fail.

modules/displayif/manifest.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 # Freeze manifest for this repo. Nothing Python to freeze here; the line below
 # names the C module so a build that includes this manifest compiles it
 # (MicroPython 1.29 c_module()).

modules/displayif/src/ports/rp2/picodvi/libdvi/tmds_table_gen.py

@@ -1,4 +1,7 @@
 #!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
 
 # The key fact is that, if x is even, and the encoder currently has a running
 # imbalance of 0, encoding x followed by x + 1 produces a symbol pair with a

modules/displayif/tests/test_lifecycle_api.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Verify displayif modules expose idempotent lifecycle methods on their types.
 
 This test runs without display hardware: it imports modules that exist on the

modules/displayif/tools/check_qstr_reachability.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Refuse an MP_QSTR_ name that only exists when a usermod's INTERFACE define is set.
 
 The rule this enforces, and why, is docs/qstrs-and-usermod-defines.md. In one
@@ -20,7 +24,7 @@
 
 A name is not reported when it *also* appears unguarded **in the same file** --
 the QSTR pass collects it from there and the guarded reference rides along -- or
-when it is in :data:`CORE_POOL` below.
+when it is in `CORE_POOL` below.
 
 Same file, not same repo, and the difference is the whole check. Every name in
 ``src/ports/samd/mod_i80bus.c`` is also referenced by the esp32 backend and by

modules/displayif/tools/test_dotclockframebuffer_smoke.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Smoke test for dotclockframebuffer.DotClockFramebuffer import and buffer protocol (esp32)."""
 
 import sys

modules/displayif/tools/test_i2cbus_smoke.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Smoke test for i2cbus import (MCU ports with machine.I2C)."""
 
 import sys

modules/displayif/tools/test_i80bus_smoke.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Smoke test for i80bus import."""
 
 import sys

modules/displayif/tools/test_mimxrt_dotclockframebuffer_smoke.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Smoke test for dotclockframebuffer.DotClockFramebuffer (mimxrt eLCDIF).
 
 Small 4x4 buffer on MIMXRT1062 (Teensy 4.x / MIMXRT1060-EVK). Full RK043 panel

modules/displayif/tools/test_mimxrt_mipidsi_smoke.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Smoke test for mipidsi import (MIMXRT1176 with MIPI DSI only).
 
 Full panel bring-up requires MIMXRT1170-EVK + Waveshare 5\" DSI on J84.

modules/displayif/tools/test_mipidsi_smoke.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Smoke test for mipidsi import (ESP32-P4 with MIPI DSI only).
 
 Full panel bring-up requires the Waveshare ESP32-P4-WIFI6-Touch-LCD-4B hardware.

modules/displayif/tools/test_picodvi_smoke.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Smoke test for picodvi import and Framebuffer (rp2 PIO / HSTX).
 
 Uses the smallest supported mode (320x240 @ 4bpp on RP2040). Full DVI output

modules/displayif/tools/test_rgbmatrix_smoke.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Smoke test for rgbmatrix import, tile height, and buffer protocol."""
 
 import sys

modules/displayif/tools/test_spi_smoke.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Smoke test for native spibus (displayif src/ports/common/spi)."""
 
 import sys

modules/h264enc/manifest.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 # h264enc: RGB565 frames to H.264 on the ESP32-P4's hardware encoder (the PPA
 # converts, esp_h264 encodes). C only, ESP32-P4 only; castif encodes through
 # its C API. Moved out of castif (media modules roadmap, Phase 3).

modules/h264enc/tests/check_h264_ffmpeg.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """ffmpeg on the PC decodes what test_h264enc.py encoded on the board.
 
 Thresholds fixed before the first run (2026-10-06): ffmpeg decodes exactly N

modules/h264enc/tests/encode_h264_ffmpeg.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """The board half's stand-in on a PC: ffmpeg's x264 encodes h264_frames.py's
 frames with the settings hardware/test_h264enc.py gives h264enc (720x720,
 30 fps, 3 Mbit/s, a keyframe every 30), so CI can run check_h264_ffmpeg.py

modules/h264enc/tests/h264_frames.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 # The test's source frames, computed the same way on a board (MicroPython)
 # and on the PC (CPython, check_h264_ffmpeg.py): a fixed RGB565 gradient with
 # a 96x96 box crossing it, 8 px a frame, in native byte order.

modules/h264enc/tests/hardware/test_h264enc.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """h264enc on the ESP32-P4 -- the media Phase 3 encode gate, board half.
 
 Encodes N frames from h264_frames.py (no camera, no cast) at 720x720, 30 fps,

modules/jpegio/manifest.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 # jpegio: JPEG decoding into RGB565 (CircuitPython's jpegio API, on ChaN's
 # TJpgDec), and LVGL's JPEG decoder when LVGL (omnipython-lvgl) is in the build.
 # C only; every port. Moved here from displayif (media modules roadmap,

modules/jpegio/tests/check_encode_pil.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Pillow, a decoder that is not ours, must read back what we encoded.
 
 Every JPEG test_jpegio_encode.py wrote must open in Pillow at its size and

modules/jpegio/tests/hardware/board_lvgl_glass.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 # On a board with a display, LVGL and jpegio: draw a corpus JPEG with
 # lv.image and compare what lands in the panel's framebuffer, pixel for pixel,
 # with jpegio decoding the same file into a buffer. The framebuffer is what

modules/jpegio/tests/jpegwalk.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """jpegwalk -- a tiny JPEG marker walker.
 
 Plain Python with no third-party imports, written so it also runs under

modules/jpegio/tests/make_corpus.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Build the jpegio test corpus in frames/ and write frames/README.md.
 
 Run:  python3 modules/jpegio/tests/make_corpus.py        (needs Pillow; 12.3 used)

modules/jpegio/tests/reference.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """Pillow fidelity reference for the jpegio corpus -> frames/reference.json.
 
 Run:  python3 modules/jpegio/tests/reference.py        (needs Pillow; 12.3 used)

modules/jpegio/tests/test_jpegio.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """jpegio -- unix MicroPython tests against the corpus and the Pillow reference.
 
 The Phase 1 gate of the org's docs/jpegio-vision.md, checked mechanically:

modules/jpegio/tests/test_jpegio_encode.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """jpegio.JpegEncoder (and the P4's hardware decode) -- the media Phase 2 gate.
 
 Thresholds were fixed before the first run, on the corpus's real camera frame

modules/jpegio/tests/test_jpegio_lvgl.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Brad Barnett
+#
+# SPDX-License-Identifier: MIT
+
 """jpegio -- its LVGL image decoder, on unix MicroPython built beside lvgl (omnipython-lvgl).
 
 The LVGL half of the Phase 2 gate in the org's docs/jpegio-vision.md, checked