产品参数​

接口说明​

产品尺寸​

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

• ESP-IDF 入门教程
• 配置 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 开发环境​

安装 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 环境,无需手动配置。

示例程序​

Transparent_Test​

程序说明​

• 本示例使用 ESP32-C5-Pico-M，通过四线 SPI 接口驱动分辨率为 128 × 64 的 SSD1312 OLED。工程当前目标芯片为 esp32c5，sdkconfig 由 ESP-IDF 6.0.2 生成。
• 驱动使用 SPI2，工作在 SPI 模式 0，时钟频率为 4 MHz。屏幕只接收数据，无需连接 MISO。
• SSD1312 驱动提供清屏、刷新、点、线、矩形、圆、英文字符、中文点阵字符和 BMP 点阵图等显示接口。显存采用 128 列 × 8 页的组织方式，每页对应 8 行像素。
• 默认运行 oled_demo_run()，依次演示英文字符串、中文点阵字符、BMP 点阵图、线条场景和仪表盘点阵图。工程还提供旋转线框立方体示例，可在 main/main.c 中切换。

硬件连接​

模块的 EN 引脚默认开启，本示例未使用该引脚。完成接线后，将 ESP32-C5-Pico-M 通过 USB 数据线连接到电脑。

本示例按模块默认的四线 SPI 接口编写。如果已将模块焊点切换为 I2C 接口，需要先恢复为四线 SPI，或修改 main/BSP/OLED/ssd1312.h 中的接口配置和引脚定义后重新构建。

代码分析​

• app_main()：调用 oled_init() 初始化屏幕。初始化成功后运行当前选择的演示程序；初始化失败时输出错误码并停止执行。
• oled_init()：配置 GPIO 和 SPI2 总线，复位 OLED，发送 SSD1312 初始化命令，清除显示 RAM 后开启显示。
• oled_refresh()：将 128 × 64 帧缓冲区按 8 个页写入 OLED。SPI 模式下每页使用一次 128 字节数据传输。
• oled_demo_run()：循环显示英文 Waveshare、中文“微雪”、BMP 点阵图、夜景线稿和仪表盘点阵图。
• cube_ui_run()：对立方体的 8 个顶点进行旋转和透视投影，再使用 12 条边绘制连续旋转的线框立方体。

oled_demo_run() 和 cube_ui_run() 内部均为持续运行的循环，因此每次只能选择其中一个。在 main/main.c 中保留需要运行的函数，并注释另一个函数：

// cube_ui_run();
oled_demo_run();

如需运行旋转立方体示例，修改为：

cube_ui_run();
// oled_demo_run();

编译和运行​

在已初始化 ESP-IDF 6.0.2 环境的终端中进入示例工程目录，执行以下命令：

idf.py build
idf.py -p COMx flash monitor

将 COMx 替换为 ESP32-C5-Pico-M 的实际串口号。烧录完成后，串口监视器显示以下初始化成功信息：

SSD1312 initialization successful!

退出串口监视器请按 Ctrl-]。

运行效果​

默认程序启动后，OLED 按以下顺序循环显示：

切换为 cube_ui_run() 后，OLED 持续显示绕竖直方向旋转的线框立方体，程序每 20 ms 绘制并刷新一帧。

示例程序​

Transparent_Test​

程序说明​

• 本示例使用 STM32F103ZET6，通过四线 SPI 接口驱动分辨率为 128 × 64 的 SSD1312 OLED。工程基于 STM32Cube HAL，并提供 Keil MDK 工程文件。
• 系统时钟由 8 MHz 外部晶振倍频至 72 MHz。OLED 默认使用 SPI1，工作在 SPI 模式 0，时钟频率为 2.25 MHz，只向屏幕发送数据，无需连接 MISO。
• SSD1312 驱动提供清屏、刷新、点、线、矩形、圆、英文字符、中文点阵字符和 BMP 点阵图等显示接口。显存大小为 1024 字节，按 128 列 × 8 页组织，每页对应 8 行像素。
• 默认运行 OLED_DemoRun()，依次演示英文字符串、中文点阵字符、BMP 点阵图、线条场景和仪表盘点阵图。工程还提供旋转线框立方体示例，可在 Core/Src/main.c 中切换。
• 工程同时预留了 I2C1 驱动，速率为 400 kHz，默认 7 位地址为 0x3C。模块需要通过焊点切换至 I2C 模式后才能使用该接口。

硬件连接​

默认四线 SPI 接线如下：

模块的 EN 引脚默认开启，本示例未使用该引脚。OLED 只接收 SPI 数据，因此无需连接 MISO。完成接线后，使用 ST-Link 连接开发板的 SWD 接口，其中 SWDIO 对应 PA13，SWCLK 对应 PA14，同时连接 3.3 V 和 GND。

如需使用 I2C，请先将 OLED 模块的硬件接口焊点切换至 I2C，再按下表接线：

同时修改 App/Inc/oled_config.h，确保只启用一个通信接口：

#define OLED_USE_SPI 0
#define OLED_USE_I2C 1

I2C 的 SCL 和 SDA 需要上拉电阻；如果模块未集成上拉电阻，需要外接合适的上拉电阻。

代码分析​

• main()：初始化 HAL、72 MHz 系统时钟、GPIO、SPI1 和 I2C1，随后调用 OLED_Init() 初始化屏幕。初始化失败时进入 Error_Handler()，成功后运行当前选择的演示程序。
• OLED_Init()：通过 PA2 对 OLED 进行硬件复位，发送 SSD1312 初始化命令，清除显示 RAM 后开启显示。
• OLED_Show()：将 128 × 64 帧缓冲区分成 8 页写入 OLED，每页传输 128 字节显示数据。
• OLED_Pixel()、OLED_Line()、OLED_Rect() 和 OLED_Circle()：在帧缓冲区中绘制基本图形；绘制完成后调用 OLED_Show() 才会更新到屏幕。
• OLED_ShowString()、OLED_DrawChinese() 和 OLED_DrawBitmap()：分别用于显示英文字符串、中文点阵字符和 BMP 点阵图。
• OLED_DemoRun()：循环显示英文 Waveshare、中文“微雪”、BMP 点阵图、夜景线稿和仪表盘点阵图。
• Cube_DemoRun()：对立方体的 8 个顶点进行旋转和透视投影，再使用 12 条边绘制连续旋转的线框立方体。

OLED_DemoRun() 和 Cube_DemoRun() 内部均为持续运行的循环，因此每次只能选择其中一个。在 Core/Src/main.c 中保留需要运行的函数，并注释另一个函数：

OLED_DemoRun();
/* Cube_DemoRun(); */

如需运行旋转立方体示例，修改为：

/* OLED_DemoRun(); */
Cube_DemoRun();

编译和运行​

1. 安装 Keil MDK 5，并在 Pack Installer 中安装 Keil::STM32F1xx_DFP 2.3.0 或更新版本。工程当前配置使用 Arm Compiler 5。
2. 打开 MDK-ARM/Transparent_STM32F103ZE.uvprojx。
3. 单击 Build 或按 F7 编译工程。编译成功后会在 MDK-ARM/Objects 目录生成 Transparent_STM32F103ZE.hex。
4. 在 Options for Target → Debug 中选择 ST-Link Debugger，然后单击 Download 将程序烧录到开发板。
5. 烧录完成后复位或重新上电，OLED 即开始运行演示程序。

工程默认按 8 MHz 外部晶振配置。如果开发板使用其他频率的晶振，需要相应修改 Core/Src/main.c 中的 SystemClock_Config()。

运行效果​

默认程序启动后，OLED 按以下顺序循环显示：

切换为 Cube_DemoRun() 后，OLED 持续显示绕竖直方向旋转的线框立方体，程序每 20 ms 绘制并刷新一帧。

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

• MicroPython 入门教程
• Pico 快速上手
• 示例程序

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 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。

Pico 快速上手​

获取 MicroPython 固件​

获取 RP2350 PLUS 板载 MicroPython 固件。

安装 Thonny IDE​

• 请参考 搭建 MicroPython 开发环境教程 安装 Thonny IDE

安装完成之后，第一次要配置语言和主板环境，由于我们是为了使用 Pico/Pico2，所以注意主板环境选择 Raspberry Pi 选项

示例程序​

Transparent_Test​

程序说明​

• 本示例使用 RP2350 PLUS 和 MicroPython，驱动分辨率为 128 × 64 的 SSD1312 OLED。工程默认使用四线 SPI，也支持将 OLED 模块切换为 I2C 接口。
• SPI 默认使用 SPI1，工作在 SPI 模式 0，时钟频率为 4 MHz。OLED 只接收数据，无需连接 MISO。
• I2C 默认使用 I2C0，时钟频率为 400 kHz，7 位地址为 0x3C。模块的硬件接口选择必须与 config.py 中的 BUS 配置一致。
• 驱动类继承 MicroPython 的 framebuf.FrameBuffer，使用 1024 字节显存保存 128 × 64 单色画面，并提供清屏、刷新、点、线、矩形、文本、对比度、反色和显示开关等接口。
• 默认运行 OLED 综合演示，依次显示标题页、中文“微雪”、产品信息图、夜景线稿和仪表盘。工程还提供持续旋转的线框立方体演示，可在 config.py 中切换。

工程文件说明：

硬件连接​

工程默认配置为四线 SPI，按下表接线：

模块的 EN 引脚默认开启，本示例未使用该引脚。完成接线后，使用支持数据传输的 USB 线将 RP2350 PLUS 连接到电脑。

如需使用 I2C，请先将 OLED 模块背面的接口选择焊点切换至 I2C，再按下表接线：

同时将 config.py 中的通信接口修改为：

BUS = "I2C"

I2C 的 SDA 和 SCL 需要上拉电阻；如果模块未集成上拉电阻，需要外接合适的上拉电阻。

代码分析​

• create_display()：读取 config.py 中的 BUS，根据配置创建 SSD1312_SPI 或 SSD1312_I2C 对象；配置值不是 SPI 或 I2C 时抛出异常。
• SSD1312._initialize()：先通过 GP12 对 OLED 进行硬件复位，再发送 SSD1312 初始化命令，清除显示 RAM 后开启显示。
• SSD1312.show()：将 128 × 64 帧缓冲区分成 8 页写入 OLED，每页传输 128 字节显示数据。
• demo.run()：循环绘制标题页、中文点阵、产品信息图、夜景线稿和仪表盘，并在每次绘制后调用 show() 刷新屏幕。
• glyphs.draw_text()：逐位解析 32 × 41 单色点阵数据，用于显示中文“微雪”。
• cube.run()：对立方体的 8 个顶点进行旋转和透视投影，再连接 12 条边，约每 20 ms 绘制并刷新一帧。

在 config.py 中通过 DEMO 选择演示程序：

# OLED 综合演示
DEMO = "oled"

# 旋转线框立方体演示
# DEMO = "cube"

demo.run() 和 cube.run() 均为持续运行的循环，因此每次只能运行其中一个演示。

运行程序​

1. 为 RP2350 PLUS 安装适用的 MicroPython 固件，然后打开 Thonny。
2. 在 Thonny 中选择 MicroPython (Raspberry Pi Pico) 解释器，并选择开发板对应的串口。
3. 将 main.py、config.py、ssd1312.py、demo.py、cube.py 和 glyphs.py 全部上传到开发板文件系统的根目录。
4. 复位开发板或在 Thonny 中运行 main.py。初始化成功后，Shell 会输出：

SSD1312 initialized using SPI

使用 I2C 时，输出中的 SPI 会变为 I2C。上传文件时请保留原文件名，main.py 会在开发板启动后自动执行。

运行效果​

默认将 DEMO 设置为 "oled" 后，OLED 按以下顺序循环显示：

将 DEMO 设置为 "cube" 后，OLED 会持续显示绕竖直方向旋转的线框立方体，程序约每 20 ms 刷新一帧。

1. 示例程序​

• 0.96inch_Transparent_OLED 示例程序

2. 硬件资料​

• 0.96inch_Transparent_OLED 原理图

3. 软件工具​

• 汉字取模软件
• Image2Lcd 图片取模软件
• Flash_download_tool

4. 其他资料​

• ESP32 Arduino Core’s documentation
• arduino-esp32
• ESP-IDF

技术支持

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

手机：13434470212

邮箱：services04@spotpear.cn

QQ：202004841