ESP-BSP Generator：从乐鑫开发板到自定义板卡的快速迁移

乐鑫科技 Espressif

416人浏览 · 2026-07-22 14:45:35

乐鑫科技 Espressif · 2026-07-22 14:45:35 发布

只需从 esp-bsp 的开发套件出发，在网页表单中自定义引脚与功能，就能下载生成一个面向自定义 PCB 的、达到量产标准的 BSP 组件——用相同的 API，实现更少的手动工作量。

简介

在没有板级支持包 (BSP) 的情况下启动一个项目时，第一阶段的大部分工作都会集中在板卡初始化上。在应用程序能够真正运行之前，开发者需要选定目标芯片、配置外设、分配 GPIO，并初始化显示屏、触摸控制器、按键、音频、传感器、存储以及板卡上的其他硬件功能。

这一过程既耗费时间，又要求对原理图有深入了解，且容易出错：一个引脚配置错误、一个缺失的依赖，或是外设配置上的细微差异，都可能导致启动流程失败。如果同一套硬件在多个产品中反复使用，或者某个原型日后演变为定制的 PCB，同样的板级工作往往需要重复进行并持续维护。

BSP 的作用

BSP 将这部分硬件相关的知识打包成一个可复用的组件，其中包含驱动程序、外设的初始化与反初始化、板卡配置、目标设置，以及使用板卡各项功能所需的 API。有了这一层，各个项目就无需在每个应用中重复相同的设置，而是统一调用这一公共的板卡层。

乐鑫此前在《在开发套件中使用 ESP-BSP》一文中介绍过这一理念——通过乐鑫维护的 BSP，官方支持的开发套件从第一次构建开始就能更便捷地使用。

这一方法同样适用于自定义硬件。为自有板卡创建 BSP，可以让团队集中在一处描述原理图、复用初始化代码、保持应用代码更加简洁，并在原型与量产硬件之间更轻松地切换。随着硬件迭代，这也使得板卡定义更易于版本管理和团队共享。

不过，手动创建 BSP 依然需要投入不小的工作量。

每一块自定义板卡都会遇到的问题

设想一种常见场景：软件团队基于 ESP32-S3-BOX-3、ESP32-C3-LCDKit、M5Stack Tab5，或 esp-bsp 中的其他板卡完成了原型开发。显示屏、触摸、音频和 SD 卡等功能都可以直接正常工作，因为这些 BSP 由乐鑫维护。

随后，硬件团队设计出一块自定义板卡，采用了不同的触摸控制器、不同的引脚映射，并且去掉了扬声器。这时，部分板级支持工作就不得不从零开始。

对此其实存在更好的工作流程。

引入 BSP Generator

ESP-BSP Generator 是一款网页工具，可用于创建 ESP-IDF BSP 组件，无需从空白文件夹开始。开发者不必手动复制现有板卡、逐一编辑源文件、更新 Kconfig 并逐项核对依赖关系，只需通过一份引导式表单来描述自己的硬件。

开发者可以从已验证可用的 esp-bsp 板卡出发，调整引脚与启用的功能以匹配自身原理图，进而为自有硬件生成一个达到量产标准的 BSP 组件。生成的软件包遵循与乐鑫官方 BSP 相同的规范，包括组件目录结构、板卡 API 以及配置文件。

最终得到的板卡层，在应用侧使用体验保持一致，同时又针对自身 PCB 完成了定制。

从直接可用的方案开始

该生成器的设计理念就是复用：开发者无需从一份空白表单开始描述整块板卡。可以先选择与自己原型最接近的官方支持板卡，加载其已有的 BSP 配置，再据此适配到自己的原理图。未发生变化的部分保持不变，定制工作只需聚焦在与自身 PCB 不同的功能、驱动和引脚分配上。
在这里插入图片描述

（图：加载配置界面——选择一款起始板卡，如 ESP-BOX-3、ESP32-C3-LCDKit 等）

具体步骤如下：

打开 ESP-BSP Generator。
点击“加载配置 (Load configuration)”，选择一款与原型最接近的起始板卡（例如 ESP-BOX-3、ESP32-S3-EYE、ESP32-C3-LCDKit）。
表单会自动填充 MCU、功能、驱动及引脚分配——其结构与 esp-bsp/bsp/ 中的官方 BSP 保持一致。

将鼠标悬停或点按“?”图标即可查看提示信息。请务必保存这份 JSON 文件——它是板卡定义的唯一真实来源 (single source of truth)。

在这里插入图片描述

（图：已加载起始板卡——ESP-BOX-3 配置已就绪，可供进一步定制）

在动手修改引脚和驱动之前，建议先完成以下几项个性化设置：

更新 BSP 名称 (BSP Name)：该名称将成为组件文件夹名称，也是生成文件中板卡的标识名。
更新详细描述 (Long Description)：所加载配置中原有的描述文字会被复制到生成的 README.md 中；如果启用了 SquareLine Studio 功能包，该描述也会被写入板卡的 .slb 元数据文件。
上传板卡照片，用于 README 展示；如果启用了 SquareLine Studio 功能包，该照片也会用于 SquareLine 预览图。
添加硬件链接 (HW link)：指向包含原理图及更多引脚说明的板卡介绍页面。
更新 BSP URL：该地址会被写入 idf_component.yml，作为软件包的规范引用地址；如果计划将组件发布到 ESP 组件注册表 (ESP Component Registry)，请务必更新此项。

为 PCB 配置功能

每一项硬件能力都对应一个功能标签页：显示屏、触摸、按键、音频、SD 卡、摄像头、传感器、USB、电池等。开发者只需启用原理图中实际具备的功能，关闭已经去掉的部分即可。

自定义板卡上常见的调整示例：

开发板上	自定义板卡上
3 个导航按键	2 个按键，且 GPIO 不同
I2C 上的 FT5x06 触摸屏	同一款控制器，但 I2C 引脚不同
RGB LCD + 背光 PWM	SPI 显示屏，固定背光
板载麦克风	无音频功能——对应标签页保持关闭

在生成任何内容之前，该工具会先检查各功能之间的依赖关系（例如：I2C 触摸功能需要先启用 I2C）。

在这里插入图片描述

（图：显示屏功能标签页——分辨率、驱动、引脚及 LVGL 选项）

一次生成，即可像使用其他 esp-bsp 组件一样集成

点击“生成 BSP (Generate BSP)”后，将得到一个包含以下内容的 ZIP 压缩包：

完整的 ESP-IDF 组件（CMakeLists.txt、Kconfig、头文件、源文件）
根据所选配置生成的 sdkconfig.defaults
包含功能说明与依赖关系表的 README.md
API.md 接口文档（Doxygen 风格，与官方 BSP 思路一致）
（可选）noglib 版本（不含 LVGL 的 BSP）
（可选）面向 UI 设计师的 SquareLine Studio OBP 功能包

应用程序仍然调用相同的 BSP 入口函数：

#include "bsp/esp-bsp.h"

void app_main(void)
{
    bsp_display_start();
    bsp_display_backlight_on();
    // ... your UI / logic unchanged in spirit
}

在 main/idf_component.yml 中接入新组件：

dependencies:
  my_custom_board:
    path: ../components/my_custom_board

将 sdkconfig.defaults 复制到项目根目录，设置目标芯片，即可开始构建。整个应用结构基本保持不变——发生变化的只有板卡层。

更换组件，保留软件

这正是该工具对产品团队最有价值的地方：

原型固件使用来自 esp-bsp的 esp-box-3 BSP
量产固件使用由生成器生成的 my_custom_board BSP
应用代码所使用的 #include 与 BSP API 在很大程度上保持一致

开发者不需要长期维护一个 esp-bsp 的分支 (fork)，而只需维护一个体量较小、由工具生成的板卡软件包，它遵循与 espressif/esp-bsp 相同的规范：组件目录结构、bsp_* 系列辅助函数、通过 esp_lvgl_port 实现的 LVGL 集成，以及可以在 esp-bsp/examples/ 下参考对比的示例。

板卡定义存储在 JSON 文件中

每一次成功运行都会在 BSP 文件夹内生成一个 JSON 配置文件（例如 my_board/my_board.json）。这份文件才是硬件定义的唯一真实来源——而非生成出来的 .c 文件。

该 JSON 文件是表单中所有配置项的结构化快照，包括：

板卡元信息——名称、MCU、仓库地址、硬件链接、描述、照片引用，以及生成器选项（noglib、SquareLine 等）
BSP_FEATURES——已启用的功能及其具体连接方式：GPIO 引脚、总线接口（I2C、SPI、RGB 等）、显示屏与触摸驱动、音频编解码器、SD 卡总线宽度、传感器类型，以及其他各项功能相关的具体设置

换言之：开发者在界面中做出的各项原理图相关决策，都被保存在这样一份可移植的文件中。而 C 语言源文件、Kconfig、sdkconfig.defaults、README.md 以及 SquareLine 功能包，都是基于这份 JSON 文件与当前生成器模板派生出来的产物。

在实际使用中，建议这样处理该 JSON 文件：

将其与固件代码一同纳入 git 版本管理——值得保留的是这份板卡定义 JSON 文件，而非手动编辑或对生成出来的 .c 文件做版本管理；当需要更新时，应基于这份 JSON 文件重新生成 BSP。
随时可重新加载：可在生成器首页通过“加载配置 (Load configuration)”重新载入，或在 BSP 生成完成后的成功页面上点击“返回并修改 (Back & change)”。
与同事共享，或跨项目复用，让团队所有成员都从同一份板卡描述出发。
在不同 PCB 版本之间做差异比对 (diff)，以准确了解发生了哪些变化（例如新增的传感器标签页、不同的 I2C 引脚、显示驱动的更换等）。

开发者是在 JSON 层面（通过表单）编辑板卡定义，而不是手动维护 BSP 本身。

ESP-IDF 升级后：重新生成，而非重写

这份 JSON 文件保存的是板卡本身的信息；而生成器模板则保存着“在当前 ESP-IDF 及组件生态下，BSP 应当如何构建”的知识。当外部环境发生变化——例如发布了新的 ESP-IDF 主版本、esp-bsp 的模式发生更新、组件注册表中出现新驱动，或是需要新增某项功能——开发者不需要在成百上千行 bsp_*.c 代码中手动进行合并。

只需加载此前保存的 JSON 文件，只调整实际发生变化的部分，再次点击“生成 BSP”即可。该工具会基于当前模板重新渲染整个组件：源文件、Kconfig、sdkconfig.defaults、API.md、README.md，以及可选的 SquareLine 功能包。原有的引脚映射与功能选择会被完整保留，而生成的代码则会自动应用模板的最新修复和接口更新。

通常需要重新生成的场景包括：

ESP-IDF 版本升级或新增目标芯片支持
生成器中 esp-bsp / 驱动模板发生更新
PCB 版本迭代——加载 JSON 文件，调整引脚或功能后重新生成
需要新增可选输出内容——例如在后续版本中启用 SquareLine Studio 功能包

开发者只需从模板刷新具体实现，而设计意图始终保留在这份 JSON 文件中。

在这里插入图片描述

（图：生成成功页面——展示后续步骤、文件列表及“下载 ZIP (Download ZIP）”按钮）

成功页面会引导完成集成的各个步骤；应用内的帮助窗口 (Help modal) 则涵盖加载 / 保存配置、各项功能，以及 SquareLine OBP 的安装路径等内容。

支持 SquareLine Studio

SquareLine Studio 是一款面向 LVGL 的可视化 UI 编辑工具——开发者可以在桌面应用中设计界面、控件和动画效果，并将其导出为 C 代码，集成到 ESP-IDF 项目中。如果工作流程中包含 UI 设计环节，可以启用“生成 SquareLine Studio 功能包 (Generate SquareLine Studio pack)”选项（该选项需要先启用显示屏功能）。生成的 ZIP 压缩包中会包含一个 Open Board Platform 软件包 (.slb、.zip、.png)，可直接复制到 ~/SquareLine/boards/ 目录中—— UI 设计师可以继续在 SquareLine 中工作，而固件所使用的引脚和分辨率，与表单中定义的完全一致。