OpenIris-ESPIDF

ESP‑IDF firmware (C/C++) with modules for Camera, Wi‑Fi, UVC, REST/Serial commands, and more
Python tools for setup over USB serial:
- tools/switchBoardType.py — choose a board profile (builds the right sdkconfig)
- tools/openiris_setup.py — interactive CLI for Wi‑Fi, MDNS/Name, Mode, LED PWM, Logs, and a Settings Summary

First-time setup on Windows (VS Code + ESP‑IDF extension)

If you’re starting fresh on Windows, this workflow is smooth and reliable:

Install tooling

Git: https://git-scm.com/downloads/win
Visual Studio Code: https://code.visualstudio.com/

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:

git clone https://github.com/lorow/OpenIris-ESPIDF.git
cd OpenIris-ESPIDF
code .

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

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.

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.4.2”.
Then open the ESP‑IDF Explorer tab and click “Open ESP‑IDF Terminal”. We’ll use that for builds.

After this, you’re ready for the Quick start below.

Quick start

1) Pick your board (loads the default configuration)

Windows (cmd):

python .\tools\switchBoardType.py --board xiao-esp32s3 --diff

macOS/Linux (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).
Build, flash, and open the serial monitor.

3) Use the Python setup CLI (recommended)

Configure the device over USB serial.

Before you run it:

If you still have the serial monitor open, close it (the port must be free).
In VS Code, open the sidebar “ESP‑IDF: Explorer” and click “Open ESP‑IDF Terminal”. We’ll run the CLI there so Python and packages are in the right environment.

Then run:

python .\tools\openiris_setup.py --port COMxx

Examples:

Windows: python .\tools\openiris_setup.py --port COM69, …
macOS: idk
Linux: idk

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

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.

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

UVC doesn’t appear on the host?
- Switch mode to UVC via CLI tool, replug USB and wait 20s.

Feedback, issues, and PRs are welcome.

README.md Unescape Escape