Firmware and tools for OpenIris -- Wi-Fi, UVC streaming, and a Python setup CLI.

• 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/setup_openiris.py -- interactive CLI for Wi-Fi, MDNS/Name, Mode, LED PWM, Logs, and a Settings Summary
• Composite USB (UVC + CDC) when UVC mode is enabled (GENERAL_INCLUDE_UVC_MODE) for simultaneous video streaming and command channel
• LED current monitoring (if enabled via MONITORING_LED_CURRENT) with filtered mA readings
• Battery voltage monitoring (if enabled via MONITORING_BATTERY_ENABLE) with Li-ion SOC percentage calculation
• Configurable debug LED + external IR LED control with optional error mirroring (LED_DEBUG_ENABLE, LED_EXTERNAL_AS_DEBUG)
• Auto-discovered per-board configuration overlays under boards/
• Command framework (JSON over serial / CDC / REST) for mode switching, Wi-Fi config, OTA credentials, LED brightness, info & monitoring
• Single source advertised name (CONFIG_GENERAL_ADVERTISED_NAME) used for both UVC device name and mDNS hostname (unless overridden at runtime)

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

1. Install tooling

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

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:

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

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

We're using UV to manage our tools, grab and install it from here.

Once installed, you'll be able to just run the commands below and UV will take care of setting up everything.

Boards are auto-discovered from the boards/ directory. First list them, then pick one:

Windows (cmd):

macOS/Linux (bash):

Notes:

• Use --list to see all detected board keys.
• Board key = relative path under boards/ with / replaced by _ (and duplicate tail segments collapsed, e.g. project_babble/project_babble -> project_babble).
• --diff shows what will change vs the current sdkconfig.
• You can also pass partial or path-like inputs (e.g. facefocusvr/eye_L), the tool normalizes them.

• Set the target (e.g., ESP32-S3).
• Build, flash, and open the serial monitor.
• (Optional) For UVC mode ensure GENERAL_INCLUDE_UVC_MODE=y. If you want device to boot directly into UVC: also set START_IN_UVC_MODE=y.
• Disable Wi-Fi services for pure wired builds: GENERAL_ENABLE_WIRELESS=n.

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

Then run:

Examples:

• Windows: uv run .\tools\setup_openiris.py --port COM69, ...
• macOS: uv run .\tools\setup_openiris.py --port \dev\tty
• Linux: uv run .\tools\setup_openiris.py --port \dev\tty

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 / Setup)
• Adjust LED PWM
• Show a Settings Summary (MAC, Wi-Fi status, mode, PWM, ...)
• View logs

• 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.

CONFIG_GENERAL_ADVERTISED_NAME (Kconfig) defines the base name announced over:

• USB UVC descriptor (appears in OS camera list)
• mDNS hostname / service name

Runtime override: If the setup CLI (or a JSON command) provides a new device name, that value supersedes the compile-time default until next flash/reset of settings.

• 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.
• Switch to UVC mode over commands (CDC/serial): {"commands":[{"command":"switch_mode","data":{"mode":"uvc"}}]} then reboot.
• Read filtered LED current (if enabled): {"commands":[{"command":"get_led_current"}]}
• Read battery status (if enabled): {"commands":[{"command":"get_battery_status"}]}

• main/ -- entry point
• components/ -- modules (Camera, WiFi, UVC, CommandManager, ...)
• tools/ -- Python helper tools (board switch, setup CLI, scanner)
• tests/ - Hardware in the loop tests, with support for different boards and automatic skips if a board can't perform a given test If you want to dig deeper: commands are mapped via the CommandManager under components/CommandManager/....

In order to run the tests, you'll need to setup a couple of things:

• copy the .env.example file in /tests/ and rename it to .env. Then, open it and fill out the network details - SSID and Password.
• plug in your board to your pc and wait for it to boot.
• open the terminal (ctrl/cmd + j in VSC) and head over to /tests/ directory.

Once there, you can invoke the tests with UV like so:

This will auto select every test we have, connect to your board automatically and have pytest skip tests that don't fit your board. For example, tests involving switching modes to UVC and testing commands over there are disabled for esp32 based boards as only esp32s3 can do it. Same goes for WiFi for FaceFocus Boards.

If you see any fails, you can try rerunning them one by one with:

Or rerun every single failed test like so:

Sometimes tests will fail due to timeouts, this is normal.

You should see the tests starting to go off, with any luck - all of them passing, your board should also start reacting to the changes - reboots, blinking lights etc are expected as we're performing hardware in the loop tests.