第 0 章：ESP-IDF 工具链与 OSRCORE 硬件

0.1 知识要点

• ESP-IDF 的安装方式（官方脚本 / VS Code 插件）
• 项目目录结构与 CMakeLists.txt 的作用
• idf.py 常用命令：build、flash、monitor、menuconfig
• OSRCORE 开发板各外设的 GPIO 分配总览
• USB CDC 作为调试控制台的配置方法

0.2 课程内容

本章介绍如何在 Linux/macOS/Windows 上搭建 ESP-IDF 开发环境，并对 OSRCORE 开发板的硬件资源进行全面介绍。完成本章后，你将能够编译、烧录并监视一个最小示例程序，为后续各章的实验打下基础。

OSRCORE 是一块面向移动机器人的紧凑型控制板，搭载 ESP32-S3 双核 240 MHz 处理器，板载 WS2812B 彩灯、无源蜂鸣器、QMI8658 六轴 IMU、正交编码器接口、SBUS 遥控接收、ESC/舵机 PWM 输出以及 USB CDC 控制台，覆盖了小型轮式机器人所需的全部基础外设。

0.3 基础学习

ESP-IDF 安装

推荐使用官方一键安装脚本：

# Linux / macOS
git clone --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf
cd ~/esp/esp-idf
./install.sh esp32s3
. ./export.sh          # 每次新终端都需要执行

Windows 用户可下载 ESP-IDF Windows Installer，安装后在 ESP-IDF CMD 终端中操作。

项目结构

my_project/
├── CMakeLists.txt          # 顶层：cmake_minimum_required + project()
├── sdkconfig.defaults      # 预设 menuconfig 选项
└── main/
    ├── CMakeLists.txt      # idf_component_register(SRCS "main.c")
    └── main.c

顶层 CMakeLists.txt 最简形式：

cmake_minimum_required(VERSION 3.16)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my_project)

idf.py 常用命令

命令	说明
idf.py set-target esp32s3	设置目标芯片（首次必须执行）
idf.py menuconfig	图形化配置（波特率、分区表等）
idf.py build	编译项目
idf.py flash	烧录到开发板（默认 /dev/ttyUSB0）
idf.py monitor	打开串口监视器（115200 baud）
idf.py flash monitor	烧录后立即监视
idf.py fullclean	清除全部编译产物

指定端口：idf.py -p /dev/ttyACM0 flash monitor

OSRCORE 硬件资源总览

外设	GPIO	驱动/协议	备注
WS2812B LED	GPIO45	RMT TX	GRB 字节序
无源蜂鸣器	GPIO42	LEDC TIMER1 CH2	10-bit，50% 占空比
ESC 油门	GPIO1	LEDC TIMER0 CH0	50 Hz，14-bit
舵机转向	GPIO2	LEDC TIMER0 CH1	50 Hz，14-bit
编码器 EA	GPIO3	PCNT edge	512 PPR
编码器 EB	GPIO9	PCNT level	减速比 10.55
I2C SDA	GPIO10	I2C_NUM_0	400 kHz
I2C SCL	GPIO11	I2C_NUM_0
QMI8658 IMU	I2C 0x6B	I2C	±8g / ±2048 dps
SBUS RX	GPIO44	UART0	100k 8E2 反相
电池 ADC	GPIO4	ADC1 CH3	分压检测
电池使能	GPIO16	GPIO OUTPUT	高电平使能
USB CDC	内置	USB Serial JTAG	控制台

USB CDC 控制台配置

在 sdkconfig.defaults 中加入：

CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y
CONFIG_ESP_CONSOLE_SECONDARY_NONE=y

或在代码中手动初始化：

usb_serial_jtag_driver_config_t cfg = {
    .rx_buffer_size = 256, .tx_buffer_size = 256
};
usb_serial_jtag_driver_install(&cfg);
esp_vfs_usb_serial_jtag_use_driver();

0.4 程序学习

ESP-IDF 应用程序的入口是 app_main()，运行在 FreeRTOS 任务中（默认栈 4 KB，优先级 1）。最小程序框架：

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"

static const char *TAG = "main";

void app_main(void)
{
    ESP_LOGI(TAG, "Hello OSRCORE!");
    while (1) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

ESP_LOGI 宏输出带时间戳和标签的日志，级别从低到高：LOGV < LOGD < LOGI < LOGW < LOGE。

0.5 课程总结

本章完成了 ESP-IDF 工具链的安装，掌握了 idf.py 的核心工作流，并对 OSRCORE 开发板的全部外设资源有了整体认识。从第 1 章起，每章聚焦一个外设，逐步构建完整的机器人控制系统。

---