# stm32F103_IoT_oneNet

**Repository Path**: kid-kid/stm32-f103_-io-t_one-net

## Basic Information

- **Project Name**: stm32F103_IoT_oneNet
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-11
- **Last Updated**: 2026-02-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SSD1306 OLED驱动库（STM32 HAL版）使用指南

---



## 一、项目概述

基于以下开源项目移植：

[github地址：https://github.com/afiskon/stm32-ssd1306](https://github.com/afiskon/stm32-ssd1306)

[字体设计网站：https://fontstruct.com/](https://fontstruct.com/)

**功能定位**：轻量级SSD1306 OLED显示驱动库，专为STM32 HAL开发环境设计，支持I2C/SPI双接口，适用于128×64/128×32等分辨率的单色OLED屏幕。只讲解I2C的使用，SPI的参考I2C即可。

**核心特性**：

- 支持I2C与4线SPI通信协议（通过宏定义切换）
- 完整图形绘制功能（点/线/圆/矩形/填充）
- 多字体支持（内置默认字体+自定义字体生成工具链）
- 无RTOS依赖，仅需STM32 HAL基础库
- 高度可配置（通过 `ssd1306_conf.h`定制参数）

---



## 二、快速集成

### 1. 文件添加

将ssd1306目录下的文件添加到工程：

```
![1770775596436](image/README_zh/1770775596436.png)![1770775596436](image/README_zh/1770775596436.png)📦SSD1306
 ┣ 📂examples ← 自定义字体转换例程
 ┃ ┗ 📂custom-fonts
 ┃ ┃ ┣ 📜arial.ttf  ← 字体文件必须放在当前.py脚本目录下
 ┃ ┃ ┣ 📜convert.py ← .txt字体文件转C代码脚本
 ┃ ┃ ┣ 📜font.c   ← 生成的字体数组
 ┃ ┃ ┣ 📜generate.py ← TrueType字体转换脚本
 ┃ ┃ ┣ 📜hd44780-large.txt  ←通过upscale.py放大后的自定义字体文件
 ┃ ┃ ┣ 📜hd44780-small.txt ←自定义字体文本本文件
 ┃ ┃ ┣ 📜README.md
 ┃ ┃ ┗ 📜upscale.py ← 字体放大脚本
 ┣ 📂ssd1306  ←驱动目录
 ┃ ┣ 📜ssd1306.c  ← 驱动文件
 ┃ ┣ 📜ssd1306.h
 ┃ ┣ 📜ssd1306_conf.h  ← ssd1306_conf_template复制过来并修改的配置文件
 ┃ ┣ 📜ssd1306_conf_template.h  ← 原始模板文件
 ┃ ┣ 📜ssd1306_fonts.c   ← 字体数组
 ┃ ┣ 📜ssd1306_fonts.h
 ┃ ┣ 📜ssd1306_tests.c ← 测试代码文件
 ┃ ┗ 📜ssd1306_tests.h


```

如下所示：添加相关.c文件

![1770775559309](image/README_zh/1770775559309.png)

### 2. 配置步骤

1.复制模板文件，将ssd1306_conf_template.h文件复制重命名为ssd1306_conf.h，并配置 `ssd1306_conf.h`关键参数：

![1770775120095](image/README_zh/1770775120095.png)

2.修改ssd1306.h中的相关配置：

![1770774995561](https://file+.vscode-resource.vscode-cdn.net/c%3A/Users/Administrator/Desktop/stm32F103_oneNet/BSP/SSD1306/image/README_zh/1770774995561.png)

### 3. 初始化与使用

```c
//............
#include "ssd1306.h"
#include "ssd1306_tests.h"
int main(void)
{
  HAL_Init();
  SystemClock_Config();
  MX_GPIO_Init();
  MX_DMA_Init();
  MX_USART1_UART_Init();
  MX_I2C1_Init();
  while (1)
  {
	//运行测试代码
      ssd1306_TestAll();
  }

}
//............
```

运行代码可以看到效果：

![1770775801892](image/README_zh/1770775801892.png)

---



## 三、使用自定义字体生成

### 1. 工具准备

进入 `examples/custom-fonts`目录，确保已安装Python 3.6+

注意：下面每个.py脚本需要安装对应的python库，如果没装可以查看py文件需要哪些库

通过pip install的方式手动安装。

### 2. 生成流程

#### 方式一：TrueType字体转换（推荐）

1.可以通过 `generate.py ` 创建自定义字体,生成字体数组在 `font.c`

```shell
python generate.py --font arial.ttf --size 20
```

 **注意：** 生成的位图的实际高度可能有所不同

2.要生成等宽（非等宽）字体，请添加 `--proportional`标志

```shell
python generate.py --font Roboto-Thin.ttf --size 15 --proportional 
```

3.通过下面的命令生成预览图片。

```shell
python generate.py --font arial.ttf --size 20 --atlas atlas.png
```

![1770790404705](image/README_zh/1770790404705.png)



---



#### 方式二：位图字体转换（不推荐）

1. 准备位图字体文件（如 `hd44780-small.txt`）
   `hd44780-small.txt`需要手动准备，可以参考[https://fontstruct.com/](https://fontstruct.com/)网站搜索或者建立自己的字体文件。
2. 执行放大处理（示例：5×8 → 16×24）：
   ```bash
   python upscale.py -f hd44780-small.txt -x 5 -y 8 -s 3 > hd44780-large.txt
   ```
3. 生成C代码：
   ```bash
   python convert.py -f hd44780-large.txt -x 16 -y 24
   ```

### 3. 集成到工程

1. 将生成的 `font.c`内的字体数组添加到工程
2. 在.h文件中新增字体引用：
   ```c
   #ifdef SSD1306_INCLUDE_FONT_13x20
   extern const SSD1306_Font_t Font_13x20;
   #endif
   ```

![1770776075563](image/README_zh/1770776075563.png)

3.在ssd1306_conf.h中增加新字体宏定义

![1770776178712](image/README_zh/1770776178712.png)

### 4.使用新字体

直接传入新添加的字体文件即可：

![1770776320392](image/README_zh/1770776320392.png)

---



## 四、显示中文（通过位图的的方式）

由于SSD1306驱动库默认仅支持ASCII字符（32-126），直接调用 `ssd1306_WriteString`无法显示中文。推荐采用以下**最简单可靠**的方式：

### 1. 使用 `generate.py`生成中文位图（推荐）

进入 `examples/custom-fonts`目录，执行以下命令：

```bash
# 生成"温度：25℃"字符串的位图（使用微软雅黑字体）
python generate.py --font "C:/Windows/Fonts/msyh.ttc" --size 16 --string "温度：25℃"
```

生成的字体和预览图片如下：

![1770790611345](image/README_zh/1770790611345.png)

> **注意**：
>
> - Windows系统下字体路径通常为 `C:/Windows/Fonts/msyh.ttc`（微软雅黑）或 `simhei.ttf`（黑体）
> - 若提示字体未找到，请确保字体文件存在，或尝试其他常见中文字体
> - 命令执行后会生成 `string.c`和 `string.png`预览图

### 2. 集成到工程

1. 将生成的 `string.c`中的数组拷贝到代码中
2. 在您代码中使用：
3. 使用 `ssd1306_DrawBitmap`函数绘制：
   ```c
   // 清屏
   ssd1306_Fill(Black);

   // 在坐标(0, 0)处绘制中文字符串
   ssd1306_DrawBitmap(0, 0, string_120x19, 120, 19, White);

   // 刷新屏幕
   ssd1306_UpdateScreen();
   ```

显示效果如下：

 ![1770790807522](image/README_zh/1770790807522.png)


### 3. 替代方案：修改驱动以支持宽字符（高级）

若需动态显示任意中文，可修改 `ssd1306_WriteChar`函数，但这需要：

- 修改字符范围检查逻辑（移除 `ch < 32 || ch > 126`限制）
- 扩展字体数据结构以支持UTF-8解码和多字节索引
- 为常用汉字创建专用字体数组（如 `Font_16x16_Chinese`）
  此方案复杂度高，且易引入兼容性问题，**不推荐初学者使用**。

> 💡 **最佳实践建议**：
> 对于嵌入式OLED应用，通常只需显示固定几个中文词汇（如状态、单位、提示信息）。因此，为这些特定字符串生成位图是最高效、最节省资源的方法。

## 五、图片显示

![1770790876518](image/README_zh/1770790876518.png)

1.准备好.BMP格式的图片

    可以下载.png/.jpg使用电脑自带画图软件转成.bmp或者其他工具

2.使用取模软件进行取模

   这里使用PCtoLCD2002这款软件：

![1770778894671](https://file+.vscode-resource.vscode-cdn.net/c%3A/Users/Administrator/Desktop/stm32F103_oneNet/BSP/SSD1306/image/README_zh/1770778894671.png)





---



另外，这款软件还可以选择字符模式，对生成相应的字符，不过此方式不适用于这个驱动库，因为生产成的字体数组不适用此驱动，需要准备适合这个软件的驱动。

![1770779152288](image/README_zh/1770779152288.png)

---



## 六、关键API说明

| 函数                                      | 说明                        |
| ----------------------------------------- | --------------------------- |
| `ssd1306_Init()`                        | 初始化OLED（自动调用Reset） |
| `ssd1306_Fill(color)`                   | 全屏填充（Black/White）     |
| `ssd1306_DrawPixel(x,y,color)`          | 绘制单个像素                |
| `ssd1306_WriteString(str, font, color)` | 显示字符串                  |
| `ssd1306_UpdateScreen()`                | 将缓冲区刷新到屏幕          |
| `ssd1306_SetContrast(value)`            | 调整对比度（0~255）         |



---



## 七、常见问题

**Q：屏幕无显示？**

- 检查I2C地址（0x3C/0x3D）是否与硬件匹配
- 确认 `SSD1306_I2C_ADDR`宏定义正确
- 验证HAL_I2C初始化是否完成

**Q：字体显示异常？**

- 检查字体高度是否与 `SSD1306_HEIGHT`匹配
- 确保字体文件已正确添加到工程
- 使用 `Font_11x18`等内置字体验证基础功能

**Q：SPI通信失败？**

- 确认 `SSD1306_CS_Pin`/`DC_Pin`配置正确
- 检查SPI时钟极性/相位是否与OLED要求一致
- 建议SPI速率≥1MHz

> 详细技术文档请参考：[SSD1306数据手册](https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf)