Skip to content

Commit fce8a06

Browse files
sfe-SparkFrosfe-SparkFro
authored
Merge pull request #3 from sparkfun/v1.0.0
2 parents 4c52594 + 26c2ba3 commit fce8a06

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+4443
-1
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
extract_red_vision_examples.py

‎.gitmodules

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[submodule "micropython-opencv"]
2+
path = micropython-opencv
3+
url = https://github.com/sparkfun/micropython-opencv.git

‎README.md

Lines changed: 114 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,114 @@
1-
# red_vision
1+
<p align="center">
2+
<img src="red_vision_examples/images/splash.png" />
3+
</p>
4+
5+
# SparkFun Red Vision
6+
7+
Welcome to SparkFun's Red Vision package! It contains MicroPython [drivers](red_vision) for SparkFun Red Vision products, and [examples](red_vision_examples) demonstrating how to use those drivers in conjunction with [our MicroPython port of OpenCV](https://github.com/sparkfun/micropython-opencv).
8+
9+
# Quick Start
10+
11+
1. Flash Red Vision MicroPython firmware to your board
12+
* Back up any files you want to keep, they *will* be overwritten!
13+
* Download the latest Red Vision firmware for your board from the [Releases tab of our MicroPython fork](https://github.com/sparkfun/micropython/releases) (`RED_VISION_MICROPYTHON_xyz`) and flash it to your board.
14+
* If you don't know how to flash firmware to your board, find your board [here](https://micropython.org/download/) and follow the instructions using the OpenCV firmware.
15+
2. Configure driver initialization
16+
* After first boot, the [`red_vision_examples`](red_vision_examples) directory will be automatically extraced to the MicroPython filesystem for easy access to all the examples.
17+
* You can safely edit these examples, and they will not be overwritten. If you want to restore the examples, delete the `restore_examples.txt` file and reboot your board.
18+
* Inside that directory, an example module called [`rv_init`](red_vision_examples/rv_init/) is imported by all examples to initialize the drivers. You will likely need to edit the files for your specific hardware and board configuration.
19+
3. Write and run OpenCV code
20+
* Any IDE should work, so use your favorite!
21+
* Start with the examples! Go through them in order, which will verify your hardware is working and demonstrate some basics of OpenCV.
22+
* See [our MicroPython port of OpenCV](https://github.com/sparkfun/micropython-opencv) for more information about how to use it.
23+
24+
# Hardware Support
25+
26+
Hardware support in this repository is mostly limited to SparkFun Red Vision products. We may consider pull requests that add support for additional hardware, see [#Contributing](#Contributing).
27+
28+
Below is the list of currently supported hardware. It's currently very small, but may be expanded in the future.
29+
30+
## MicroPython Devices
31+
32+
| Status | Device | Notes |
33+
| --- | --- | --- |
34+
| ✔️ | [XRP Controller](https://www.sparkfun.com/sparkfun-experiential-robotics-platform-xrp-controller.html) | |
35+
36+
## Camera Drivers
37+
38+
| Status | Device | Notes |
39+
| --- | --- | --- |
40+
| ✔️ | HM01B0 | |
41+
| ⚠️ | [OV5640](https://www.sparkfun.com/ov5640-camera-board-5-megapixel-2592x1944-fisheye-lens.html) | See [#1](https://github.com/sparkfun/red_vision/issues/1) |
42+
43+
## Display Drivers
44+
45+
| Status | Device | Notes |
46+
| --- | --- | --- |
47+
| ✔️ | ST7789 | |
48+
49+
## Touch Screen Drivers
50+
51+
| Status | Device | Notes |
52+
| --- | --- | --- |
53+
| ✔️ | CST816 | |
54+
55+
# Performance
56+
57+
See the [MicroPython-OpenCV READMA](https://github.com/sparkfun/micropython-opencv) general information about performance with OpenCV. For reference, the XRP (with Raspberry Pi RP2350) can run the [SparkFun Logo Detection Example](red_vision_examples/ex06_detect_sfe_logo.py) at 2 to 2.5 FPS at 320x240 resolution.
58+
59+
One way to improve performance is to select the best hardware drivers for your setup. For example, the default SPI driver for the ST7789 is limited to the max SPI baudrate for the processor's SPI peripheral. That's 24MHz in the case of the RP2350, but another driver is provided that uses the PIO peripheral that runs at 75MHz, so displaying images can be ~3x faster (not including required colorspace conversions).
60+
61+
For users wanting maximum performance, it may be desireable to bypass the high-level functions of the display/camera drivers, and instead work directly with the buffer member variables and read/write functions. This can avoid computationally expensive colorspace conversions when reading and writing images if they're not needed, but this is for advanced users only.
62+
63+
# Installing Red Vision with `mip`
64+
65+
If you want to add the Red Vision package to a board that's already running MicroPython, you can easily install it using [`mip`](https://docs.micropython.org/en/latest/reference/packages.html). For example, here's the [`mpremote`](https://docs.micropython.org/en/latest/reference/mpremote.html) command:
66+
67+
```
68+
mpremote mip install github:sparkfun/red_vision
69+
```
70+
71+
## Building Red Vision MicroPython Firmware
72+
73+
If you're building MicroPython firmware from scratch and want to freeze Red Vision into your firmware, perform the following:
74+
75+
1. Clone this repo and MicroPython
76+
* ```
77+
cd ~
78+
git clone https://github.com/sparkfun/red_vision.git
79+
cd red_vision
80+
git submodule update --init
81+
cd ~
82+
git clone https://github.com/micropython/micropython.git
83+
```
84+
2. (Optional) Archive the [red_vision_examples](red_vision_examples) folder so it can be frozen into the firmware
85+
* If you want the examples to be available in the MicroPython filesystem in an editable folder, run the following:
86+
* ```
87+
pip install freezefs
88+
python3 -m freezefs red_vision/red_vision_examples red_vision/extract_red_vision_examples.py --on-import=extract --compress --overwrite always
89+
```
90+
* This will use [`freezefs`](https://github.com/bixb922/freezefs) to build the examples folder into a compressed and self-extracting archive that can be frozen into the firmware.
91+
* The benefit of using `freezefs` is that it can extract the contents into a folder that you can easily view and edit, whereas simply freezing the folder with the normal MicroPython manifest system would mean the examples are not editable or viewable.
92+
3. Build Red Vision MicroPython firmware
93+
* ```
94+
make -C red_vision PORT_DIR=~/micropython/ports/rp2/ BOARD=SPARKFUN_XRP_CONTROLLER -j4
95+
```
96+
* Replace `rp2` and `SPARKFUN_XRP_CONTROLLER` with your platform and board name respectively
97+
* The [`Makefile`](Makefile) does a few things:
98+
* It sets `BOARD_VARIANT` to `RED_VISION`. That variant must be created if it hasn't been already.
99+
* It sets `USER_C_MODULES` to [`micropython-opencv`](micropython-opencv) so OpenCV is built into the firmware.
100+
* It sets `FROZEN_MANIFEST` to the Red Vision [`manifest.py`](manifest.py), which does a few things:
101+
* It retains your board's original manifest file, so all modules that are normally frozen for your board are still included.
102+
* It freezes the [`red_vision`](red_vision) directory as a module that can be imported.
103+
* It also includes the [`sdcard`](https://github.com/micropython/micropython-lib/tree/master/micropython/drivers/storage/sdcard) module, which is not normally included in MicroPython, but is very useful if you're working with images.
104+
* If the examples folder was archived, it will be included. It will additionally freeze the [`boot.py`](boot.py) file into the firmware, which will automatically unpack the examples if needed.
105+
106+
# Contributing
107+
108+
Found a bug? Want support for other hardware?
109+
110+
First, please see if there is an [existing issue](https://github.com/sparkfun/micropython-opencv/issues). If not, then please [open a new issue](https://github.com/sparkfun/micropython-opencv/issues/new) so we can discuss the topic!
111+
112+
Pull requests are welcome! Please keep the scope of your pull request focused (make separate ones if needed), and keep file changes limited to the scope of your pull request.
113+
114+
Keep in mind that we only intend to support SparkFun Red Vision products in this repository, though we may be open to hosting support for some hardware from other vendors. Please first open an issue to check if we're open to it.

‎boot.py

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Check whether `restore_examples.txt` exists
2+
import os
3+
try:
4+
os.stat('red_vision_examples/restore_examples.txt')
5+
# If this succeeds, the file exists, so we don't need to do anything
6+
except OSError:
7+
# If we get here, it means the file doesn't exist, so we should unpack the
8+
# examples folder and create the file
9+
import extract_red_vision_examples
10+
file = open('red_vision_examples/restore_examples.txt', 'w')
11+
file.write('''Hi!
12+
13+
This folder is frozen into the firmware. To make it accessible, a special
14+
boot.py script that's also frozen into the firmware automatically unpacks the
15+
frozen folder to an editable location on the filesystem. It will only unpack the
16+
folder if this `restore_examples.txt` file is missing, so you can safely edit
17+
the examples here without your changes being overwritten. If you want to restore
18+
the examples to their original state, delete this file and reboot your board.
19+
''')
20+
file.close()
21+
22+
# Clean up to avoid cluttering the namespace
23+
del extract_red_vision_examples, file
24+
25+
# The examples folder has an importable module, so we need to add it to the path
26+
import sys
27+
sys.path.append('red_vision_examples')
28+
29+
# Clean up to avoid cluttering the namespace
30+
del os, sys

‎manifest.py

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Include the board's original manifest file
2+
include("$(BOARD_DIR)/manifest.py")
3+
4+
# Include the Red Vision directory as one package
5+
package("red_vision")
6+
7+
# Ensure the SD card module is included
8+
require("sdcard")
9+
10+
# Check if the examples directory has been archived
11+
import os
12+
try:
13+
os.stat('extract_red_vision_examples.py')
14+
15+
# If we get here, then the examples directory has been archived and we can
16+
# add it to the manifest so it gets frozen into the firmware
17+
module("extract_red_vision_examples.py")
18+
19+
# Also freeze the boot script that automatically unpacks the examples
20+
module("boot.py")
21+
except OSError:
22+
# The examples directory has not been archived, nothing to do
23+
pass

‎micropython-opencv

Submodule micropython-opencv added at e502357

‎package.json

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"urls": [
3+
["red_vision/__init__.py", "red_vision/__init__.py"],
4+
["red_vision/cameras/__init__.py", "red_vision/cameras/__init__.py"],
5+
["red_vision/cameras/cv2_camera.py", "red_vision/cameras/cv2_camera.py"],
6+
["red_vision/cameras/dvp_camera.py", "red_vision/cameras/dvp_camera.py"],
7+
["red_vision/cameras/dvp_rp2_pio.py", "red_vision/cameras/dvp_rp2_pio.py"],
8+
["red_vision/cameras/hm01b0_pio.py", "red_vision/cameras/hm01b0_pio.py"],
9+
["red_vision/cameras/hm01b0.py", "red_vision/cameras/hm01b0.py"],
10+
["red_vision/cameras/ov5640_pio.py", "red_vision/cameras/ov5640_pio.py"],
11+
["red_vision/cameras/ov5640.py", "red_vision/cameras/ov5640.py"],
12+
["red_vision/displays/__init__.py", "red_vision/displays/__init__.py"],
13+
["red_vision/displays/cv2_display.py", "red_vision/displays/cv2_display.py"],
14+
["red_vision/displays/st7789_pio.py", "red_vision/displays/st7789_pio.py"],
15+
["red_vision/displays/st7789_spi.py", "red_vision/displays/st7789_spi.py"],
16+
["red_vision/displays/st7789.py", "red_vision/displays/st7789.py"],
17+
["red_vision/touch_screens/__init__.py", "red_vision/touch_screens/__init__.py"],
18+
["red_vision/touch_screens/cst816.py", "red_vision/touch_screens/cst816.py"],
19+
["red_vision/touch_screens/cv2_touch_screen.py", "red_vision/touch_screens/cv2_touch_screen.py"]
20+
],
21+
"version": "1.0.0"
22+
}

‎red_vision/__init__.py

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#-------------------------------------------------------------------------------
2+
# SPDX-License-Identifier: MIT
3+
#
4+
# Copyright (c) 2025 SparkFun Electronics
5+
#-------------------------------------------------------------------------------
6+
# cv2_drivers/touch_screens/__init__.py
7+
#
8+
# Imports all available drivers for MicroPython OpenCV.
9+
#-------------------------------------------------------------------------------
10+
11+
from . import displays
12+
from . import cameras
13+
from . import touch_screens

‎red_vision/cameras/__init__.py

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
#-------------------------------------------------------------------------------
2+
# SPDX-License-Identifier: MIT
3+
#
4+
# Copyright (c) 2025 SparkFun Electronics
5+
#-------------------------------------------------------------------------------
6+
# cv2_drivers/cameras/__init__.py
7+
#
8+
# Imports all available camera drivers for MicroPython OpenCV.
9+
#-------------------------------------------------------------------------------
10+
11+
# Import sys module to check platform
12+
import sys
13+
14+
# Import RP2 drivers
15+
if 'rp2' in sys.platform:
16+
from . import hm01b0_pio
17+
from . import ov5640_pio

‎red_vision/cameras/cv2_camera.py

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
#-------------------------------------------------------------------------------
2+
# SPDX-License-Identifier: MIT
3+
#
4+
# Copyright (c) 2025 SparkFun Electronics
5+
#-------------------------------------------------------------------------------
6+
# cv2_camera.py
7+
#
8+
# Base class for OpenCV camera drivers.
9+
#-------------------------------------------------------------------------------
10+
11+
class CV2_Camera():
12+
"""
13+
Base class for OpenCV camera drivers.
14+
"""
15+
def __init__(self):
16+
"""
17+
Initializes the camera.
18+
"""
19+
pass
20+
21+
def open(self):
22+
"""
23+
Opens the camera and prepares it for capturing images.
24+
"""
25+
raise NotImplementedError("open() must be implemented by driver")
26+
27+
def release(self):
28+
"""
29+
Releases the camera and frees any resources.
30+
"""
31+
raise NotImplementedError("release() must be implemented by driver")
32+
33+
def read(self, image=None):
34+
"""
35+
Reads an image from the camera.
36+
37+
Args:
38+
image (ndarray, optional): Image to read into
39+
40+
Returns:
41+
tuple: (success, image)
42+
- success (bool): True if the image was read, otherwise False
43+
- image (ndarray): The captured image, or None if reading failed
44+
"""
45+
raise NotImplementedError("read() must be implemented by driver")

0 commit comments

Comments
 (0)