MrUnknownDE/OpenIris-ESPIDF
1
0
Fork 0
mirror of https://github.com/MrUnknownDE/OpenIris-ESPIDF.git synced 2026-04-11 18:53:44 +02:00
Code Issues Packages Projects Releases Wiki Activity

README.md

Browse Source
This commit is contained in:
PhosphorosVR
2025-08-22 12:45:42 +02:00
parent 40833490d4
commit 05e122ffdd
1 changed files with 146 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

194
README.md
View File

@@ -1,69 +1,167 @@
| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C6 | ESP32-H2 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- | -------- | -------- |
# Blink Example
## OpenIris-ESPIDF
(See the README.md file in the upper level 'examples' directory for more information about examples.)
Firmware and tools for OpenIris on ESP32/ESP32‑S3 — Wi‑Fi, UVC streaming, and a handy Python setup CLI.
This example demonstrates how to blink a LED by using the GPIO driver or using the [led_strip](https://components.espressif.com/component/espressif/led_strip) library if the LED is addressable e.g. [WS2812](https://cdn-shop.adafruit.com/datasheets/WS2812B.pdf). The `led_strip` library is installed via [component manager](main/idf_component.yml).
Short, friendly, and practical.
## How to Use Example
---
Before project configuration and build, be sure to set the correct chip target using `idf.py set-target <chip_name>`.
## What’s inside
- ESP‑IDF firmware (C/C++) with modules for Camera, Wi‑Fi, UVC, REST/Serial commands, and more
- Python tools to make setup easy over USB serial:
- `tools/switchBoardType.py` — choose a board profile (loads the right sdkconfig)
- `tools/openiris_setup.py` — interactive CLI for Wi‑Fi, MDNS/Name, Mode, LED PWM, Logs, and a Settings Summary
- `tools/wifi_scanner.py` — optional Wi‑Fi scanner
### Hardware Required
---
* A development board with normal LED or addressable LED on-board (e.g., ESP32-S3-DevKitC, ESP32-C6-DevKitC etc.)
* A USB cable for Power supply and programming
## Prerequisites
- ESP‑IDF installed and available in your terminal (`idf.py` works)
- Python 3.10+ with `pip`
- USB cable to your board
- Optional: install Python dependencies for the tools
See [Development Boards](https://www.espressif.com/en/products/devkits) for more information about it.
Windows (cmd):
```cmd
python -m pip install -r tools\requirements.txt
```
macOS/Linux (bash):
```bash
python3 -m pip install -r tools/requirements.txt
```
Note for Windows: If emojis don’t render nicely, it’s only cosmetic — everything still works.
### Configure the Project
---
Open the project configuration menu (`idf.py menuconfig`).
## First-time setup on Windows (VS Code + ESP‑IDF extension)
If you’re starting fresh on Windows, this workflow is smooth and reliable:
In the `Example Configuration` menu:
1) Install tooling
- Git: https://git-scm.com/downloads/win
- Visual Studio Code: https://code.visualstudio.com/
* Select the LED type in the `Blink LED type` option.
* Use `GPIO` for regular LED
* Use `LED strip` for addressable LED
* If the LED type is `LED strip`, select the backend peripheral
* `RMT` is only available for ESP targets with RMT peripheral supported
* `SPI` is available for all ESP targets
* Set the GPIO number used for the signal in the `Blink GPIO number` option.
* Set the blinking period in the `Blink period in ms` option.
### Build and Flash
Run `idf.py -p PORT flash monitor` to build, flash and monitor the project.
(To exit the serial monitor, type ``Ctrl-]``.)
See the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.
## Example Output
As you run the example, you will see the LED blinking, according to the previously defined period. For the addressable LED, you can also change the LED color by setting the `led_strip_set_pixel(led_strip, 0, 16, 16, 16);` (LED Strip, Pixel Number, Red, Green, Blue) with values from 0 to 255 in the [source file](main/blink_example_main.c).
```text
I (315) example: Example configured to blink addressable LED!
I (325) example: Turning the LED OFF!
I (1325) example: Turning the LED ON!
I (2325) example: Turning the LED OFF!
I (3325) example: Turning the LED ON!
I (4325) example: Turning the LED OFF!
I (5325) example: Turning the LED ON!
I (6325) example: Turning the LED OFF!
I (7325) example: Turning the LED ON!
I (8325) example: Turning the LED OFF!
2) Get the source code
- Create a folder where you want the repo (e.g., `D:\OpenIris-ESPIDF\`). In File Explorer, right‑click the folder and choose “Open in Terminal”.
- Clone and open in VS Code:
```cmd
git clone https://github.com/lorow/OpenIris-ESPIDF.git
cd OpenIris-ESPIDF
code .
```
Note: The color order could be different according to the LED model.
3) Install the ESP‑IDF VS Code extension
- In VS Code, open the Extensions tab and install: https://marketplace.visualstudio.com/items?itemName=espressif.esp-idf-extension
The pixel number indicates the pixel position in the LED strip. For a single LED, use 0.
4) Set the default terminal profile to Command Prompt
- Press Ctrl+Shift+P → search “Terminal: Select Default Profile” → choose “Command Prompt”.
- Restart VS Code from its normal shortcut (not from Git Bash). This avoids running ESP‑IDF in the wrong shell.
5) Configure ESP‑IDF in the extension
- On first launch, the extension may prompt to install ESP‑IDF and tools — follow the steps. It can take a while.
- If you see the extension’s home page instead, click “Configure extension”, pick “EXPRESS”, choose “GitHub” as the server and version “v5.3.3”.
- Then open the ESP‑IDF Explorer tab and click “Open ESP‑IDF Terminal”. We’ll use that for builds.
6) Default board profile and switching
- The project ships with multiple board profiles; one default may target internal “Project Babble” boards.
- If you have a Seeed XIAO ESP32S3 (or another board), switch the profile with the helper script:
```cmd
python .\tools\switchBoardType.py --board xiao-esp32s3 --diff
```
- You can re‑run this anytime to switch boards; `--diff` shows the changes.
After this, you’re ready for the Quick start below.
---
## Quick start
### 1) Pick your board (loads the default configuration)
Windows (cmd):
```cmd
python .\tools\switchBoardType.py --board xiao-esp32s3 --diff
```
macOS/Linux (bash):
```bash
python3 ./tools/switchBoardType.py --board xiao-esp32s3 --diff
```
- Set `--board` to your target board
- `--diff` shows what changed in the config
### 2) Build & flash
- Set the target (e.g., ESP32‑S3):
```cmd
idf.py set-target esp32s3
```
- Build, flash, and open the serial monitor:
```cmd
idf.py -p COM15 flash monitor
```
Replace `COM15` with your port (Windows: `COM…`, Linux: `/dev/ttyUSB…`, macOS: `/dev/cu.usbmodem…`).
Exit the monitor with `Ctrl+]`.
### 3) Use the Python setup CLI (recommended)
Configure the device conveniently over USB serial.
Windows (cmd):
```cmd
python .\tools\openiris_setup.py --port COM15
```
macOS/Linux (bash):
```bash
python3 ./tools/openiris_setup.py --port /dev/ttyUSB0
```
What the CLI can do:
- Wi‑Fi menu: automatic (scan → pick → password → connect → wait for IP) or manual (scan, show, configure, connect, status)
- Set MDNS/Device name (also used for the UVC device name)
- Switch mode (Wi‑Fi / UVC / Auto)
- Adjust LED PWM
- Show a Settings Summary (MAC, Wi‑Fi status, mode, PWM, …)
- View logs
Tip: On start, the CLI keeps the device in a setup state so replies are stable.
---
## Serial number & MAC
- Internally, the serial number is derived from the Wi‑Fi MAC address.
- The CLI displays the MAC by default (clearer); it’s the value used as the serial number.
- The UVC device name is based on the MDNS hostname.
---
## Common workflows
- Fast Wi‑Fi setup: in the CLI, go to “Wi‑Fi settings” → “Automatic setup”, then check “status”.
- Change name/MDNS: set the device name in the CLI, then replug USB — UVC will show the new name.
- Adjust brightness/LED: set LED PWM in the CLI.
- Quick health check: run “Get settings summary” after flashing to verify the device state.
---
## Project layout (short)
- `main/` — entry point
- `components/` — modules (Camera, WiFi, UVC, CommandManager, …)
- `tools/` — Python helper tools (board switch, setup CLI, scanner)
If you want to dig deeper: commands are mapped via the `CommandManager` under `components/CommandManager/...`.
---
## Troubleshooting
- No device/port found?
- Pass `--port` explicitly (e.g., `--port COM15`).
- Right after reset, the device emits heartbeats for a short time; the CLI finds it fastest during that window.
- UVC doesn’t appear on the host?
- Switch mode to UVC and replug USB. On Windows the first driver init can take a moment.
- Wi‑Fi won’t connect?
- Check password/channel. Use the automatic setup in the CLI and then inspect the status.
- ESP‑IDF not detected?
- Ensure the ESP‑IDF environment is active in the terminal (IDF Command Prompt or the extension’s ESP‑IDF Terminal; alternatively source `export.ps1`/`export.sh`).
- Missing Python modules?
- Run `pip install -r tools/requirements.txt`.
* If the LED isn't blinking, check the GPIO or the LED type selection in the `Example Configuration` menu.
---
For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.
Have fun with OpenIris! Feedback, issues, and PRs are welcome.