From 05e122ffdd3db530a681db20a751fb4cb96c2ed0 Mon Sep 17 00:00:00 2001 From: PhosphorosVR Date: Fri, 22 Aug 2025 12:45:42 +0200 Subject: [PATCH] README.md --- README.md | 194 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 146 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 8e6e412..ddfdd99 100644 --- a/README.md +++ b/README.md @@ -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 `. +## 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.