ESP-IDF Store

3 个工具让你问构建服务器它有哪些 ESP-IDF 版本和工具,以及检查一切 是不是健康。

“Store” 住在构建服务器上,不在你电脑上。你永远不需要在本地装 ESP-IDF —— 这些工具只是让你看一眼构建服务器有什么,这样你能挑一 个版本来 pin。

store_versions / idf.versions

返回构建服务器有的 ESP-IDF 版本列表。

输入: 无。

返回:

{
  "store_root": "/var/lib/aegis/espctl-store",
  "versions": [
    {
      "version": "v5.3.1",
      "path": "/var/lib/aegis/espctl-store/idf/v5.3.1",
      "default": true,
      "tools": ["xtensa-esp32s3-elf", "riscv32-esp-elf", "..."]
    },
    {
      "version": "v5.2.2",
      "path": "/var/lib/aegis/espctl-store/idf/v5.2.2",
      "default": false,
      "tools": ["..."]
    }
  ]
}

被标记 default: true 的版本是没有其他 pin 时构建会用的版本。要在 项目级别 pin 不同的版本,用 idf_select_version 或者在 .espctl.toml 里设。

无副作用。 随时可以调。

doctor / doctor.run

某个东西不工作时,最重要的工具。doctor 检查:

1. 构建服务器可达 —— espctl 能不能到你给它的 URL?
2. 你的访问密钥能用 —— 服务器接受它吗?
3. 可用的 IDF 版本 —— 构建服务器有什么?
4. 你的项目设置 —— .espctl.toml 能解析吗?target 合法吗? idf_version 和构建服务器有的某个版本匹配吗?

输入: 无。

返回:

{
  "status": "healthy",
  "checks": [
    { "name": "control_plane", "status": "ok", "detail": "https://esphome.cloud/health 200 OK" },
    { "name": "auth", "status": "ok", "detail": "access key accepted" },
    { "name": "store_manifest", "status": "ok", "detail": "3 IDF versions available" },
    { "name": "default_version", "status": "ok", "detail": "v5.3.1" },
    { "name": "project_config", "status": "ok", "detail": ".espctl.toml valid, target=esp32s3" }
  ],
  "warnings": [],
  "errors": []
}

失败时,具体检查项降级为 warning 或 error:

{
  "status": "unhealthy",
  "checks": [
    { "name": "control_plane", "status": "error", "detail": "ECONNREFUSED https://esphome.cloud" }
  ],
  "errors": [
    {
      "name": "control_plane",
      "message": "Cannot reach the build server. Builds will run in plan-only mode."
    }
  ]
}

排查任何问题先跑 doctor。 它能在一次往返里抓出大多数设置错误。

另见

• idf_select_version —— 选择某次具体构建用的版本。
• 前置条件 —— 你电脑上要装什么 (提示:很少)。
• 故障排查 —— doctor 报错时怎么办。