TFT ILI9341 显示屏演示：Arduino 上的图形与弹球动画

引言

彩色 TFT 显示屏是为 Arduino 项目增添丰富视觉反馈的绝佳方式。在本教程中，我们将使用 Adafruit ILI9341 和 Adafruit GFX 库驱动一块 240x320 分辨率的 ILI9341 型 TFT 屏幕。你将学习如何连接显示屏、安装所需库，并编写代码来绘制静态 UI 元素以及实现弹球动画。这一切都可以在 Velxio 模拟器中直接运行，无需任何硬件！

电路讲解

我们先来检查电路。原理图很简单：Arduino Uno 通过 SPI（串行外设接口）与 ILI9341 显示屏通信。

以下是完整的接线列表：

• SCK（串行时钟） 和 MOSI（主出从入） 是 SPI 数据线。它们负责将时钟和数据从 Arduino 传输到显示屏。
• CS（片选） 告诉显示屏何时监听 SPI 命令。低电平有效。
• D/C（数据/命令） 选择 SPI 传输的是命令还是像素数据。
• RST（复位） 复位显示屏控制器。我们将其连接到一个数字引脚，以便在需要时执行硬件复位。
• LED 控制背光。我们将其设置为高电平以打开背光。

无需外部元件——显示屏工作在 5V 逻辑电平（大多数 ILI9341 模块兼容 5V），SPI 引脚直接连接即可。

代码讲解

现在让我们深入代码。我们将使用 Adafruit ILI9341 库以及 Adafruit GFX 库来实现图形基元。这些库需要通过库管理器安装。

打开库管理器（工具 > 管理库），搜索 “Adafruit ILI9341” 和 “Adafruit GFX Library”。安装两者。SPI 库会自动包含。

以下是完整代码：

// TFT ILI9341 显示屏演示 (240x320)
// 库：Adafruit ILI9341 + Adafruit GFX
// 连接：CS=10, DC/RS=9, RST=8, LED=7, MOSI=11(SPI), SCK=13(SPI)

#include <Adafruit_GFX.h>
#include <Adafruit_ILI9341.h>
#include <SPI.h>

#define TFT_CS   10
#define TFT_DC    9
#define TFT_RST   8
#define TFT_LED   7

Adafruit_ILI9341 tft(TFT_CS, TFT_DC, TFT_RST);

// 背景颜色：蓝色（在深色模拟器画布上可见）
#define BG_COLOR 0x001F

// 球的状态
int ballX = 120, ballY = 200;
int ballDX = 3, ballDY = 2;
const int BALL_R = 10;

// 运动场边界
const int FX = 5, FY = 110, FW = 230, FH = 200;

void drawStaticUI() {
  tft.fillScreen(BG_COLOR);

  // 标题
  tft.setTextSize(3);
  tft.setTextColor(tft.color565(255, 220, 0));
  tft.setCursor(20, 10);
  tft.print("VELXIO TFT");

  // 副标题
  tft.setTextSize(2);
  tft.setTextColor(tft.color565(180, 180, 255));
  tft.setCursor(30, 50);
  tft.print("ILI9341 Demo");

  // 调色板条
  tft.fillRect(10, 82, 70, 18, tft.color565(220, 50, 50));
  tft.fillRect(85, 82, 70, 18, tft.color565(50, 200, 50));
  tft.fillRect(160, 82, 70, 18, tft.color565(50, 100, 240));

  // 运动场边框
  tft.drawRect(FX, FY, FW, FH, tft.color565(80, 80, 130));
}

void setup() {
  pinMode(TFT_LED, OUTPUT);
  digitalWrite(TFT_LED, HIGH);

  tft.begin();
  drawStaticUI();
}

void loop() {
  // 擦除旧球
  tft.fillCircle(ballX, ballY, BALL_R, BG_COLOR);

  // 更新位置
  ballX += ballDX;
  ballY += ballDY;

  // 在边界反弹
  if (ballX < FX + BALL_R + 1 || ballX > FX + FW - BALL_R - 1) ballDX = -ballDX;
  if (ballY < FY + BALL_R + 1 || ballY > FY + FH - BALL_R - 1) ballDY = -ballDY;

  // 绘制球
  tft.fillCircle(ballX, ballY, BALL_R, tft.color565(255, 140, 0));

  delay(30);
}

代码要点

• 引脚定义：我们将 TFT_CS、TFT_DC、TFT_RST 和 TFT_LED 分别定义为引脚 10、9、8 和 7。这与我们的接线一致。
• 库初始化：Adafruit_ILI9341 tft(TFT_CS, TFT_DC, TFT_RST); 创建了显示对象。库内部处理 SPI 通信。
• 背光控制：在 setup() 中，我们将引脚 7 设置为高电平以打开背光。如果没有这一步，屏幕将保持黑暗。
• 静态 UI：drawStaticUI() 用蓝色背景填充屏幕，打印两行文本，绘制三个彩色矩形作为调色板，并勾勒出运动场矩形边框。
• 动画循环：在 loop() 中，我们通过绘制一个背景色的实心圆来擦除旧球，更新其位置，检查与运动场边界的碰撞，然后以橙色重新绘制球。delay(30) 控制帧率。
• 颜色转换：tft.color565(r, g, b) 将 8 位 RGB 值转换为显示屏使用的 16 位 565 格式。

学生需掌握的关键概念

1. SPI 通信：显示屏使用 SPI，这是一种同步串行协议。Arduino 是主机，显示屏是从机。数据传输仅需三根线（SCK、MOSI、CS）；D/C 和 RST 是额外的控制线。
2. 图形基元：Adafruit GFX 库提供了诸如 fillScreen()、fillRect()、drawRect()、fillCircle()、setCursor()、print() 和 setTextSize() 等函数。这些函数使得绘制形状和文本变得简单。
3. 双缓冲（概念）：我们在绘制新球之前擦除旧球。这可以防止拖影。在更高级的项目中，你可能会使用帧缓冲区。
4. 碰撞检测：弹球逻辑检查球的中心是否距离边界小于 BALL_R 像素。如果是，则反转方向。
5. 色深：ILI9341 支持 262K 颜色（18 位），但库为了速度使用 16 位（65K 颜色）。color565() 将 RGB 打包成 5-6-5 位格式。

常见问题与调试技巧

• 背光关闭：如果屏幕保持黑暗，请确保引脚 7 设置为高电平。在模拟器中，检查 LED 引脚线是否已连接。
• 引脚错误：仔细检查 CS、DC、RST、MOSI 和 SCK 是否与代码匹配。任何一根线接错都可能导致输出混乱或屏幕无显示。
• 库未安装：没有 Adafruit 库，代码将无法编译。请使用库管理器安装它们。
• SPI 冲突：如果有其他 SPI 设备，请确保它们的 CS 引脚不会同时激活。本例中只有 TFT 使用 SPI。
• 球消失：如果球离开了运动场，请检查碰撞边界。条件中使用 FX + BALL_R + 1 是为了考虑球的半径。

建议的扩展功能

在基本演示运行成功后，可以尝试以下增强：

• 添加第二个球，具有不同的速度和颜色。
• 显示传感器数据（例如来自电位器的数据），以条形图或数字形式呈现。
• 创建一个简单游戏，如乒乓球或反应计时器。
• 使用触摸输入，如果你的显示屏带有触摸控制器（例如 XPT2046）。
• 优化性能，使用 startWrite() 和 endWrite() 来批量处理 SPI 事务。

亲自尝试！

准备好看看效果了吗？在 Velxio 中打开实时示例，然后点击 运行 按钮。

你还可以探索画布工具栏，进行缩放、平移和检查仿真。

如果你想从头开始构建，请使用组件选择器添加一个 Arduino Uno 和一个 ILI9341 显示屏。

点击下面的链接打开示例并开始实验：

在 Velxio 上打开 TFT ILI9341 显示屏演示

祝你编程愉快！