1. 项目缘起：为什么要在屏幕上“看”加速度？

几年前，我第一次接触嵌入式开发时，总觉得传感器数据是“看不见摸不着”的。你写一段代码，读取加速度计的X、Y、Z轴数值，通过串口打印出来，屏幕上滚动着一串串像Accel: X=0.12, Y=0.98, Z=9.81这样的数字。虽然数据准确，但非常不直观。你很难立刻从这些数字中感知到设备是静止、晃动，还是正在自由落体。这种体验，就像医生只看化验单上的数字，而不是看一张清晰的X光片。

后来，我开始使用像Wio Terminal这样的设备，它自带一块2.4英寸的彩色LCD屏幕。我突然意识到，把传感器数据可视化，是理解物理世界与数字世界交互最直接、最有效的方式。将加速度计的读数实时显示在屏幕上，不仅仅是做一个“仪表盘”，它更是一个强大的调试工具和学习平台。你可以亲眼看到，当你轻轻倾斜设备时，哪个轴的数值在敏感变化；当你快速晃动时，数值的响应速度和范围是怎样的。这种直观的反馈，能让你迅速建立起对传感器特性、坐标系、数据滤波等概念的深刻理解。

所以，这个项目的核心价值，就是打通从物理信号到视觉感知的“最后一公里”。它适合所有正在学习物联网、嵌入式系统、传感器应用的开发者，尤其是那些已经厌倦了盯着串口监视器，希望更生动地与硬件对话的朋友。通过Wio Terminal，我们不仅能读取数据，更能“看见”数据，让无形的力变得有形。

2. Wio Terminal与加速度计硬件探秘

在动手写代码之前，我们必须先搞清楚手中的“武器”。Wio Terminal之所以成为原型开发的利器，在于其高度集成的设计。它不仅仅是一个单片机开发板，更是一个自带输入输出设备的完整系统。

2.1 Wio Terminal的核心架构

Wio Terminal的主控芯片是Microchip的ATSAMD51，这是一颗基于Arm Cortex-M4F内核的微控制器，运行频率高达120MHz，并带有硬件浮点运算单元（FPU）。对于处理传感器数据和图形渲染来说，充足的算力和FPU至关重要。更重要的是，它集成了LCD驱动器、三轴加速度计（LIS3DHTR）、麦克风、蜂鸣器、按键、光线传感器等多种外设。这种“All-in-One”的设计，让我们无需焊接任何飞线，就能开始这个项目。

我们重点关注的加速度计型号是STMicroelectronics的LIS3DHTR。这是一款数字输出、低功耗的三轴加速度传感器。它的“数字输出”特性意味着内部已经集成了模数转换器（ADC），我们通过I2C或SPI总线直接读取的就是经过校准的数字值，省去了外部ADC和复杂模拟电路设计的麻烦。其测量范围可配置（通常为±2g, ±4g, ±8g, ±16g），在默认配置下，我们常使用±2g范围以获得最佳分辨率。

2.2 加速度计的物理原理与数据解读

加速度计的基本原理是测量惯性力。以最常见的电容式加速度计（LIS3DHTR即为此类）为例，其内部有一个微小的可动质量块（Proof Mass），通过弹簧结构悬挂。当有加速度时，质量块因惯性会发生位移，导致其与固定电极之间的电容发生变化，通过测量这个电容变化就能换算出加速度值。

Wio Terminal上的LIS3DHTR坐标系定义如下：

• X轴：平行于屏幕的长边，向右为正。
• Y轴：平行于屏幕的短边，向上为正。
• Z轴：垂直于屏幕平面，从屏幕指向使用者为正。

在静止状态下，设备水平放置（屏幕朝上）时，地球重力加速度（约9.8 m/s²，或简化为1g）会完全作用在Z轴上。此时，理想读数应为：X=0g, Y=0g, Z=+1g。如果你将设备竖直放置（像手机一样竖屏），那么重力会主要作用在Y轴上（或X轴，取决于方向）。

传感器输出的原始数据是ADC计数，需要根据量程和分辨率转换为有物理意义的加速度值。以±2g量程、12位分辨率为例，计算公式通常是：加速度(g) = (原始读数 / 灵敏度) * 量程其中灵敏度对于LIS3DHTR在±2g时为4096 counts/g。所以，如果读到的Z轴原始值是4096，那么对应的加速度就是(4096 / 4096) * 2g * (方向)？这里有个常见的误区。实际上，对于数字输出传感器，我们通常直接使用库函数，它会帮我们处理好换算，直接返回以g或m/s²为单位的浮点数。理解这个背景，是为了当数据看起来“不对劲”时，我们能知道从哪里开始排查。

3. 开发环境搭建与核心库选择

工欲善其事，必先利其器。为Wio Terminal编程，目前最主流、体验最好的方式是使用Arduino IDE配合Seeed Studio提供的板卡支持包。下面我会详细拆解每一步，并解释为什么这么选。

3.1 软件环境配置详解

首先，你需要安装Arduino IDE（建议1.8.x稳定版或更新的2.0+版本）。安装完成后，打开“首选项”，在“附加开发板管理器网址”中输入：https://files.seeedstudio.com/arduino/package_seeeduino_boards_index.json这个URL指向Seeed Studio官方维护的板卡支持包索引。添加后，你就可以在“工具”->“开发板”->“开发板管理器”中搜索并安装“Seeed SAMD Boards”。这个包包含了Wio Terminal以及Seeed其他基于SAMD51芯片板子的所有底层支持（编译器工具链、烧录算法、核心库等）。

安装完成后，在“工具”->“开发板”列表中选中“Seeed Wio Terminal”。接下来是关键步骤：选择正确的端口。将Wio Terminal通过Type-C数据线连接到电脑，端口通常会显示为“COMx (Seeed Wio Terminal)”或类似字样。

注意：首次使用时，Wio Terminal可能需要进入“引导加载程序”模式才能被识别为串口设备。方法是：在连接USB的情况下，快速按两次板载的“RST”按键。此时，屏幕会熄灭，电脑会识别出一个新的存储设备（名为“Arduino”），这表示已进入bootloader模式，可以进行程序烧录。之后每次上传代码，IDE会自动控制其复位进入该模式。

3.2 必须安装的库文件

Wio Terminal的强大，很大程度上得益于其丰富的专用库。对于本项目，我们需要两个核心库：

1. Seeed_Arduino_LIS3DHTR：这是ST LIS3DHTR加速度计的官方驱动库。它封装了通过I2C总线与传感器通信的所有底层细节，提供了简洁的API，例如getAccelerationX()等函数来直接获取以g为单位的加速度值。通过Arduino IDE的库管理器（项目->加载库->管理库）搜索“LIS3DHTR”即可安装。

2. TFT_eSPI：这是一个极其强大且高效的TFT屏幕驱动库。Wio Terminal的屏幕控制器是ILI9341，TFT_eSPI库通过高度优化的底层驱动，能充分发挥硬件性能。虽然Seeed也提供了WioTerminal库（封装了TFT_eSPI），但直接使用TFT_eSPI能让我们进行更精细的图形控制。同样通过库管理器搜索安装。

为什么选择TFT_eSPI而不是更简单的WioTerminal内置图形函数？因为TFT_eSPI性能更好，功能更全（支持字体、图形、精灵图等），并且其配置方式让我们能透彻理解屏幕驱动过程。安装后，你需要在你的Arduino库文件夹中找到TFT_eSPI库目录，编辑其中的User_Setup.h文件。你需要注释掉其他屏幕驱动，并确保与Wio Terminal相关的设置被启用。通常，Seeed的板支持包已经提供了预配置的文件，但了解这个步骤对解决未来可能的显示问题至关重要。

4. 从零开始：代码实现与逐行解析

现在，进入最核心的实操环节。我们将编写一个完整的程序，实现加速度计数据的实时读取与动态可视化显示。我会将代码分成几个逻辑模块，并详细解释每一部分的作用和背后的考量。

4.1 初始化与全局定义

#include <Wire.h> #include "LIS3DHTR.h" #include <TFT_eSPI.h> TFT_eSPI tft = TFT_eSPI(); LIS3DHTR<LIS3DHTR_I2C> accelerometer; // 屏幕布局参数 const int SCREEN_WIDTH = 320; const int SCREEN_HEIGHT = 240; const int CENTER_X = SCREEN_WIDTH / 2; const int CENTER_Y = SCREEN_HEIGHT / 2; // 用于存储加速度值的变量 float accX = 0, accY = 0, accZ = 0; // 用于滤波的变量 float filteredAccX = 0, filteredAccY = 0, filteredAccZ = 0; const float ALPHA = 0.1; // 一阶低通滤波系数 // 用于绘制动态指示器的参数 const int GAUGE_RADIUS = 80; const int NEEDLE_LENGTH = 70;

• 头文件与对象：引入必要的库并创建屏幕tft和传感器accelerometer对象。LIS3DHTR<I2C>模板指定使用I2C通信。
• 屏幕参数：定义常量便于后续布局计算，使代码更易读和维护。
• 数据变量：accX/Y/Z存储原始读数，filteredAccX/Y/Z存储经过滤波后的值。这里引入了一个关键概念：滤波。传感器原始数据通常包含高频噪声，直接显示会导致数值跳动剧烈，观感差。我们采用一阶低通滤波（filtered = ALPHA * new + (1-ALPHA) * old），ALPHA越小，滤波效果越强，曲线越平滑，但延迟也越大。0.1是一个在响应速度和平滑度之间不错的折衷。

4.2setup()函数：硬件与显示的启动

void setup() { Serial.begin(115200); while (!Serial); // 等待串口就绪，仅用于调试 // 初始化屏幕 tft.init(); tft.setRotation(3); // 根据你的握持方向调整旋转（0-3） tft.fillScreen(TFT_BLACK); // 初始化加速度计 Wire.begin(); accelerometer.begin(Wire, LIS3DHTR_I2C_ADDRESS); // 默认地址0x19 delay(100); if (!accelerometer) { tft.setTextColor(TFT_RED); tft.drawString("ACCELEROMETER ERROR", CENTER_X, CENTER_Y); while(1); // 停止执行 } accelerometer.setOutputDataRate(LIS3DHTR_DATARATE_100HZ); // 设置数据速率 accelerometer.setFullScaleRange(LIS3DHTR_RANGE_2G); // 设置量程为±2g // 绘制静态UI框架 drawStaticFrame(); }

• 串口初始化：用于调试输出，在实际显示稳定后可注释掉以节省资源。
• 屏幕初始化：tft.init()启动屏幕。tft.setRotation(3)将屏幕旋转270度，使Type-C接口在右侧，这是常见的横屏握持方式。你可以尝试0-3的不同值来适配你的安装方向。
• 加速度计初始化：启动I2C总线，初始化传感器。这里有一个非常重要的错误处理：通过if(!accelerometer)检查传感器是否成功连接。如果失败，在屏幕上显示错误并挂起程序，这能快速定位硬件连接问题（如接触不良、地址错误）。我们还将数据输出率（ODR）设为100Hz，量程设为±2g。更高的ODR意味着更实时的数据，但也会增加功耗和噪声；±2g量程在测量倾斜等应用时提供最佳分辨率。
• 绘制静态框架：将不变的UI元素（如标题、刻度、背景）在setup中一次性绘制，避免在主循环中重复绘制浪费CPU时间。这是优化图形性能的常见技巧。

4.3drawStaticFrame()函数：构建用户界面

void drawStaticFrame() { tft.setTextColor(TFT_WHITE, TFT_BLACK); tft.setTextSize(2); tft.drawString("Wio Terminal Accel Demo", CENTER_X, 10, 2); // 居中显示标题 tft.setTextSize(1); tft.drawString("X:", 30, 60); tft.drawString("Y:", 30, 90); tft.drawString("Z:", 30, 120); // 绘制一个模拟的仪表盘外圈 tft.drawCircle(CENTER_X, 180, GAUGE_RADIUS, TFT_DARKGREY); for (int i = 0; i < 360; i += 30) { float angle = i * PI / 180.0; int x1 = CENTER_X + (GAUGE_RADIUS - 5) * cos(angle); int y1 = 180 + (GAUGE_RADIUS - 5) * sin(angle); int x2 = CENTER_X + GAUGE_RADIUS * cos(angle); int y2 = 180 + GAUGE_RADIUS * sin(angle); tft.drawLine(x1, y1, x2, y2, TFT_WHITE); } tft.drawString("-1g", CENTER_X - GAUGE_RADIUS - 15, 175); tft.drawString("0", CENTER_X, 180 - GAUGE_RADIUS - 15); tft.drawString("+1g", CENTER_X + GAUGE_RADIUS + 5, 175); }

这个函数构建了界面的骨架。我们使用了drawString显示文本，drawCircle和drawLine绘制仪表盘。所有坐标都基于之前定义的常量进行计算，这样修改屏幕布局会非常方便。将UI绘制与数据更新分离，是保持代码清晰和运行高效的关键。

4.4loop()函数：数据采集、处理与动态更新

主循环是程序跳动的心脏，它需要高效地完成四件事：读取数据、处理数据、更新数字显示、更新图形指示。

void loop() { // 1. 读取原始数据 accX = accelerometer.getAccelerationX(); accY = accelerometer.getAccelerationY(); accZ = accelerometer.getAccelerationZ(); // 2. 应用低通滤波 filteredAccX = ALPHA * accX + (1 - ALPHA) * filteredAccX; filteredAccY = ALPHA * accY + (1 - ALPHA) * filteredAccY; filteredAccZ = ALPHA * accZ + (1 - ALPHA) * filteredAccZ; // 3. 更新数字显示区域（避免整屏刷新） updateDigitalReadings(); // 4. 更新模拟仪表盘指针 updateAnalogGauge(); delay(50); // 控制刷新率，约20Hz }

循环中一个关键的优化点是局部刷新。我们不会在每次循环时都用fillScreen(TFT_BLACK)清屏再重绘所有内容，那会产生严重的闪烁。相反，我们只更新那些变化的部分（数字和指针）。delay(50)将刷新率控制在约20帧/秒，这对于人眼观察数据变化已经足够平滑，同时避免了不必要的CPU占用和功耗。

4.5updateDigitalReadings()与updateAnalogGauge()函数

void updateDigitalReadings() { // 用背景色覆盖旧文本，再绘制新文本，实现“原地更新” tft.setTextColor(TFT_BLACK); tft.drawString(String(accX, 2), 60, 60); // 清除旧值 tft.drawString(String(accY, 2), 60, 90); tft.drawString(String(accZ, 2), 60, 120); tft.setTextColor(TFT_CYAN); tft.drawString(String(filteredAccX, 2), 60, 60); // 绘制滤波后的值 tft.drawString(String(filteredAccY, 2), 60, 90); tft.drawString(String(filteredAccZ, 2), 60, 120); } void updateAnalogGauge() { static float oldAngle = 0; // 计算新的指针角度（以X轴为例，映射到-90度到+90度） float newAngle = constrain(filteredAccX, -1.0, 1.0) * 90.0; // 约束在±1g内，映射到±90度 newAngle = newAngle * PI / 180.0; // 转换为弧度 // 计算指针终点坐标 int newX = CENTER_X + NEEDLE_LENGTH * sin(newAngle); int newY = 180 + NEEDLE_LENGTH * cos(newAngle); // 注意：这里cos对应Y轴，因为0度指向正上方 // 用背景色（黑色）擦除旧指针（从圆心到旧终点画一条黑线） tft.drawLine(CENTER_X, 180, CENTER_X + NEEDLE_LENGTH * sin(oldAngle), 180 + NEEDLE_LENGTH * cos(oldAngle), TFT_BLACK); // 绘制新指针（红色） tft.drawLine(CENTER_X, 180, newX, newY, TFT_RED); // 保存当前角度供下次擦除使用 oldAngle = newAngle; }

在updateDigitalReadings中，我们采用了“先涂黑再画新”的技巧实现文本更新，这是在没有“图层”或“控件”概念的底层图形库中常用的方法。String(value, 2)表示将浮点数转换为字符串，保留两位小数。

updateAnalogGauge函数实现了指针的动态效果。其核心逻辑是：

1. 映射：将滤波后的X轴加速度（-1g 到 +1g）线性映射到角度（-90度 到 +90度）。constrain函数确保数值不会超出范围，避免指针“飞出”仪表盘。
2. 坐标计算：利用三角函数（sin,cos）计算指针末端在屏幕上的坐标。注意，因为屏幕坐标系Y轴向下为正，所以角度计算需要根据你的仪表盘朝向进行调整。
3. 擦除重绘：这是实现动态图形的经典“动画”原理。我们保存上一帧指针的位置（oldAngle），在绘制新指针前，用背景色在旧位置画一条完全相同的线，相当于“擦除”它，然后再在新位置画上新颜色的线。这样就实现了指针的平滑移动，没有残留。

5. 效果优化与深度调试技巧

代码跑起来，看到数字和指针动起来，只是第一步。要让这个项目真正具有实用价值和观赏性，还需要一些优化和调试技巧。

5.1 校准与零偏修正

你会发现，即使将Wio Terminal绝对水平静止放置，Z轴读数可能也不是精确的1.000g，X和Y轴也可能有零点几的微小偏移。这不是错误，而是传感器的零偏误差。对于高精度应用，我们需要校准。

一个简单的软件校准方法是：将设备在静止状态下水平放置一段时间，采集数百个X、Y、Z的读数，分别计算它们的平均值offsetX, offsetY, offsetZ。然后，在后续每次读取数据后，都减去这个偏移量：calibratedAccX = rawAccX - offsetX;对于Z轴，因为静止时理论值为1g，所以offsetZ应该是(平均原始Z值 - 1.0)。你可以在setup()函数中增加一个自动校准环节，或者将计算好的偏移量作为常量写入代码。

5.2 高级滤波算法探索

一阶低通滤波简单有效，但有时可能不够。你可以尝试更复杂的滤波器，例如互补滤波或卡尔曼滤波，尤其是当你未来想结合陀螺仪数据做姿态融合时。在Arduino上，一个轻量级的卡尔曼滤波实现可以显著提升数据平滑度，同时比一阶低通滤波更好地处理突变。你可以搜索并引入“SimpleKalmanFilter”等库进行尝试。这会是性能与效果的一次显著提升。

5.3 性能分析与优化

如果你的动画出现卡顿，或者想进一步提高刷新率，可以进行性能分析：

1. 减少绘制操作：确保静态部分只画一次。检查是否有在循环内无意识执行的fillScreen或大量drawString。
2. 使用SPI频率：TFT_eSPI库允许你设置SPI时钟频率。在User_Setup.h中或通过tft.init()后的tft.setSPIClockSpeed提高速度（如到40MHz），可以加速屏幕数据传输。
3. 简化图形：用drawLine代替drawLine的多次调用，用实心图形代替空心图形（如果支持），这些都能减少绘图指令。
4. 测量帧率：在循环中计算并打印每次迭代的时间，可以直观了解程序性能瓶颈。

5.4 扩展思路：从可视化到应用

这个基础项目可以衍生出无数有趣的应用：

• 姿态指示器：用三个仪表盘分别显示X、Y、Z轴，或者用一个3D立方体在屏幕上模拟设备的实时旋转。
• 敲击检测：通过检测加速度的突然剧烈变化（峰值检测），来实现双击唤醒、敲击计数等功能。
• 简单计步器：分析加速度波形，寻找符合步行特征的周期性模式。
• 数据记录仪：将数据写入Wio Terminal的SD卡槽中的MicroSD卡，进行长时间数据采集，然后导入电脑分析。
• 无线传输：利用Wio Terminal的Wi-Fi或蓝牙功能，将实时加速度数据发送到手机App或云端服务器，实现远程监控。

每一次对数据的可视化，都是对物理世界更深一层的理解。Wio Terminal这块小小的屏幕，就像一扇窗，让我们得以窥见那些原本隐藏在电子信号背后的力学奥秘。当你亲手让这些数字和图形随着你的动作而舞动时，那种连接虚拟与现实的成就感，正是嵌入式开发最迷人的地方。