产品特性​

• 搭载 RISC-V 32 位处理器，主频高达 240MHz
• 集成 384KB SRAM、320KB ROM 和 4MB Flash
• 集成 2.4GHz 与 5GHz 双频 Wi-Fi、Bluetooth 5.0 (LE) 以及 IEEE 802.15.4 （支持 Zigbee 3.0 和 Thread) 无线通信，具备出色的射频性能
• 板载天线切换芯片，可以使用板载天线或者外接天线（IPEX1）
• 采用正反可插拔的 USB Type-C 接口
• 引出丰富的外设接口，邮票孔设计，方便焊接集成到用户自主设计的底板上
• 支持多种低功耗工作状态，可灵活调节通信距离、数据率和功耗之间的平衡，以满足各种应用场景的功耗需求

资源接口​

引脚​

天线切换​

产品尺寸​

本章节包含以下部分，请按需阅读：

• Arduino 入门教程
• 配置开发环境
• 示例程序

Arduino 入门教程​

初次接触 Arduino ESP32 开发，想要快速上手？我们为您准备了一套通用的 入门教程。

• 第0节 认识 ESP32
• 第1节 安装和配置 Arduino IDE
• 第2节 Arduino 基础知识
• 第3节 数字输出/输入
• 第4节 模拟输入
• 第5节 脉冲宽度调制 (PWM)
• 第6节 串行通信 (UART)
• 第7节 I2C 通信
• 第8节 SPI 通信
• 第9节 Wi-Fi 基础用法
• 第10节 网页服务器
• 第11节 蓝牙 (Bluetooth)
• 第12节 LVGL 图形界面开发
• 第13节 综合项目

请注意：该教程使用 ESP32-S3-Zero 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。

配置开发环境​

1. 安装和配置 Arduino IDE​

请参考 安装和配置 Arduino IDE 教程 下载安装 Arduino IDE 并添加 ESP32 支持。

安装步骤： 安装方式请参考：Arduino 库管理教程。

2. 示例程序​

Arduino 示例程序位于 示例程序包 的 Arduino 目录中。

01_GPIO​

代码​

代码解释​

• REG_WRITE() 配合 REG_READ() 对 GPIO 输出寄存器按位取反，可一次性切换多组引脚电平。
• delay(300) 用于控制翻转节奏，让外接 LED 或示波器现象更容易观察。

02_BlinkRGB​

代码​

代码解释​

• set_wheel_color(wheel_pos) 根据当前色轮位置计算 RGB 颜色，并写入板载灯珠。
• wheel_pos++ 持续递增颜色索引，配合 20ms 的刷新间隔形成平滑变色效果。

运行效果​

03_GetchipID​

代码​

代码解释​

• ESP.getEfuseMac() 读取芯片出厂烧录的 MAC 地址，并进一步组合成简化的 chip_id。
• 代码通过串口输出芯片型号、版本和核心数，便于快速确认当前板卡信息。

运行效果​

04_BLE​

代码​

代码解释​

• NimBLEDevice::init() 用于初始化 BLE 协议栈，并设置广播时显示的设备名。
• advertising->start() 启动广播，手机或其他 BLE 设备即可扫描到该开发板。

运行效果​

05_UART​

代码​

代码解释​

• Serial1.available() 用于判断串口接收缓冲区中是否有新数据。
• 读到的数据立即通过 Serial1.write() 回发，实现最基础的串口回环测试。

运行效果​

06_WIFI_AP​

代码​

代码解释​

• WiFi.softAP(ssid, password) 负责启动热点模式，让开发板作为一个 Wi-Fi 接入点工作。
• WiFi.softAPIP() 可读取热点的本机地址，方便后续让手机或电脑连接测试。

运行效果​

07_WIFI_STA​

代码​

代码解释​

• WiFi.begin(ssid, password) 用于连接指定路由器，后面的循环持续检查连接状态。
• 连接成功后通过 WiFi.localIP() 输出分配到的 IP，方便确认联网是否正常。

运行效果​

08_WIFI_StaticIP​

代码​

代码解释​

• 这段代码每隔 5 秒检查一次联网状态，避免在主循环中频繁重连。
• 当 Wi-Fi 断开时会重新调用 WiFi.begin() 发起连接，并在成功后打印当前 IP 信息。

运行效果​

本章节包含以下内容，请按需阅读：

• ESP-IDF 入门教程
• 配置开发环境
• 示例程序

ESP-IDF 入门教程​

初次接触 ESP32 ESP-IDF 开发，想要快速上手？我们为您准备了一套通用的 入门教程。

• 第0节 认识 ESP32
• 第1节 搭建环境
• 第2节 运行实例
• 第3节 创建项目
• 第4节 使用组件
• 第5节 调试程序
• 第6节 FreeRTOS
• 第7节 驱动外设
• 第8节 Wi-Fi 编程
• 第9节 BLE 编程

请注意：该教程使用 ESP32-S3-Zero 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。

配置开发环境​

安装 ESP-IDF 开发环境​

1. 前往 ESP-IDF Installation Manager 下载 ESP-IDF 安装管理器。这是乐鑫最新推出的跨平台安装工具，下文将演示如何使用其离线安装功能。

   在页面中点击 Offline Installer 标签，然后在筛选栏中选择 Windows 操作系统和你需要的 ESP-IDF 版本（图示仅为参考，请以实际为准）。

   
   

   确认选择无误后，点击下载按钮。浏览器将自动同时下载两个文件：一个是 ESP-IDF 离线整合包(.zst)，另一个是 ESP-IDF 安装器(.exe)。

   
   

   请耐心等待两个文件下载完成。

2. 下载完成后，双击运行 ESP-IDF 安装器(eim-gui-windows-x64.exe)。

   启动后，可在右上角将界面语言切换为中文。

   
   

   安装工具会自动检测同一目录下是否存在离线整合包。点击 从存档安装。

   
   

   接下来，选择安装路径。建议使用默认路径；若需自定义，请确保路径中不包含中文或空格。确认无误后，点击 开始安装。

   
   

3. 当看到如下界面时，表示 ESP-IDF 已安装成功。

   
   

4. 建议同时安装驱动程序。点击 完成安装，然后点击 安装驱动程序。

   
   

安装 Visual Studio Code 与 ESP-IDF 扩展​

1. 下载并安装 Visual Studio Code。

2. 安装时建议勾选 通过 Code 打开操作添加到 Windows 资源管理器文件上下文菜单,以便快速打开项目文件夹。

3. 在 VS Code 中,点击侧边活动栏中的  扩展图标(或使用快捷键 Ctrl + Shift + X)打开 扩展 视图。

4. 在搜索框中输入 ESP-IDF,找到 ESP-IDF 扩展并点击安装。

   
   

5. 当 ESP-IDF 扩展版本 ≥ 2.0 时,扩展会自动检测并识别上述步骤中安装的 ESP-IDF 环境,无需手动配置。

示例程序​

ESP-IDF 示例程序位于 示例程序包 的 ESP-IDF 目录中。

01_GPIO​

代码​

代码解释​

• 代码先遍历选中的 GPIO 引脚并统一设置输出电平，再通过 output_level = !output_level 实现同步翻转。
• vTaskDelay(pdMS_TO_TICKS(500)) 用于控制闪烁周期，方便观察 GPIO 输出变化。

02_BlinkRGB​

代码​

代码解释​

• led_strip_set_wheel() 根据 wheel_pos 计算当前颜色，适合做循环彩虹灯效。
• 每次 led_strip_refresh() 后延时 20ms，可让颜色变化看起来更平滑。

运行效果​

03_GetchipID​

代码​

代码解释​

• esp_chip_info() 用于读取芯片核心数、版本等基础硬件信息。
• esp_efuse_mac_get_default() 读取默认 MAC 地址，可作为设备的唯一标识输出。

运行效果​

04_BLE​

代码​

代码解释​

• 代码先初始化 NVS、蓝牙控制器和 Bluedroid 协议栈，这是 BLE 广播运行的基础。
• esp_ble_gap_config_adv_data_raw() 用于配置原始广播数据，随后设备即可被外部扫描到。

运行效果​

05_UART​

代码​

代码解释​

• uart_param_config()、uart_driver_install() 和 uart_set_pin() 分别完成串口参数、驱动和引脚映射配置。
• 最后通过 xTaskCreate() 启动收发任务，让串口接收和发送可以并行运行。

运行效果​

06_WIFI_AP​

代码​

代码解释​

• 这段代码把开发板配置成 AP 模式，核心是 esp_wifi_set_mode(WIFI_MODE_AP) 和 esp_wifi_set_config()。
• 如果密码为空，会自动切换成开放热点模式，便于快速测试连接。

运行效果​

07_WIFI_STA​

代码​

代码解释​

• esp_netif_create_default_wifi_sta() 用于创建 STA 网络接口，供开发板连接路由器使用。
• 注册 Wi-Fi 与 IP 事件回调后，程序就能在联网成功或掉线时执行对应处理逻辑。

运行效果​

08_WIFI_StaticIP​

代码​

代码解释​

• esp_netif_ip_info_t 结构体用于一次性配置静态 IP、网关和子网掩码。
• 这类写法适合设备地址需要固定的场景，便于局域网内通过已知地址访问开发板。

运行效果​

09_ZIGBEE​

• 1：准备两块ESP32-C5-Zero 开发板，确保它们供电正常且处于可烧录程序的状态。
• 2：将第一块开发板与电脑连接，使用烧录工具往该开发板烧录 HA_on_off_light 程序（此程序用于控制 RGB 灯），烧录完成后保持开发板上电状态。
• 3：将第二块开发板与电脑连接，使用烧录工具往该开发板烧录 HA_on_off_switch 程序（此程序用于通过 BOOT 按键实现控制功能），烧录完成后保持开发板上电状态。

代码​

代码解释​

• esp_zb_platform_config() 完成 Zigbee 平台层初始化，准备好射频与主机配置。
• xTaskCreate(esp_zb_task, ...) 将 Zigbee 主任务独立运行，便于后续扩展网络控制逻辑。

运行效果​

10_Mem_Security​

代码​

代码解释​

• 这几行分别用于查看当前安全状态、权限信息，并测试硬件加密与 TEE/APM 相关功能。
• 适合用来快速验证芯片安全特性是否初始化正常。

本章节包含以下部分，请按需阅读：

• MicroPython 入门教程
• 配置开发环境

MicroPython 入门教程​

初次接触 ESP32 MicroPython 开发，想要快速上手？我们为您准备了一套通用的 ESP32 MicroPython 入门教程。

• 第1节 搭建开发环境
• 第2节 基础知识
• 第3节 GPIO 数字输出/输入
• 第4节 ADC 模拟输入
• 第5节 PWM 输出
• 第6节 UART 通信
• 第7节 I2C 通信
• 第8节 SPI 通信
• 第9节 Wi-Fi 基础用法
• 第10节 网页服务器
• 第11节 蓝牙
• 第12节 综合项目

请注意：该教程使用 ESP32-S3-Zero 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。

配置开发环境​

1. 烧录 MicroPython 固件和配置 Thonny​

请参考 搭建 MicroPython 开发环境教程 烧录 MicroPython 固件。

2. 其他提示​

• ESP32-C5-Zero MicroPython 固件下载链接：https://micropython.org/download/ESP32_GENERIC_C5/

• 若通过 乐鑫 Flash 下载工具 为 ESP32-C5-Zero 烧录 MicroPython 固件，烧录地址为 0x0。

01_GPIO​

代码​

代码解释​

• 代码先把 0 到 12 号 GPIO 配置为输出口，再统一拉高、拉低实现循环闪烁。
• time.sleep(0.5) 控制亮灭节奏，便于观察引脚输出效果。

02_BlinkRGB​

代码​

代码解释​

• wheel(pos) 根据位置值返回不同 RGB 组合，用于生成彩虹渐变色。
• np.write() 会把颜色数据真正刷新到灯珠上，循环执行后即可看到流动变色效果。

运行效果​

03_GetchipID​

代码​

代码解释​

• network.WLAN(network.STA_IF) 用于启用无线网卡的 STA 模式。
• 读取到的 mac 再经 ubinascii.hexlify() 转成字符串，方便直接打印唯一 ID。

运行效果​

04_BLE​

代码​

代码解释​

• adv_payload() 按 BLE 广播格式拼接设备名和发射功率等字段。
• ble.gap_advertise() 启动广播后，外部设备就可以扫描到这个 BLE 名称。

运行效果​

05_UART​

代码​

代码解释​

• 代码使用 UART(1, ...) 初始化 UART1，并把 TX/RX 分别映射到指定引脚。
• 主循环中每秒发送一次字符串，可用于最基础的串口连通性测试。

运行效果​

06_WIFI_AP​

代码​

代码解释​

• 这段代码主要用于输出热点启动后的 SSID、密码和 IP 地址，确认 AP 模式是否正常工作。
• ap.ifconfig()[0] 取到的是热点当前的本机 IP。

运行效果​

07_WIFI_STA​

代码​

代码解释​

• sta.connect(SSID, PASSWORD) 发起联网，后面的循环持续等待直到连接成功。
• 这种写法适合示例演示，能直观看到设备正在连接 Wi-Fi。

运行效果​

08_WIFI_StaticIP​

代码​

代码解释​

• 连接成功后调用 sta.ifconfig(...) 手动写入静态 IP 配置，覆盖 DHCP 分配结果。
• 这样设备每次联网后都使用固定地址，便于局域网内调试和访问。

运行效果​

1. 硬件资料​

开发板设计文件

• 引脚图
• 原理图-Gitee
• 原理图-GitHub
• 工程图纸-Gitee
• 工程图纸-GitHub

2. 技术手册​

• ESP32-C5 芯片官方手册

  • 技术规格书：中文版 | 英文版
  • 技术参考手册：中文版 | 英文版

• 数据手册

  • WS2812B RGB LED 数据手册

3. 软件开发资源​

• ESP32-C5-Zero 示例程序-GitHub
• ESP32-C5-Zero 示例程序-Gitee
• 串口和网络调试助手

技术支持

周一-周五（9:30-6:30）周六（9:30-5:30）

手机：13434470212

邮箱：services04@spotpear.cn

QQ：202004841