Skip to content

Commit 4f930cc

Browse files
sfe-SparkFrosfe-SparkFro
committed
Updates for v1.0.0
1 parent fce8a06 commit 4f930cc

File tree

2 files changed

+44
-36
lines changed

2 files changed

+44
-36
lines changed

‎README.md

Lines changed: 43 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -8,25 +8,39 @@ Welcome to SparkFun's Red Vision package! It contains MicroPython [drivers](red_
88

99
# Quick Start
1010

11+
## Flash Red Vision MicroPython Firmware
12+
13+
> [!Warning]
14+
> Back up the files on your MicroPython device, they *will* be overwritten!
15+
1116
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.
17+
* [Download the latest Red Vision firmware](https://github.com/sparkfun/micropython/releases) for your board (`RED_VISION_MICROPYTHON_xyz`).
18+
* Flash the firmware to your board.
1419
* 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
1620
* 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.
1721
* 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.
22+
2. Configure drivers
23+
* An example module called [`rv_init`](red_vision_examples/rv_init/) is imported by all examples to initialize the Red Vision drivers. You will likely need to edit the files for your specific hardware and board configuration.
1924
3. Write and run OpenCV code
2025
* Any IDE should work, so use your favorite!
2126
* Start with the examples! Go through them in order, which will verify your hardware is working and demonstrate some basics of OpenCV.
2227
* See [our MicroPython port of OpenCV](https://github.com/sparkfun/micropython-opencv) for more information about how to use it.
2328

29+
## Install Red Vision with `mip`
30+
31+
> [!Note]
32+
> This will only install the [hardware drivers](red_vision). It does not include the [examples](red_vision_examples), nor does it include [OpenCV](https://github.com/sparkfun/micropython-opencv).
33+
34+
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:
35+
36+
```
37+
mpremote mip install github:sparkfun/red_vision
38+
```
39+
2440
# Hardware Support
2541

2642
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).
2743

28-
Below is the list of currently supported hardware. It's currently very small, but may be expanded in the future.
29-
3044
## MicroPython Devices
3145

3246
| Status | Device | Notes |
@@ -37,71 +51,64 @@ Below is the list of currently supported hardware. It's currently very small, bu
3751

3852
| Status | Device | Notes |
3953
| --- | --- | --- |
40-
| ✔️ | HM01B0 | |
54+
| ✔️ | [HM01B0](https://www.sparkfun.com/sparkfun-red-vision-camera-board-hm01b0-color.html) | |
4155
| ⚠️ | [OV5640](https://www.sparkfun.com/ov5640-camera-board-5-megapixel-2592x1944-fisheye-lens.html) | See [#1](https://github.com/sparkfun/red_vision/issues/1) |
4256

4357
## Display Drivers
4458

4559
| Status | Device | Notes |
4660
| --- | --- | --- |
47-
| ✔️ | ST7789 | |
61+
| ✔️ | [ST7789](https://www.sparkfun.com/sparkfun-red-vision-touch-display-for-pico.html) | |
4862

4963
## Touch Screen Drivers
5064

5165
| Status | Device | Notes |
5266
| --- | --- | --- |
53-
| ✔️ | CST816 | |
67+
| ✔️ | [CST816](https://www.sparkfun.com/sparkfun-red-vision-touch-display-for-pico.html) | |
5468

5569
# Performance
5670

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.
71+
See the [MicroPython-OpenCV README](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.
5872

5973
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).
6074

6175
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.
6276

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
77+
# Building Red Vision MicroPython Firmware
7278

73-
If you're building MicroPython firmware from scratch and want to freeze Red Vision into your firmware, perform the following:
79+
Below are instructions to build the Red Vision MicroPython firmware from scratch:
7480

7581
1. Clone this repo and MicroPython
7682
* ```
7783
cd ~
7884
git clone https://github.com/sparkfun/red_vision.git
7985
cd red_vision
80-
git submodule update --init
86+
git submodule update --init --recursive
8187
cd ~
8288
git clone https://github.com/micropython/micropython.git
8389
```
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:
90+
2. (Optional) Archive the [red_vision_examples](red_vision_examples) folder so it can be frozen into the firmware and made available in the MicroPython filesystem in an editable folder
8691
* ```
8792
pip install freezefs
8893
python3 -m freezefs red_vision/red_vision_examples red_vision/extract_red_vision_examples.py --on-import=extract --compress --overwrite always
8994
```
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.
95+
* 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.
96+
* 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.
9297
3. Build Red Vision MicroPython firmware
9398
* ```
94-
make -C red_vision PORT_DIR=~/micropython/ports/rp2/ BOARD=SPARKFUN_XRP_CONTROLLER -j4
99+
make -C micropython/ports/rp2/ \
100+
BOARD=SPARKFUN_XRP_CONTROLLER \
101+
BOARD_VARIANT=RED_VISION \
102+
USER_C_MODULES=~/red_vision/micropython-opencv/micropython_opencv.cmake \
103+
FROZEN_MANIFEST=~/red_vision/manifest.py" \
104+
-j4
95105
```
96106
* 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.
107+
* The Red Vision [`manifest.py`](manifest.py) does a few things:
108+
* It retains your board's original manifest file, so all modules that are normally frozen for your board are still included.
109+
* It freezes the [`red_vision`](red_vision) directory as a module that can be imported.
110+
* 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 for extra storage.
111+
* 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.
105112
106113
# Contributing
107114
@@ -111,4 +118,5 @@ First, please see if there is an [existing issue](https://github.com/sparkfun/mi
111118
112119
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.
113120
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.
121+
> [!Note]
122+
> 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.

‎micropython-opencv

0 commit comments

Comments
 (0)