esp-bmgr-assist 0.6.0

ESP Board Manager Python package for idf.py extensions

esp-bmgr-assist

PyPI package: esp-bmgr-assist
Python package: esp_bmgr_py

esp-bmgr-assist injects into the idf.py startup flow through a .pth hook, then discovers and loads the ESP Board Manager extension automatically.

PyPI 包名：esp-bmgr-assist
Python 包目录：esp_bmgr_py

esp-bmgr-assist 通过 .pth 注入 idf.py 启动流程，帮助工程自动发现并加载 ESP Board Manager 扩展。

Features / 功能

• Automatically appends the detected board manager path to IDF_EXTRA_ACTIONS_PATH.

• Supports local and managed component discovery:

  • components/esp_board_manager
  • components/espressif__esp_board_manager
  • managed_components/espressif__esp_board_manager

• Supports first-use bootstrap on idf.py bmgr ... and the legacy idf.py gen-bmgr-config ....

• Resolves the real project directory correctly for -C / --project-dir.

• Can locate board manager through direct dependencies or transitive dependencies resolved by the project dependency graph.

• 自动把可用的 board manager 路径加入 IDF_EXTRA_ACTIONS_PATH。

• 支持本地组件和托管组件发现：

  • components/esp_board_manager
  • components/espressif__esp_board_manager
  • managed_components/espressif__esp_board_manager

• 支持在 idf.py bmgr ... 和兼容旧命令 idf.py gen-bmgr-config ... 首次使用时自动自举。

• 支持正确处理 -C / --project-dir 等项目目录参数。

• 支持通过直接依赖或项目依赖图解析出的传递依赖定位 board manager。

Installation / 安装

Install this package into the Python environment used by ESP-IDF.

请安装在 ESP-IDF 对应的 Python 虚拟环境中。

Install from PyPI:

pip install esp-bmgr-assist

Install from source:

pip install /path/to/esp-bmgr-py

Upgrade an existing installation from PyPI:

pip install --upgrade esp-bmgr-assist

Upgrade from a local checkout after new changes:

pip install --upgrade /path/to/esp-bmgr-py

Usage / 使用方法

Recommended command:

idf.py bmgr

Legacy command kept for compatibility:

idf.py gen-bmgr-config

Debug mode:

export ESP_BMGR_DEBUG=1
idf.py bmgr

Assist preflight warnings are enabled by default for build-like commands:

idf.py build

Disable them when needed:

export ESP_BMGR_ASSIST_PREFLIGHT=0
idf.py build

Assist can warn about:

• missing components/gen_bmgr_codes/* generated artifacts
• CONFIG_IDF_TARGET mismatch between sdkconfig and board_manager.defaults

The assist-side preflight currently focuses on build-like commands and intentionally skips interactive/config-only commands such as set-target, menuconfig, confserver, and config-report.

推荐命令：

idf.py bmgr

兼容旧命令：

idf.py gen-bmgr-config

调试模式：

export ESP_BMGR_DEBUG=1
idf.py bmgr

assist 侧预检查默认会在 build 一类命令上启用：

idf.py build

如需关闭，可设置：

export ESP_BMGR_ASSIST_PREFLIGHT=0
idf.py build

开启时，assist 会额外提示：

• components/gen_bmgr_codes/* 生成物缺失
• sdkconfig 与 board_manager.defaults 的 CONFIG_IDF_TARGET 不匹配

当前 assist 预检查只针对 build 一类命令，不会对 set-target、menuconfig、 confserver、config-report 这类交互/配置命令输出这些 warning。

Compatibility And Known Issues / 兼容与已知问题

Older package behavior / 旧版本行为

Starting from 0.3.1, this package no longer declares core dependencies managed by ESP-IDF itself, such as idf-component-manager. This avoids accidentally upgrading key packages inside the IDF environment during pip install.

从 0.3.1 起，本包不再声明 idf-component-manager 等由 ESP-IDF 自身管理的核心依赖，避免在 pip install 时误升级 IDF 环境中的关键包。

If you installed 0.3.0 before and later saw check-python-dependencies failures, repair the current IDF environment first, then reinstall a newer esp-bmgr-assist.

如果之前安装过 0.3.0，之后出现 check-python-dependencies 失败，请先修复当前 IDF 环境，再重新安装更新版本的 esp-bmgr-assist。

InvalidVersion / 4.0.0-unsupported

This is usually caused by broken third-party package metadata already present in the current Python environment, often in mixed or Conda-based environments. It is not caused by esp-bmgr-assist itself.

这通常是当前 Python 环境里已有第三方包的元数据不符合 PEP 440，常见于混用或 Anaconda 环境，不是 esp-bmgr-assist 自身逻辑导致的。

Recommended actions:

1. Use the official ESP-IDF Python environment.
2. Reinstall or remove the package named in the error log.
3. Create a clean virtual environment if needed.

建议按下面顺序处理：

1. 优先使用 ESP-IDF 官方 Python 虚拟环境。
2. 重装或卸载报错中点名的包。
3. 必要时新建干净的虚拟环境后再安装。

IDF_EXTRA_ACTIONS_PATH separator / 多路径分隔符

Use ; as the separator for multiple IDF_EXTRA_ACTIONS_PATH entries, matching ESP-IDF behavior on all platforms. Do not use :.

多个 IDF_EXTRA_ACTIONS_PATH 路径请使用分号 ; 分隔，与 ESP-IDF 在各平台上的行为保持一致。不要使用 :。