esp-layrz 1.0.0

Professional ESP-IDF Shield Toolchain for advanced development

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:

# 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?