First Release

.github/workflows/build.yml

@@ -1,18 +1,37 @@
 name: Build firmware
 
 on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - features_for_launch
   workflow_dispatch:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v4
+    - name: Checkout repository
+      uses: actions/checkout@v4
       with:
         submodules: true
-    - name: make
+    - name: Install packages
       run: |
-        sudo apt-get install gcc-arm-none-eabi libnewlib-arm-none-eabi
-        make -C micropython/mpy-cross
-        make -C micropython/ports/rp2 BOARD=SPARKFUN_XRP_CONTROLLER submodules
-        make BOARD=SPARKFUN_XRP_CONTROLLER
+        sudo apt install cmake python3 build-essential gcc-arm-none-eabi libnewlib-arm-none-eabi libstdc++-arm-none-eabi-newlib
+    - name: Build MPY Cross
+      run: make -C micropython/mpy-cross
+    - name: MicroPython submodules
+      run: make -C micropython/ports/rp2 BOARD=SPARKFUN_XRP_CONTROLLER submodules
+    - name: Set Pico SDK path
+      run: echo "PICO_SDK_PATH=$GITHUB_WORKSPACE/micropython/lib/pico-sdk" >> "$GITHUB_ENV"
+    - name: Build OpenCV
+      run: make -C src/opencv PLATFORM=rp2350 --no-print-directory -j4
+    - name: Build firmware
+      run: make BOARD=SPARKFUN_XRP_CONTROLLER -j4
+    - name: Upload UF2
+      uses: actions/upload-artifact@v4
+      with:
+        name: firmware.uf2
+        path: micropython/ports/rp2/build-SPARKFUN_XRP_CONTROLLER-LARGE_BINARY/firmware.uf2

.gitmodules

@@ -1,6 +1,6 @@
-[submodule "src/opencv"]
-	path = src/opencv
-	url = https://github.com/sfe-SparkFro/opencv.git
+[submodule "src/opencv/opencv"]
+	path = src/opencv/opencv
+	url = https://github.com/opencv/opencv.git
 [submodule "src/ulab"]
 	path = src/ulab
 	url = https://github.com/v923z/micropython-ulab.git

Makefile

@@ -7,14 +7,20 @@ CURRENT_DIR = $(shell pwd)
 # Set the MicroPython user C module path to the OpenCV module
 MAKE_ARGS = USER_C_MODULES="$(CURRENT_DIR)/src/opencv_upy.cmake"
 
+# Ensure we're building the OpenCV board variant
+MAKE_ARGS += BOARD_VARIANT=LARGE_BINARY
+
+# Use the OpenCV driver manifest
+MAKE_ARGS += FROZEN_MANIFEST="$(CURRENT_DIR)/manifest.py"
+
 # Build MicroPython with the OpenCV module
 all:
 	@cd micropython/ports/rp2 && export CMAKE_ARGS="$(CMAKE_ARGS)" && make -f Makefile $(MAKEFLAGS) $(MAKE_ARGS)
 
 # Clean the MicroPython build
 clean:
-	@cd micropython/ports/rp2 && make -f Makefile $(MAKEFLAGS) clean
+	@cd micropython/ports/rp2 && make -f Makefile $(MAKEFLAGS) $(MAKE_ARGS) clean
 
 # Load the MicroPython submodules
 submodules:
-	@cd micropython/ports/rp2 && make -f Makefile $(MAKEFLAGS) submodules
+	@cd micropython/ports/rp2 && make -f Makefile $(MAKEFLAGS) $(MAKE_ARGS) submodules

cv2_drivers/__init__.py

@@ -0,0 +1,13 @@
+#-------------------------------------------------------------------------------
+# SPDX-License-Identifier: MIT
+# 
+# Copyright (c) 2025 SparkFun Electronics
+#-------------------------------------------------------------------------------
+# cv2_drivers/touch_screens/__init__.py
+# 
+# Imports all available drivers for MicroPython OpenCV.
+#-------------------------------------------------------------------------------
+
+from . import displays
+from . import cameras
+from . import touch_screens

cv2_drivers/cameras/__init__.py

@@ -0,0 +1,17 @@
+#-------------------------------------------------------------------------------
+# SPDX-License-Identifier: MIT
+# 
+# Copyright (c) 2025 SparkFun Electronics
+#-------------------------------------------------------------------------------
+# cv2_drivers/cameras/__init__.py
+# 
+# Imports all available camera drivers for MicroPython OpenCV.
+#-------------------------------------------------------------------------------
+
+# 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

@@ -0,0 +1,45 @@
+#-------------------------------------------------------------------------------
+# SPDX-License-Identifier: MIT
+# 
+# Copyright (c) 2025 SparkFun Electronics
+#-------------------------------------------------------------------------------
+# cv2_camera.py
+# 
+# Base class for OpenCV camera drivers.
+#-------------------------------------------------------------------------------
+
+class CV2_Camera():
+    """
+    Base class for OpenCV camera drivers.
+    """
+    def __init__(self):
+        """
+        Initializes the camera.
+        """
+        pass
+
+    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

@@ -0,0 +1,60 @@
+#-------------------------------------------------------------------------------
+# SPDX-License-Identifier: MIT
+# 
+# Copyright (c) 2025 SparkFun Electronics
+#-------------------------------------------------------------------------------
+# dvp_camera.py
+# 
+# Base class for OpenCV DVP (Digital Video Port) camera drivers.
+#-------------------------------------------------------------------------------
+
+from .cv2_camera import CV2_Camera
+
+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
+
+    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.
+
+        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)

cv2_drivers/cameras/dvp_rp2_pio.py

@@ -0,0 +1,182 @@
+#-------------------------------------------------------------------------------
+# SPDX-License-Identifier: MIT
+# 
+# Copyright (c) 2025 SparkFun Electronics
+#-------------------------------------------------------------------------------
+# dvp_rp2_pio.py
+#
+# 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.
+# 
+# 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
+#-------------------------------------------------------------------------------
+
+import rp2
+from machine import Pin, PWM
+
+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,
+        pin_vsync,
+        pin_hsync,
+        pin_pclk,
+        pin_xclk,
+        xclk_freq,
+        sm_id,
+        num_data_pins,
+        bytes_per_frame,
+        byte_swap
+    ):
+        """
+        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):
+            Pin(pin_d0+i, Pin.IN)
+        Pin(pin_vsync, Pin.IN)
+        Pin(pin_hsync, Pin.IN)
+        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
+
+        # 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
+
+        # 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,
+            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
+        bytes_per_transfer = 4
+        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,
+            count = bytes_per_frame // bytes_per_transfer,
+            ctrl = dma_ctrl
+        )
+
+    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
+
+        Returns:
+            bool: Current active state if no argument is provided
+        """
+        # If no argument is provided, return the current active state
+        if active == None:
+            return self._sm.active()
+
+        # Disable the DMA, the VSYNC handler will re-enable it when needed
+        self._dma.active(False)
+
+        # Set the active state of the state machine
+        self._sm.active(active)
+
+        # If active, set up the VSYNC interrupt handler
+        if active:
+            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(
+                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)
+
+        # Reset state machine to ensure ISR is cleared
+        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()
+
+        # Reset the DMA write address
+        self._dma.write = self._buffer
+
+        # Start the DMA
+        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
+    # machine is created
+    @rp2.asm_pio(
+            in_shiftdir = rp2.PIO.SHIFT_LEFT,
+            push_thresh = 32,
+            autopush = True,
+            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
+        wait(0, gpio, 0) # Mask in PCLK pin