3.使用ST7789v高清彩色TFT显示屏.md · 梁墨鸢/EFR32xG24 Explorer Kit CircuitPython学习仓库

# 3.使用st7789v高清彩色TFT显示屏

st7789v高清彩色TFT显示屏是在嵌入式产品方面，非常常用的一款彩色显示屏。
![](assets/17039897738064.jpg)

这个类型的显示屏，是SPI接口的，全彩65K，颜色丰富，显示效果好。其大小有多种，如1.14、1.54、2.0、3.2等，分辨率也有很多种，如：135x240、240x240、170x320、240x320等。

这篇分享，就在 EFR32xG24 Explorer Kit 上，使用 SPI 接口的 大小1.14寸 分辨率135x240的st7789v高清彩色TFT显示屏 进行信息和图片显示。
在 CircuitPython 环境下，使用displayio来驱动显示屏的话，除了初始化有差异以外，其他调用都基本一样。因此，这篇分享，与前一篇 **使用SSD1306 OLED单色显示屏** 内容上有较多重复的地方。

## 一、硬件接口了解
### 1. st7789v显示屏
我所使用的st7789v显示屏是下面这种：
![](assets/17039878612527.jpg)

其使用SPI接口，除了通常SPI片选和通信的引脚外，还需要RES、DC、BLK引脚连接。

### 2. EFR32xG24 Explorer Kit
在 EFR32xG24 Explorer Kit 上，一共有2个位置，可以连接SPI设备：
![](assets/17039902577215.jpg)

#### 1) mikroBUS接口
mikroBUS由一对1x8的母头，且丝印固定的引脚组成，包括三种最常用的通信接口：SPI、I2C、UART, 以及模拟输入、PWM、复位、片选，以及3.3V、5V和GND，根据丝印，通常SPI和3.3V在左，I2C、UART和5V在右。
![](assets/17039487033670.jpg)
用它来连接上面的 st7789v显示屏 ，一样也要注意线序和VCC、GND。实际使用中，引脚不够，需要使用mikroBUS以外的引脚。
另外需要注意的是，要先确定所使用的st7789v显示屏的工作电压，如果是3.3V的， 那么就只能接3V3，接5V就会烧了。我的st7789v显示屏最高工作电压为3.3V~5V，所以供电我使用3V3。

#### 2). Breakout Pads接口
Breakout Pads就是我们常说的普通接口了，自己焊针或者焊母头都可以。
在 EFR32xG24 Explorer Kit开发板的mikroBUS母头的外面两边各1列，就是Breakout Pads，比mikroBUS要多一些引脚。
![](assets/17039491983244.jpg)

从上面的标注也可以看出，这些引脚中与mikroBUS母头挨着的，实际上与mikroBUS的功能，是一一对应的。

在Breakout Pads接口上连接st7789v显示屏，与mikroBUS接口一样，也务必要注意连接正确的供电接口，以及对应的SPI引脚。

## 二、实际接线
因为设计到的连线比较多，下面就把EFR32xG24 Explorer Kit开发板和st7789v显示屏引脚的连接详细列出来：

| xG24-EK                | st7789v | 说明     |
|------------------------|---------|----------|
| GND                    | GND     | 共地     |
| VMCU                   | VCC     | 供电     |
| PC01 - MIKROE_SPI_SCK  | SCL     | 时钟信号 |
| PC03 - MIKROE_SPI_MOSI | SDA     | MOSI     |
| PC08 - MIKROE_RST      | RES     | RESET    |
| PC09                   | DC      | 命令     |
| PC00 - MIKROE_SPI_CS   | CS      | 片选     |
| PB00 - MIKROE_ANALOG   | BLK     | 背光     |

根据我所使用的连接线(双头母头)，我直接将ST7789连接到了Breakout Pads接口。

## 三、显示屏驱动和扩展库
### 1. 安装驱动库和扩展库
在CircuitPython中，使用displayio来驱动显示屏，而驱动不同的显示屏，需要对应的驱动程序。
另外，驱动了显示屏，还要在显示屏上进行具体内容的显示。在 CircuitPython中，使用 adafruit_display 相关的扩展库来提显示文本、图形等功能。
因此在编写正式的程序代码之前，为了配合本次分享的实际内容，还需要先下载以下的库：
* adafruit_st7789：st7789驱动库
* adafruit_bitmap_font：位图字体库
* adafruit_display_text：文本显示库
* adafruit_imageload：图片调用库

要安装上面的扩展库，可以使用Thonny的插件安装功能：
![](assets/17039532384565.jpg)

在插件管理界面，按照下面的步骤，安装插件：
![](assets/17039989627168.jpg)

![](assets/17039989859349.jpg)

依次安装上面列出的所有扩展库，安装完成后，从下面的途径，打开插件安装的目录：
![](assets/17039535010296.jpg)

找到安装的新的扩展库：
![](assets/17039991693838.jpg)

### 2. 上传驱动库和扩展库到开发板
首先将开发板连接到电脑，并打开Thonny，选择好对应的解析器和端口，确保连上：
![](assets/17039539156473.jpg)

然后，在 Thonny中，打开文件浏览：
![](assets/17039538394730.jpg)

按照下面的步骤，先进入开发板上的lib目录，然后本地目录切换到上一步扩展库安装后的目录，并上传实际需要的扩展库：
![](assets/17039993785702.jpg)

### 3. 检查上传安装结果
上传完成后，执行下面的命令，检查是否上传成功：
```
import adafruit_st7789
import adafruit_bitmap_font
import adafruit_display_text
import adafruit_imageload
```
正确上传后，运行的结果如下：
![](assets/17039995018191.jpg)

## 四、显示英文
通过前面的步骤，安装好了扩展库，下面就可以开始实际显示程序的编写了。
### 1. 驱动显示屏
首先，需要将显示设备关联到SPI接口连接的st7789显示屏，具体代码如下：
```
import board
import displayio
import digitalio
import adafruit_st7789

displayio.release_displays()

# 引脚定义
TFT_BL = board.PB0
TFT_DC = board.PC9
TFT_CS = board.MIKROE_CS
TFT_RST = board.MIKROE_RST

# 屏幕背光开启
tft_bl = digitalio.DigitalInOut(TFT_BL)
tft_bl.switch_to_output()
tft_bl.value = True

# spi设备检查
spi = board.SPI()
while not spi.try_lock():
    pass
spi.configure(baudrate=24000000) # Configure SPI for 24MHz
spi.unlock()

# 显示设备初始化
display_bus = displayio.FourWire(spi, command=TFT_DC, chip_select=TFT_CS, reset=TFT_RST)
display = adafruit_st7789.ST7789(
    display_bus, rotation=270, width=240, height=135, rowstart=40,colstart=53
)
```
当使用 EFR32xG24 Explorer Kit 开发板上mikroBUS、Breakout Pads上默认的SPI引脚时，则使用 board.SPI() 来实例化默认的SPI设备。
然后通过displayio和adafruit_st7789进行关联，最终得到 display ，就是用于屏幕操作的对象了。
在实际使用中，可能需要调整`rotation`，使得屏幕的方向在正确的方向显示。另外，还需要设置好`rowstart,colstart`，使得实际的显示区域与屏幕刚好一致。
我所使用的st7789v分辨率为135x240，所以上述代码中设置了`rotation=270, width=240, height=135, rowstart=40,colstart=53`，以便得到合适的显示结果。

### 2. 使用位图显示区块
上面进行了初始化，我们需要检验一下，初始化是否成功，分辨率设置是否正确。
可以用下面的代码进行检验：
```
# 在屏幕上显示两个区块
splash = displayio.Group(scale=2)
display.root_group = splash

color_bitmap = displayio.Bitmap(int(240/2), int(135/2), 1)
color_palette = displayio.Palette(1)
color_palette[0] = 0xFF0000 # 红色
bg_sprite = displayio.TileGrid(color_bitmap,
                               pixel_shader=color_palette,
                               x=0, y=0)
splash.append(bg_sprite)

color_bitmap1 = displayio.Bitmap(int((240-10)/2), int((135-10)/2), 1)
color_palette1 = displayio.Palette(1)
color_palette1[0] = 0xFFFF00 # 黄色
bg_sprite1 = displayio.TileGrid(color_bitmap1,
                               pixel_shader=color_palette1,
                               x=2, y=2)
splash.append(bg_sprite1)
```

上述代码，先在屏幕上，画一个铺满屏幕的红色的长方形区域，然后再画一个小一点的黄色长方块区域。
运行后，实际的运行效果见本文最后的配图。

从图中可以看到，黄色块内嵌于红框之类，红框四边宽度一致，说明前面的初始化都设置正确了。

### 3. 显示英文
然后，使用下面的代码来显示英文字符：
```
import terminalio
from adafruit_display_text import label

text = "Happy New Year!"
text_area = label.Label(terminalio.FONT, text=text, color=0xFFFFFF, x=20, y=20)
splash.append(text_area)
```

将上述代码保存，然后运行，最终实际的效果本文最后的配图。

## 五、显示中文
### 1. 中文字体
在CircuitPython中，通过displayio显示中文，本质上，和英文没有什么区别，要说有什么差别，那就是显示中文，要使用含有中文点阵库的字体文件。
在前面显示英文的过程中，使用了 terminalio.FONT ，这个是CircuitPython提供的一个内置英文字体库，可以方便的显示英文。
英文只有26个，加上字符啥的，也不超过127个，1个8x8的点阵字库占用空间不到8K，所以完全可以内置。
但是，中文有成千上万个，就算1000个汉字，使用8*8的点阵数据(实际不行，不足以支撑大多数汉字的显示)，如果直接内置，那么也要占用上100K的空间(实际不止这么大)，而且调用时查询速度也慢。所以，如果在MCU中，要在显示屏上显示中文，一般采用如下两种方式：
1. 使用额外的字库芯片，帮助存储汉字字库。例如有的显示屏模块上，就自带了汉字字库便于调用。
2. 生成只包含需要显示的汉字字符的字库，从而极大地减小字库文件的大小，并大幅提高字符查询的速度。

通常情况下，会采用第2中方式，较为通用。

在 Adafruit官方提供的学习资料 [Custom Fonts for CircuitPython Displays](https://learn.adafruit.com/custom-fonts-for-pyportal-circuitpython-display/overview) 中，给出了使用自定义字体的详细指导。
其中，使用的工具是FontForge，下载地址：[Download FontForge](https://fontforge.org/en-US/downloads/)。

参考该指导，最终使用如下的步骤，来进行要显示的字库的生成。
#### 1). 打开需要使用的字体文件
在字体网站，或者本机字体库，找到想要使用的ttf字体文件，然后使用FontForge打开：
![](assets/17039563227472.jpg)

#### 2). 生成字符过滤脚本
访问 [https://honestqiao.gitee.io/web_bdf2pcf/](https://honestqiao.gitee.io/web_bdf2pcf/)，在**FontForge定制显示字符集脚本生成工具**部分，直接点击转换为脚本，会有演示。
然后参考演示，修改添加需要显示的中文字符：
![](assets/17039561560313.jpg)
#### 3). 在 FontForge 中执行脚本
拷贝上述界面生成的脚本，在 FontForge 中打开脚本执行界面运行：
![](assets/17039564002582.jpg)

![](assets/17039564464414.jpg)

只看成功后，会显示如下：
![](assets/17039564719586.jpg)

#### 4). 生成需要显示字符的位图数据
按照下图点击紧凑后，就能看到所有需要用于显示的字符：
![](assets/17039565289035.jpg)

上述脚本生成界面，会默认选择英文字符，便于实际使用。如果不需要的话，看群出字形修改脚本，去掉不需要显示的字符。

然后，生成可用位图部件：
![](assets/17039566778841.jpg)

![](assets/17039567344822.jpg)

在CircuitPython中，因为使用的是位图字体，所以是不能调整显示字符的字号大小的。
如果改变上述设置中的像素大小，则最终显示时，会根据这里的设置，改变实际显示的大小。

#### 5). 生成字体
最后，然后最终的字体文件：
![](assets/17039568315831.jpg)

![](assets/17039568955664.jpg)

在生成字体时，必须选择输出位BDF文件，才可以在CircuitPython中使用。

#### 6). 转换为pcf字体文件
上一步生成的bdf文件，已经可以在CircuitPython中直接使用。
但如果转换为pcf文件格式，则字体文件更小，而且查询速度更快。
要转换为pcf文件格式，回到刚才的页面 [https://honestqiao.gitee.io/web_bdf2pcf/](https://honestqiao.gitee.io/web_bdf2pcf/) ，在 **网页版bdf转pcf字体转换工具** 部分，选择刚才生成的bdf字体文件，就会自动转换并下载：
![](assets/17039571659244.jpg)
#### 6). 上传字体文件到开发板
转换完成后，将转换生成的pcf文件，上传到开发板的fonts目录：
![](assets/17039572051638.jpg)

现在，中文字体准备好了，可以用于中文显示了。
上面的操作步骤，看起来挺复杂的，实际上都是简单的操作，进行过几次就能熟练，后续要生成需要显示的中文，10几秒就能搞定。

### 2. 显示中文
字体文件准备号以后，在前面显示英文的基础上，做简单修改，调用中文字体即可，具体代码如下：
```
import terminalio
from adafruit_display_text import label
from adafruit_bitmap_font import bitmap_font
from adafruit_display_text import label

font_cn_file = "/fonts/SJruosixingkai-21-2024-20.pcf"
font_cn = bitmap_font.load_font(font_cn_file)

text_cn = "元旦快乐!"
text_cn_area = label.Label(font_cn, text=text_cn, color=0xFFFFFF, x=20, y=40)
splash.append(text_cn_area)
```

在上述代码中，显示中文的部分，就是先调用中文字体，然后使用label.Label()显示中文的时候，传入中文字体即可。

保存后，运行上述代码，实际效果如下：
![](assets/17040232718561.jpg)

在上面的图片中，将SSD1306 OLED显示屏，放在一起进行对比。

## 六、总结
EFR32xG24 Explorer Kit 提供的各种类型的接口，真的是非常的方便，连接外部设备很容易。
再加上CircuitPython的加持，驱动显示屏的工作，基本上是拿来即用，把时间用在自己想要做的实际工作上，效率会更高。
赶紧把你手头的st7789显示屏拿出来，在 EFR32xG24 Explorer Kit 上点亮吧！

## 七、 学习资料
关于 在CircuitPython 中 st7789/st7735 的详细用法，以及显示屏使用，可以前往Adafruit官方查看学习资料：
* [ Adafruit 1.14" 240x135 Color TFT Breakout LCD Display](https://learn.adafruit.com/adafruit-1-14-240x135-color-tft-breakout)
* [CircuitPython Display Support Using displayio](https://learn.adafruit.com/circuitpython-display-support-using-displayio)
* [Custom Fonts for CircuitPython Displays](https://learn.adafruit.com/custom-fonts-for-pyportal-circuitpython-display/overview)

梁墨鸢/EFR32xG24 Explorer Kit CircuitPython学习仓库

简介

发行版

贡献者

近期动态

梁墨鸢/EFR32xG24 Explorer Kit CircuitPython学习仓库 .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

梁墨鸢/EFR32xG24 Explorer Kit CircuitPython学习仓库