# esp32-oled-driver

**Repository Path**: anduoyun/esp32-oled-driver

## Basic Information

- **Project Name**: esp32-oled-driver
- **Description**: 本项目是基于江协科技 STM32 OLED 显示屏驱动移植而来的 ESP32-S3 OLED 显示屏驱动库，适用于 128x64 分辨率的 OLED 屏幕（I2C 接口）。本驱动库专为 ESP32-S3 开发板设计，支持 ESP-IDF 5.3.1 开发环境。
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 1
- **Created**: 2025-02-10
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: ESP32, 驱动, oled

## README

# ESP32-S3 OLED 显示屏驱动

本项目是基于**江协科技 STM32 OLED 显示屏驱动**移植而来的 ESP32-S3 OLED 显示屏驱动库，适用于 128x64 分辨率的 OLED 屏幕（I2C 接口）。本驱动库专为 ESP32-S3 开发板设计，支持 ESP-IDF 5.3.1 开发环境。

## 项目简介

本驱动库基于江协科技的 STM32 OLED 驱动代码移植而来，适配 ESP32-S3 的硬件 I2C 控制器，并针对 ESP-IDF 开发环境进行了优化。支持显示 ASCII 字符、汉字、图形等内容，适用于各种需要 OLED 显示屏的 ESP32-S3 项目。

### 特性

- **支持多种显示内容**：
  - ASCII 字符（8x16 和 6x8 两种字体）
  - 汉字（16x16 点阵）
  - 图形（支持任意尺寸的图像显示）
  - 基本图形绘制（点、线、矩形、圆、椭圆等）
- **高效硬件 I2C**：使用 ESP32-S3 的硬件 I2C 控制器，性能优于 GPIO 模拟 I2C。
- **易用性**：提供简洁的 API 接口，方便快速集成到项目中。
- **可移植性**：代码结构清晰，易于移植到其他 ESP32 系列开发板。
- **开源免费**：基于 MIT 许可证开源，允许自由使用和修改。

## 硬件要求

- **开发板**：ESP32-S3
- **OLED 屏幕**：128x64 分辨率，I2C 接口
- **接线**：
  - SCL -> GPIO 5
  - SDA -> GPIO 4
  - VCC -> 3.3V
  - GND -> GND

## 开发环境

- **操作系统**：Windows 11
- **开发框架**：ESP-IDF 5.3.1
- **编译器**：GCC

## 快速开始

### 1. 克隆项目

```bash
git clone https://gitee.com/sida-li/esp32-oled-driver.git
cd esp32s3-oled-driver
```

### 2. 配置目标

确保已安装 ESP-IDF 5.3.1，并设置好开发环境。然后配置项目：
```
idf.py set-target esp32s3
idf.py menuconfig # 根据板子实际情况修改flash大小和cpu频率
```

### 3. 修改引脚 
在 `main/hardware/OLED.h` 中，检查以下配置：
- **I2C 引脚配置**：确保 SCL 和 SDA 引脚与硬件接线一致（默认 SCL=5，SDA=4）。
```c
#define SCL_PIN          5
#define SDA_PIN          4
```

### 4. 编译烧录

```c
idf.py build
idf.py -p PORT flash monitor
```
将 `PORT` 替换为实际的串口端口号（如 COM3）。

## API 参考

### 初始化

- `void OLED_Init(void)`：初始化 OLED 屏幕。

### 显示控制

- `void OLED_Clear(void)`：清空屏幕。
- `void OLED_Update(void)`：将显存内容更新到屏幕。
- `void OLED_ShowChar(int16_t X, int16_t Y, char Char, uint8_t FontSize)`：显示单个字符。
- `void OLED_ShowString(int16_t X, int16_t Y, char *String, uint8_t FontSize)`：显示字符串。
- `void OLED_ShowChinese(int16_t X, int16_t Y, char *Chinese)`：显示汉字。
- `void OLED_ShowImage(int16_t X, int16_t Y, uint8_t Width, uint8_t Height, const uint8_t *Image)`：显示图像。

### 图形绘制

- `void OLED_DrawPoint(int16_t X, int16_t Y)`：绘制点。
- `void OLED_DrawLine(int16_t X0, int16_t Y0, int16_t X1, int16_t Y1)`：绘制直线。
- `void OLED_DrawRectangle(int16_t X, int16_t Y, uint8_t Width, uint8_t Height, uint8_t IsFilled)`：绘制矩形。
- `void OLED_DrawCircle(int16_t X, int16_t Y, uint8_t Radius, uint8_t IsFilled)`：绘制圆形。
- `void OLED_DrawEllipse(int16_t X, int16_t Y, uint8_t A, uint8_t B, uint8_t IsFilled)`：绘制椭圆。

## 许可证

本项目基于 MIT 许可证开源。详细信息请参阅 [LICENSE](LICENSE) 文件。

## 致谢

- 本驱动基于江协科技的 STM32 OLED 显示屏驱动移植而来，感谢江协科技的开源贡献。
- 感谢 ESP-IDF 团队提供的强大开发框架。

## 反馈与贡献

如果您在使用过程中遇到问题或有改进建议，欢迎提交 Issue 或 Pull Request。您的支持是项目发展的动力！