如何添加新的开发板支持

本文档将详细介绍如何为项目添加新的开发板支持。

一、文件结构

首先需要在 main/boards/ 目录下创建新开发板的目录：

main/boards/your-board-name/
├── config.h          # 开发板配置头文件
├── config.json       # 构建配置
└── your_board.cc    # 开发板实现文件

二、配置文件

2.1 硬件配置 (config.h)

// 音频配置
#define AUDIO_INPUT_SAMPLE_RATE  16000
#define AUDIO_OUTPUT_SAMPLE_RATE 24000

// GPIO定义
#define BUILTIN_LED_GPIO        GPIO_NUM_X  // 内置LED引脚
#define BOOT_BUTTON_GPIO        GPIO_NUM_X  // BOOT按键引脚
#define TOUCH_BUTTON_GPIO       GPIO_NUM_X  // 触摸按键引脚
#define VOLUME_UP_BUTTON_GPIO   GPIO_NUM_X  // 音量+按键引脚
#define VOLUME_DOWN_BUTTON_GPIO GPIO_NUM_X  // 音量-按键引脚

// I2C配置
#define I2C_MASTER_NUM     I2C_NUM_1
#define I2C_MASTER_SDA_IO  GPIO_NUM_X
#define I2C_MASTER_SCL_IO  GPIO_NUM_X
#define I2C_MASTER_FREQ_HZ 400000

// 显示配置
#define DISPLAY_SDA_PIN GPIO_NUM_X
#define DISPLAY_SCL_PIN GPIO_NUM_X
#define DISPLAY_WIDTH   128
#define DISPLAY_HEIGHT  64  // 32或64

2.2 构建配置 (config.json)

{
  "target": "esp32s3", // 目标芯片
  "builds": [
    {
      "name": "your-board-name",
      "sdkconfig_append": [
        "CONFIG_BOARD_YOUR_BOARD_NAME=y",
        "CONFIG_OLED_SSD1306_128X64=y", // 显示器类型
        "CONFIG_AUDIO_ES8311=y" // 音频编解码器类型
      ]
    }
  ]
}

三、开发板实现

3.1 基本框架 (your_board.cc)

#include "board.h"
#include "config.h"

class YourBoard : public WifiBoard {  // 或其他合适的基类
public:
    YourBoard() {
        InitializeDisplay();
        InitializeButtons();
        InitializeIot();
    }

    // 必须实现的虚函数
    virtual Led* GetLed() override;
    virtual AudioCodec* GetAudioCodec() override;
    virtual Display* GetDisplay() override;
    virtual Button* GetBootButton() override;
    virtual Button* GetTouchButton() override;

private:
    void InitializeDisplay();
    void InitializeButtons();
    void InitializeIot();

    // 成员变量
    std::unique_ptr<Display> display_;
    std::unique_ptr<AudioCodec> audio_codec_;
    std::unique_ptr<Button> boot_button_;
    std::unique_ptr<Button> touch_button_;
};

3.2 必要功能实现

// LED控制实现
Led* YourBoard::GetLed() {
    static SingleLed led(BUILTIN_LED_GPIO);
    return &led;
}

// 音频编解码器实现
AudioCodec* YourBoard::GetAudioCodec() {
    if (!audio_codec_) {
        audio_codec_ = std::make_unique<ES8311AudioCodec>(
            I2C_MASTER_NUM,
            I2C_MASTER_SDA_IO,
            I2C_MASTER_SCL_IO,
            I2C_MASTER_FREQ_HZ
        );
    }
    return audio_codec_.get();
}

// 显示器实现
Display* YourBoard::GetDisplay() {
    if (!display_) {
        display_ = std::make_unique<SSD1306Display>(
            DISPLAY_WIDTH,
            DISPLAY_HEIGHT,
            DISPLAY_SDA_PIN,
            DISPLAY_SCL_PIN
        );
    }
    return display_.get();
}

// 按键实现
Button* YourBoard::GetBootButton() {
    if (!boot_button_) {
        boot_button_ = std::make_unique<GpioButton>(BOOT_BUTTON_GPIO);
    }
    return boot_button_.get();
}

Button* YourBoard::GetTouchButton() {
    if (!touch_button_) {
        touch_button_ = std::make_unique<TouchButton>(TOUCH_BUTTON_GPIO);
    }
    return touch_button_.get();
}

3.3 初始化函数实现

void YourBoard::InitializeDisplay() {
    auto display = GetDisplay();
    display->Initialize();
}

void YourBoard::InitializeButtons() {
    auto boot_button = GetBootButton();
    boot_button->OnClick([this]() {
        Application::GetInstance().ToggleChatState();
    });

    auto touch_button = GetTouchButton();
    touch_button->OnPressDown([this]() {
        Application::GetInstance().StartListening();
    });
    touch_button->OnPressUp([this]() {
        Application::GetInstance().StopListening();
    });
}

void YourBoard::InitializeIot() {
    auto& thing_manager = iot::ThingManager::GetInstance();
    thing_manager.AddThing(iot::CreateThing("Speaker"));
    thing_manager.AddThing(iot::CreateThing("Lamp"));
}

// 声明开发板
DECLARE_BOARD(YourBoard);

四、CMake 配置

在项目的 CMakeLists.txt 中添加新开发板：

if(CONFIG_BOARD_YOUR_BOARD_NAME)
    list(APPEND srcs
        "boards/your-board-name/your_board.cc"
    )
endif()

五、验证步骤

1. 编译验证

# 配置项目，选择新开发板
idf.py menuconfig  （记得选择新开发板）

# 编译
idf.py build

2. 功能验证清单

• LED 控制正常
• 显示器初始化成功
• 按键响应正确
• 音频录放正常
• IoT 功能正常

六、常见问题

1. 编译错误

• 检查 config.h 中的 GPIO 定义是否正确
• 确认 CMakeLists.txt 配置正确
• 验证类的虚函数是否全部实现

2. 硬件初始化失败

• 检查 I2C 配置是否正确
• 确认 GPIO 引脚定义无冲突
• 验证显示器和音频编解码器型号配置

3. 按键响应异常

• 检查按键 GPIO 配置
• 确认中断处理正确
• 验证回调函数绑定

七、参考示例

可以参考以下已实现的开发板：

• LiChuangBoard (立创实战派)
• BoxBoard (ESP32-S3-BOX3)
• CoreS3Board (M5Stack CoreS3)

这些实现都在 main/boards/ 目录下可以找到。