esp-bmgr-assist 0.2.0

ESP Board Manager Python package for idf.py extensions

esp-bmgr-assist

PyPI 发行版名：esp-bmgr-assist（pip install esp-bmgr-assist）。Python 包目录仍为 esp_bmgr_py（含 .pth 引导），与旧文档中的 esp-bmgr-py 仓库路径可并存。

这个包通过自动注入一段代码到 idf.py，为 ESP Board Manager 功能提供便捷使用支持。

功能特性

• 通过 .pth 文件实现自动注入
• 自动查找和设置 board manager 组件路径
• 支持 -C / --project-dir 等 idf.py 项目目录参数
• 支持本地组件（components/esp_board_manager）和托管组件（managed_components/espressif__esp_board_manager）
• 在执行 idf.py gen-bmgr-config ... 时自动补齐 main/idf_component.yml 中缺失的 board manager 依赖
• 在执行 idf.py gen-bmgr-config ... 时自动下载缺失的 board manager 组件

安装

注意：必须要安装在 esp-idf 的虚拟环境中

从 PyPI 安装

pip install esp-bmgr-assist

从源码安装

pip install git+https://github.com/TDA-2030/esp-bmgr-py.git

工作原理

1. 自动注入: 通过 .pth 文件在 Python 启动时自动导入 idf_injector 模块，注册导入钩子

2. 延迟执行: 使用导入钩子机制，仅在 idf.py 导入 idf_py_actions 模块时才执行初始化代码（此时 logging 系统已初始化，避免过早执行干扰 CMake 的 Python 检测）

3. 组件查找: _main() 函数执行时，按以下优先级查找 board manager 组件：

   • 优先查找本地组件：检查 components/esp_board_manager 或 components/espressif__esp_board_manager
   • 检查 manifest 文件中的 override_path 配置
   • 检查已下载的托管组件：managed_components/espressif__esp_board_manager

4. 主动自举: 如果执行的是 idf.py gen-bmgr-config ... 且当前工程还没有可用的 board manager 组件：

   • 自动解析真实工程目录（支持 -C / --project-dir）
   • 自动创建或补齐 main/idf_component.yml
   • 自动追加 espressif/esp_board_manager 依赖
   • 自动下载组件到 managed_components/espressif__esp_board_manager

5. 环境变量设置: 将找到的 board manager 组件路径添加到 IDF_EXTRA_ACTIONS_PATH 环境变量

6. 自动发现: idf.py 会自动扫描 IDF_EXTRA_ACTIONS_PATH 目录，发现并加载 board manager 扩展

IDF_EXTRA_ACTIONS_PATH 多路径写法

与 ESP-IDF tools/idf.py 一致：多个目录必须用英文分号 ; 分隔（各平台相同）。不要使用 os.pathsep（例如 Linux/macOS 上常见的 :）：IDF 只会按 ; 拆分，否则整段会被当成一个目录名，扩展无法按预期加载。本包内合并/解析该变量时也仅按 ; 处理，与 IDF 行为对齐。

使用方法

安装后，直接使用 idf.py 命令：

idf.py gen-bmgr-config

调试

设置 ESP_BMGR_DEBUG=1 环境变量可查看调试信息：

export ESP_BMGR_DEBUG=1
idf.py gen-bmgr-config

调试输出来自 esp_bmgr_py（idf_injector），与 board 管理组件内部的日志系统无关。idf_injector loaded 仅在 当前 idf.py 进程 进入扩展自举时打印一次——不会在组件下载等环节启动的每个 Python 子进程里重复打印。