Clean up examples and drivers

Safe imports of RP2 drivers
Add docstring comments
Make driver members private
Update comments in examples

Author: sfe-SparkFro

cv2_drivers/cameras/__init__.py

@@ -1,2 +1,7 @@
-from . import hm01b0_pio
-from . import ov5640_pio
+# Import sys module to check platform
+import sys
+
+# Import RP2 drivers
+if 'rp2' in sys.platform:
+    from . import hm01b0_pio
+    from . import ov5640_pio

cv2_drivers/cameras/cv2_camera.py

@@ -1,5 +1,35 @@
 class CV2_Camera():
+    """
+    Base class for OpenCV camera drivers.
+    """
     def __init__(self):
+        """
+        Initializes the camera.
+        """
         pass
 
-    # TODO: Implement common methods for all cameras
+    def open(self):
+        """
+        Opens the camera and prepares it for capturing images.
+        """
+        raise NotImplementedError("open() must be implemented by driver")
+
+    def release(self):
+        """
+        Releases the camera and frees any resources.
+        """
+        raise NotImplementedError("release() must be implemented by driver")
+
+    def read(self, image=None):
+        """
+        Reads an image from the camera.
+
+        Args:
+            image (ndarray, optional): Image to read into
+
+        Returns:
+            tuple: (success, image)
+                - success (bool): True if the image was read, otherwise False
+                - image (ndarray): The captured image, or None if reading failed
+        """
+        raise NotImplementedError("read() must be implemented by driver")

cv2_drivers/cameras/dvp_camera.py

@@ -1,25 +1,50 @@
 from .cv2_camera import CV2_Camera
-from machine import Pin
-from time import sleep_us
 
 class DVP_Camera(CV2_Camera):
+    """
+    Base class for OpenCV DVP (Digital Video Port) camera drivers.
+    """
     def __init__(
         self,
         i2c,
         i2c_address
     ):
+        """
+        Initializes the DVP camera with I2C communication.
+
+        Args:
+            i2c (I2C): I2C object for communication
+            i2c_address (int): I2C address of the camera
+        """
         super().__init__()
 
-        self.i2c = i2c
-        self.i2c_address = i2c_address
+        self._i2c = i2c
+        self._i2c_address = i2c_address
+
+    def _read_register(self, reg, nbytes=1):
+        """
+        Reads a register from the camera over I2C.
+
+        Args:
+            reg (int): Register address to read
+            nbytes (int): Number of bytes to read from the register
+
+        Returns:
+            bytes: Data read from the register
+        """
+        self._i2c.writeto(self._i2c_address, bytes([reg >> 8, reg & 0xFF]))
+        return self._i2c.readfrom(self._i2c_address, nbytes)
+
+    def _write_register(self, reg, data):
+        """
+        Writes data to a register on the camera over I2C.
 
-    def readRegister(self, reg, nbytes=1):
-        self.i2c.writeto(self.i2c_address, bytes([reg >> 8, reg & 0xFF]))
-        return self.i2c.readfrom(self.i2c_address, nbytes)
-    
-    def writeRegister(self, reg, data):
+        Args:
+            reg (int): Register address to write
+            data (bytes, int, list, tuple): Data to write to the register
+        """
         if isinstance(data, int):
             data = bytes([data])
         elif isinstance(data, (list, tuple)):
             data = bytes(data)
-        self.i2c.writeto(self.i2c_address, bytes([reg >> 8, reg & 0xFF]) + data)
+        self._i2c.writeto(self._i2c_address, bytes([reg >> 8, reg & 0xFF]) + data)

cv2_drivers/cameras/dvp_rp2_pio.py

@@ -1,7 +1,16 @@
 import rp2
 from machine import Pin, PWM
 
+# This class is derived from:
+# https://github.com/adafruit/Adafruit_ImageCapture/blob/main/src/arch/rp2040.cpp
+# Released under the MIT license.
+# Copyright (c) 2021 Adafruit Industries
 class DVP_RP2_PIO():
+    """
+    This class implements a DVP (Digital Video Port) interface using the RP2 PIO
+    (Programmable Input/Output) interface. This is only available on Raspberry
+    Pi RP2 processors.
+    """
     def __init__(
         self,
         pin_d0,
@@ -15,12 +24,27 @@ def __init__(
         bytes_per_frame,
         byte_swap
     ):
-        self.pin_d0 = pin_d0
-        self.pin_vsync = pin_vsync
-        self.pin_hsync = pin_hsync
-        self.pin_pclk = pin_pclk
-        self.pin_xclk = pin_xclk
-        self.sm_id = sm_id
+        """
+        Initializes the DVP interface with the specified parameters.
+
+        Args:
+            pin_d0 (int): Data 0 pin number for DVP interface
+            pin_vsync (int): Vertical sync pin number
+            pin_hsync (int): Horizontal sync pin number
+            pin_pclk (int): Pixel clock pin number
+            pin_xclk (int): External clock pin number
+            xclk_freq (int): Frequency in Hz for the external clock
+            sm_id (int): PIO state machine ID
+            num_data_pins (int): Number of data pins used in DVP interface
+            bytes_per_frame (int): Number of bytes per frame to capture
+            byte_swap (bool): Whether to swap bytes in the captured data
+        """
+        self._pin_d0 = pin_d0
+        self._pin_vsync = pin_vsync
+        self._pin_hsync = pin_hsync
+        self._pin_pclk = pin_pclk
+        self._pin_xclk = pin_xclk
+        self._sm_id = sm_id
 
         # Initialize DVP pins as inputs
         for i in range(num_data_pins):
@@ -30,86 +54,98 @@ def __init__(
         Pin(pin_pclk, Pin.IN)
 
         # Set up XCLK pin if provided
-        if self.pin_xclk is not None:
-            self.xclk = PWM(Pin(pin_xclk))
-            self.xclk.freq(xclk_freq)
-            self.xclk.duty_u16(32768) # 50% duty cycle
+        if self._pin_xclk is not None:
+            self._xclk = PWM(Pin(pin_xclk))
+            self._xclk.freq(xclk_freq)
+            self._xclk.duty_u16(32768) # 50% duty cycle
 
         # Copy the PIO program
         program = self._pio_read_dvp
 
         # Mask in the GPIO pins
-        program[0][0] |= self.pin_hsync & 0x1F
-        program[0][1] |= self.pin_pclk & 0x1F
-        program[0][3] |= self.pin_pclk & 0x1F
+        program[0][0] |= self._pin_hsync & 0x1F
+        program[0][1] |= self._pin_pclk & 0x1F
+        program[0][3] |= self._pin_pclk & 0x1F
 
         # Mask in the number of data pins
         program[0][2] &= 0xFFFFFFE0
         program[0][2] |= num_data_pins
 
         # Create PIO state machine to capture DVP data
-        self.sm = rp2.StateMachine(
-            self.sm_id,
+        self._sm = rp2.StateMachine(
+            self._sm_id,
             program,
             in_base = pin_d0
         )
 
         # Create DMA controller to transfer data from PIO to buffer
-        self.dma = rp2.DMA()
-        req_num = ((self.sm_id // 4) << 3) + (self.sm_id % 4) + 4
+        self._dma = rp2.DMA()
+        req_num = ((self._sm_id // 4) << 3) + (self._sm_id % 4) + 4
         bytes_per_transfer = 4
-        dma_ctrl = self.dma.pack_ctrl(
+        dma_ctrl = self._dma.pack_ctrl(
             # 0 = 1 byte, 1 = 2 bytes, 2 = 4 bytes
             size = {1:0, 2:1, 4:2}[bytes_per_transfer],
             inc_read = False,
             treq_sel = req_num,
             bswap = byte_swap
         )
-        self.dma.config(
-            read = self.sm,
+        self._dma.config(
+            read = self._sm,
             count = bytes_per_frame // bytes_per_transfer,
             ctrl = dma_ctrl
         )
 
-    def active(self, active = None):
+    def _active(self, active=None):
+        """
+        Sets or gets the active state of the DVP interface.
+
+        Args:
+            active (bool, optional):
+                - True: Activate the DVP interface
+                - False: Deactivate the DVP interface
+                - None: Get the current active state
+        """
         # If no argument is provided, return the current active state
         if active == None:
-            return self.sm.active()
+            return self._sm.active()
 
         # Disable the DMA, the VSYNC handler will re-enable it when needed
-        self.dma.active(False)
+        self._dma.active(False)
 
         # Set the active state of the state machine
-        self.sm.active(active)
+        self._sm.active(active)
 
         # If active, set up the VSYNC interrupt handler
         if active:
-            Pin(self.pin_vsync).irq(
+            Pin(self._pin_vsync).irq(
                 trigger = Pin.IRQ_FALLING,
                 handler = lambda pin: self._vsync_handler()
             )
         # If not active, disable the VSYNC interrupt handler
         else:
-            Pin(self.pin_vsync).irq(
+            Pin(self._pin_vsync).irq(
                 handler = None
             )
 
     def _vsync_handler(self):
+        """
+        Handles the VSYNC interrupt to capture a frame of data.
+        """
         # Disable DMA before reconfiguring it
-        self.dma.active(False)
+        self._dma.active(False)
 
         # Reset state machine to ensure ISR is cleared
-        self.sm.restart()
+        self._sm.restart()
 
         # Ensure PIO RX FIFO is empty (it's not emptied by `sm.restart()`)
-        while self.sm.rx_fifo() > 0:
-            self.sm.get()
+        while self._sm.rx_fifo() > 0:
+            self._sm.get()
 
         # Reset the DMA write address
-        self.dma.write = self.buffer
+        self._dma.write = self._buffer
 
         # Start the DMA
-        self.dma.active(True)
+        self._dma.active(True)
 
     # Here is the PIO program, which is configurable to mask in the GPIO pins
     # and the number of data pins. It must be configured before the state
@@ -121,6 +157,9 @@ def _vsync_handler(self):
             fifo_join = rp2.PIO.JOIN_RX
         )
     def _pio_read_dvp():
+        """
+        PIO program to read DVP data from the GPIO pins.
+        """
         wait(1, gpio, 0) # Mask in HSYNC pin
         wait(1, gpio, 0) # Mask in PCLK pin
         in_(pins, 1)     # Mask in number of pins