esp-layrz 1.0.0
Professional ESP-IDF Shield Toolchain for advanced development
Requires Python: >=3.11

# esp-layrz: Professional ESP-IDF Shield Toolchain

**esp-layrz** is a high-level CLI wrapper designed to abstract the complexity of the **ESP-IDF** environment on Windows. It provides a clean, professional interface by eliminating visual noise, automating dependency detection, and ensuring environment synchronization.

## 🚀 Technical Evolution & Engineering

The current version of `esp-layrz` is the result of solving three critical engineering challenges:

### 1. Environment Synchronization (The "3.11 vs 3.12" Fix)

**The Problem:** ESP-IDF often coexists with multiple virtual environments. If the system attempts to run `idf.py` using a different Python interpreter than the one used during the framework installation, security warnings and compatibility errors occur.
**The Solution:** We implemented `sys.executable` binding. This ensures that `esp-layrz` and the underlying `idf.py` command use the exact same process, eliminating the common warning: *"Python interpreter is not from installed venv"*.

### 2. Dynamic Output Filtering (Clean UI)

**The Problem:** Recent versions of `esptool` (v5.0+) generate multiple deprecation warnings (`Warning: Deprecated`) due to internal framework changes beyond the user's control.
**The Solution:** A real-time stream interceptor using `subprocess.Popen` analyzes every line of output. Unless `--verbose` mode is active, the tool silences these warnings, keeping the terminal focused on hardware status and build progress.

### 3. Smart Path Discovery

**The Problem:** Hardcoded paths (e.g., `C:\Espressif...`) break the tool if the framework is updated or moved to a different drive.
**The Solution:** A cascading search logic was implemented. It prioritizes the `IDF_PATH` environment variable, followed by dynamic pattern matching (`glob`) to locate the most recent framework version automatically.

---

## 🛠 Installation & Setup

### Pre-Installation Requirements

1. **ESP-IDF Installed:** A working Espressif installation (v5.x recommended) located at `C:\Espressif` or defined in your `IDF_PATH`.
2. **Active Environment:** You should run the installation from within the ESP-IDF PowerShell/CMD or have the Espressif Python environment active.

### Installation Process

From the root of the project:

```powershell
# Install in editable mode for immediate updates
pip install -e .

```

### Post-Installation Verification

1. **Check Paths:** Run `esp-layrz info` to confirm `IDF_PATH` points to your current version.
2. **Test Sync:** Run `esp-layrz run --version`. A clean output confirms successful synchronization.
3. **Auto-Detection:** Connect your ESP32 and run `esp-layrz flash`. The system will automatically detect the COM port.

---

## 📖 Command Reference

| Command | Description |
| --- | --- |
| `esp-layrz -v [cmd]` | **Verbose Mode:** Shows all hidden deprecation warnings and debug info. |
| `esp-layrz run "[args]"` | **Passthrough:** Directly execute any `idf.py` command (e.g., `menuconfig`). |
| `esp-layrz info` | **Environment Info:** Displays detected paths and active Python versions. |
| `esp-layrz full-clean` | **Deep Clean:** Removes both `build/` folder and `sdkconfig`. |

---

## ⏩ Future Roadmap: Python 3.13 & 3.14

`esp-layrz` is built with a "Future-Proof" architecture to adopt upcoming Python releases.

* **Python 3.13 Support:** We are preparing for the removal of the GIL (Free-threaded CPython). Our `run_idf` engine will evolve to use improved buffer management to ensure filtering doesn't degrade performance in multi-threaded environments.
* **Python 3.14 Preparation:** We plan to migrate all path logic to a full `pathlib` implementation to leverage low-level optimizations expected in 3.14.
* **Bridge Logic:** The tool already includes the `IDF_SKIP_CHECK_PYTHON_REQUIREMENTS` flag, allowing it to act as a compatibility bridge. This enables you to experiment with cutting-edge Python versions even before ESP-IDF officially certifies them.

---

### Maintenance Note

If you update your ESP-IDF framework, there is no need to reinstall `esp-layrz`. The tool will scan your installation directory on startup and select the newest version automatically.

Would you like me to generate a **`pyproject.toml`** or **`setup.py`** that matches this professional documentation?