docs: machine/network/omv/rp2 library reference audit

- machine: per-port availability sections + grouped methods/constants
  across ADC, CAN, Counter, Encoder, I2C, I2CTarget, I2S, LED, PWM,
  Pin, RTC, SDCard, SPI, Timer, UART, WDT.
- network: WINC1500/CYW43/NINA driver split, LAN/WLAN/WINC audit,
  network.rst index cleanup.
- omv.image: expanded module intro, restructured functions/constants
  into themed subsections; converted Blob/Line/Circle/Rect/QRCode/
  AprilTag/DataMatrix/BarCode/Displacement/kptmatch/Similarity/
  Statistics/Percentile/Threshold from .. method:: x() to
  .. attribute:: x to match the attrtuple-backed runtime API;
  expanded Image class intro and ImageIO methods/constants;
  fixed get_enclosed_ellipse return type (plain tuple, degrees).
- omv.csi / omv.sensor: ioctl docs regrouped per sensor family.
- rp2: unhidden Flash / PIO / StateMachine docs and scrubbed for
  hygiene on RP2040.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: kwagyeman

docs/conf.py

@@ -349,23 +349,20 @@ def _render_landing_code(src):
     "library/esp.rst",
     "library/espnow.rst",
     "library/esp32.rst",
-    "library/rp2.rst",
-    "library/rp2.DMA.rst",
-    "library/rp2.Flash.rst",
-    "library/rp2.PIO.rst",
-    "library/rp2.StateMachine.rst",
     "library/wm8960.rst",
     "library/zephyr.rst",
     "library/zephyr.DiskAccess.rst",
     "library/zephyr.FlashArea.rst",
     "library/zephyr.zsensor.rst",
     "library/lcd160cr.rst",
+    "library/machine.ADCBlock.rst",
     "library/machine.ADCWiPy.rst",
     "library/machine.DAC.rst",
     "library/machine.SD.rst",
     "library/machine.TimerWiPy.rst",
     "library/machine.USBDevice.rst",
     "library/network.CC3K.rst",
+    "library/network.PPP.rst",
     "library/network.WIZNET5K.rst",
     "library/network.WLANWiPy.rst",
     "library/pyb.Accel.rst",

docs/library/index.rst

@@ -168,6 +168,7 @@ for which boards include each one.
    stm.rst
    mimxrt.rst
    omv.alif.rst
+   rp2.rst
    ubluepy.rst
 
 Hardware drivers
@@ -369,6 +370,7 @@ RP2040-based Nano-form-factor board with the U-blox NINA-W102
 Wi-Fi/Bluetooth module. *No longer actively supported; the last OpenMV
 firmware release for this board is retained for archival use.*
 
+* :mod:`rp2` --- RP2040-specific PIO / DMA / flash helpers
 * :mod:`espflash` --- ESP32 ROM bootloader firmware flasher
 * :mod:`lsm6dsox` --- LSM6DSOX 6-axis IMU
 * :mod:`dht` --- DHT11 and DHT22 temperature/humidity sensors

docs/library/machine.ADC.rst

@@ -4,63 +4,81 @@
 class ADC -- analog to digital conversion
 =========================================
 
-The ADC class provides an interface to analog-to-digital converters, and
-represents a single endpoint that can sample a continuous voltage and
-convert it to a discretised value.
-
-For extra control over ADC sampling see :ref:`machine.ADCBlock <machine.ADCBlock>`.
+The :class:`ADC` class wraps a single analog-to-digital converter
+channel that samples a voltage on a pin (or one of the on-chip
+analog channels) and returns its discretised value.
 
 Example usage::
 
-   from machine import ADC
+   from machine import ADC, Pin
 
-   adc = ADC(pin)        # create an ADC object acting on a pin
-   val = adc.read_u16()  # read a raw analog value in the range 0-65535
-   val = adc.read_uv()   # read an analog value in microvolts
+   adc = ADC(Pin("P6"))      # ADC channel on header pin P6 (PA5)
+   val = adc.read_u16()      # raw reading scaled to 0..65535
 
 Constructors
 ------------
 
-.. class:: ADC(id: int | Pin, *, sample_ns: int | None = None, atten: int | None = None)
-
-   Access the ADC associated with a source identified by *id*.  This
-   *id* may be an integer (usually specifying a channel number), a
-   :ref:`Pin <machine.Pin>` object, or other value supported by the
-   underlying machine.
+.. class:: ADC(id: int | str | Pin) -> ADC
 
-   If additional keyword-arguments are given then they will configure
-   various aspects of the ADC.  If not given, these settings will take
-   previous or default values.  The settings are:
+   Construct an :class:`ADC` object for the analog source identified
+   by ``id``. The accepted forms are:
 
-     - *sample_ns* is the sampling time in nanoseconds.
-
-     - *atten* specifies the input attenuation.
+      * an integer channel number (``0`` -- ``18`` on STM32, port-
+        specific elsewhere);
+      * a :class:`Pin` object, or a board pin string such as
+        ``"P6"`` -- the pin must be analog-capable;
+      * one of the internal-channel constants (:data:`CORE_TEMP`,
+        :data:`CORE_VREF`, :data:`CORE_VBAT`, :data:`VREF` or
+        :data:`CORE_VDD`) to read the MCU's internal sensors.
+        STM32 only.
 
    Methods
    -------
 
-   .. method:: init(*, sample_ns: int | None = None, atten: int | None = None) -> None
+   .. method:: read_u16() -> int
 
-      Apply the given settings to the ADC.  Only those arguments that are
-      specified will be changed.  See the ADC constructor above for what the
-      arguments are.
+      Sample the analog channel once and return the result as an
+      unsigned 16-bit integer (``0`` -- ``65535``). Lower-resolution
+      ADCs are left-aligned into the 16-bit range so the
+      port-specific raw resolution is hidden.
 
-   .. method:: block() -> ADCBlock
+   .. method:: read_uv() -> int
 
-      Return the :ref:`ADCBlock <machine.ADCBlock>` instance associated with
-      this ADC object.
+      Sample the analog channel and return the result in microvolts.
+      The reading is calibrated against the internal reference where
+      hardware supports it. mimxrt port only.
 
-      This method only exists if the port supports the
-      :ref:`ADCBlock <machine.ADCBlock>` class.
+   Constants
+   ---------
 
-   .. method:: read_u16() -> int
+   The constants below are only available on the STM32 port; pass
+   them as the ``id`` argument to construct an :class:`ADC` that
+   reads one of the on-chip analog sensors. The result of
+   :meth:`read_u16` is the channel's raw 16-bit reading; for
+   calibrated values use the helpers on :class:`pyb.ADCAll`.
 
-      Take an analog reading and return an integer in the range 0-65535.
-      The return value represents the raw reading taken by the ADC, scaled
-      such that the minimum value is 0 and the maximum value is 65535.
+   .. data:: VREF
+      :type: int
 
-   .. method:: read_uv() -> int
+      External voltage-reference channel.
+
+   .. data:: CORE_VREF
+      :type: int
+
+      Internal 1.21 V (nominal) voltage-reference channel
+      (``VREFINT``).
+
+   .. data:: CORE_TEMP
+      :type: int
+
+      Internal die-temperature sensor channel.
+
+   .. data:: CORE_VBAT
+      :type: int
+
+      Backup-battery voltage channel (``VBAT``).
+
+   .. data:: CORE_VDD
+      :type: int
 
-      Take an analog reading and return an integer value with units of
-      microvolts.  It is up to the particular port whether or not this value
-      is calibrated, and how calibration is done.
+      MCU supply-rail channel (``VDDA``).

docs/library/machine.CAN.rst

@@ -9,13 +9,19 @@ between one or more nodes connected to a common bus. CAN 2.0 was standardised in
 ISO-11898, and is now also known as CAN Classic.
 
 There is also a newer, backwards compatible, protocol named CAN FD (CAN with
-Flexible Data-Rate). *The machine.CAN driver does not currently support CAN FD
-features, use `pyb.CAN` on stm32 if you need CAN FD*.
+Flexible Data-Rate). The :class:`machine.CAN` driver does not currently
+support CAN FD features; use :class:`pyb.CAN` on STM32 if you need
+CAN FD.
 
 CAN support requires a controller (often an internal microcontroller
 peripheral), and an external transceiver to level-shift the signals onto the CAN
 bus.
 
+Available on STM32 OpenMV cams (M4 / M7 / H7 / H7 Plus / Pure Thermal /
+N6, plus the Arduino-branded variants that wire a transceiver). Not
+yet supported on the OpenMV Cam RT1062 (mimxrt port) or the OpenMV
+Cam AE3 (alif port).
+
 The ``machine.CAN`` interface is a *low level basic* CAN messaging interface
 that abstracts a CAN controller as an outgoing priority queue for sending
 messages, an incoming queue for receiving messages, and mechanisms for reporting
@@ -573,18 +579,54 @@ Constructor
    ^^^^^^^^^^
 
    .. data:: IRQ_RX
-             IRQ_TX
-             IRQ_STATE
       :type: int
 
-       IRQ event triggers. Used with :func:`CAN.irq()` and `machine_can_irq_flags`.
+      Pass to the ``trigger`` argument of :meth:`irq` to fire the
+      handler each time the CAN controller has received a complete
+      message into the RX FIFO. Inside the handler, read the
+      message with :meth:`recv`.
+
+   .. data:: IRQ_TX
+      :type: int
+
+      Pass to the ``trigger`` argument of :meth:`irq` to fire the
+      handler each time the CAN controller finishes a transmit
+      attempt (success or failure). Inside the handler, use the
+      additional bits below to recover which mailbox completed and
+      whether it failed -- see :ref:`machine_can_irq_flags`.
+
+   .. data:: IRQ_STATE
+      :type: int
+
+      Pass to the ``trigger`` argument of :meth:`irq` to fire the
+      handler each time the controller transitions between the
+      ``STATE_*`` values (active / warning / passive / bus-off).
+      Use :meth:`state` inside the handler to read the new state.
 
    .. data:: IRQ_TX_FAILED
-             IRQ_TX_IDX_SHIFT
-             IRQ_TX_IDX_MASK
       :type: int
 
-       Additional IRQ event flags for `CAN.IRQ_TX`. See `machine_can_irq_flags`.
+      Status flag that may be set in ``irq().flags()`` when an
+      :data:`IRQ_TX` event fires. Indicates the transmit attempt
+      failed (typically because :meth:`cancel_send` was called, or
+      the controller entered an error state).
+
+   .. data:: IRQ_TX_IDX_SHIFT
+      :type: int
+
+      Bit position of the transmit-mailbox-index field within the
+      ``irq().flags()`` value during an :data:`IRQ_TX` event. The
+      mailbox index is extracted as
+      ``(flags >> IRQ_TX_IDX_SHIFT) & IRQ_TX_IDX_MASK``.
+
+   .. data:: IRQ_TX_IDX_MASK
+      :type: int
+
+      Bit mask of the transmit-mailbox-index field within the
+      ``irq().flags()`` value during an :data:`IRQ_TX` event. The
+      extracted index matches the integer returned by the
+      corresponding :meth:`send` call (an int in the range ``0`` to
+      :data:`TX_QUEUE_LEN`).
 
 .. _machine_can_irq_flags:
 
@@ -606,8 +648,8 @@ information about the TX event:
 * ``CAN.IRQ_TX_FAILED`` bit is set if the transmit failed. Usually this will
   only happen if :func:`CAN.cancel_send()` was called, although it may also
   happen if the controller enters an error state.
-* ``CAN.IRQ_TX_MASK << CAN.IRQ_TX_SHIFT`` is a bitmasked region of the flags
-  value that holds the index of the transmit buffer which generated the event.
+* ``CAN.IRQ_TX_IDX_MASK << CAN.IRQ_TX_IDX_SHIFT`` is a bitmasked region of the
+  flags value that holds the index of the transmit buffer which generated the event.
   This will be an integer in the range ``0`` to `CAN.TX_QUEUE_LEN` (exclusive),
   and will match the result of a previous call to `CAN.send()`.