SmartPi流水灯教程：GPIO翻转与PWM渐变详解

版本信息：v1.0 | 更新日期：2026-02-10
适用模组：SU-03T、CI-03T、CI-33T、CI-73T、SU-32T 等支持 GPIO/PWM 输出的 SmartPi 模组
素材来源：技术交流群真实用户提问 + SmartPi 官方文档

前言

流水灯效果几乎是语音交互产品中不可或缺的视觉反馈手段。用户能否第一时间感知设备状态，往往取决于LED的闪烁节奏和流动方向。然而，实际开发中想要实现流畅的流水灯或渐变效果，不少开发者会遇到参数配置、时序协调等方面的卡点。

用户真实提问（智能公元12群，2026-02-07）：
"请问想通过3路PWM实现流水灯效果应该如何设置，我参考了B站上的呼吸灯设置方法但是频率闪烁不对"

官方解答：
"用定时器和IO输出的延时反转功能去试试"

这篇文章会系统梳理 SmartPi 平台上实现流水灯效果的主流方案，从最基本的花样到进阶的渐变控制，覆盖不同阶段开发者的实际需求。

一、流水灯效果概述

1.1 常见流水灯效果类型

1.2 实现方案对比

二、方案一：GPIO 延时电平翻转（基础闪烁）

2.1 适用场景

• 只需基本的亮灭交替效果
• 不需要高精度时序
• 控制1~2个LED

2.2 配置方法

步骤1：GPIO 延时翻转配置

进入智能公元平台的 GPIO 配置页面：

1. 选中要控制的 GPIO 引脚
2. 开启 "延时电平翻转" 开关
3. 设定 "延时时长"（单位：毫秒）

配置示例：
GPIO引脚：A0
初始状态：高电平（点亮LED）
延时时长：500ms（0.5秒后自动翻转）

步骤2：语音命令配置

2.3 工作原理

启动时序：
t=0ms:    GPIO输出高电平 → LED点亮
t=500ms:  延时翻转 → GPIO变低 → LED熄灭
t=1000ms: 延时翻转 → GPIO变高 → LED点亮
...循环往复

2.4 局限性

• 时序精度一般，适合简单闪烁
• 无法驱动多LED流水跑马效果
• 亮度固定不可调

三、方案二：PWM 占空比控制（呼吸灯效果）

3.1 PWM 占空比参数设置

用户常见问题（智能公元16群，2026-02-07）：
"占空比这里要设置2.5ms就写2.5吗？"

关键提醒：PWM 占空比参数必须填写整数，禁止使用小数点。这个细节很容易踩坑——很多人习惯性输入2.5，结果灯根本按预期亮不起来。PWM的本质是把时间切碎来模拟亮度，一旦参数出现小数，控制器直接报错或忽略指令。

占空比计算方法

占空比参数 = (目标时间 / PWM周期) × 100

计算示例：

配置示例：

假设PWM频率100Hz（周期10ms），要实现25%占空比：
1. 目标时间 = 2.5ms
2. PWM周期 = 10ms
3. 占空比参数 = (2.5 / 10) × 100 = 25

3.2 呼吸灯效果配置

方法一：使用多个固定占空比命令

方法二：使用变量动态控制

1. 定义亮度变量：

   • 变量名：brightness
   • 类型：int
   • 默认值：50

2. PWM 配置：

   • PWM输出引脚：选择支持PWM的GPIO
   • 占空比变量：brightness

3. 语音命令：

   • "变亮一点" → brightness = brightness + 10
   • "变暗一点" → brightness = brightness - 10

3.3 不同模组的 PWM 资源

四、方案三：定时器 + GPIO（流水跑马灯）

4.1 适用场景

• 需要多个 LED 依次点亮的跑马效果
• 要求每个 LED 点亮时长准确
• 实现典型流水灯效果

4.2 配置步骤

步骤1：定义定时器

在"定时器"配置页面：

• 定时器名称：led_timer
• 定时器时长：200ms（每个LED点亮时长）
• 定时器模式：重复触发

步骤2：定义变量

变量名：led_index
类型：int
默认值：0
说明：记录当前点亮的LED编号（0-2，共3个LED）

步骤3：配置定时器超时动作

触发方式：定时器超时
关联定时器：led_timer

控制动作：

1. 关闭所有LED（GPIO A0/A1/A2 输出低电平）
2. 根据led_index点亮对应LED：
   - led_index=0 → GPIO A0输出高电平
   - led_index=1 → GPIO A1输出高电平
   - led_index=2 → GPIO A2输出高电平
3. led_index自增：
   - led_index = (led_index + 1) % 3
4. 重新启动定时器

步骤4：语音控制

4.3 工作流程

上电/启动 → [A0亮] → 200ms → [A1亮] → 200ms → [A2亮] → 200ms → [A0亮] → 循环...

4.4 实际配置代码示例

// 定时器超时事件处理
void on_led_timer_expired() {
    // 步骤1：关闭所有LED
    set_gpio(A0, LOW);
    set_gpio(A1, LOW);
    set_gpio(A2, LOW);

    // 步骤2：根据索引点亮对应LED
    switch(led_index) {
        case 0: set_gpio(A0, HIGH); break;
        case 1: set_gpio(A1, HIGH); break;
        case 2: set_gpio(A2, HIGH); break;
    }

    // 步骤3：更新索引（循环）
    led_index = (led_index + 1) % 3;

    // 步骤4：重新启动定时器
    start_timer("led_timer", 200);
}

五、方案四：软件模拟 PWM（渐变效果）

5.1 适用场景

• 硬件 PWM 通道不够用
• 希望实现平滑无极渐变
• 时序精度要求不太苛刻

5.2 实现原理

通过快速切换 GPIO 的高低电平来模拟 PWM 效果：

渐变升亮过程：
t=0:    [亮1ms, 灭9ms]  → 10%亮度
t=100ms: [亮2ms, 灭8ms]  → 20%亮度
t=200ms: [亮3ms, 灭7ms]  → 30%亮度
...
t=900ms: [亮10ms, 灭0ms] → 100%亮度

5.3 配置方法

方法：使用定时器 + GPIO 延时翻转

1. 创建渐变定时器：

   • 名称：fade_timer
   • 时长：100ms（渐变步进时间）
   • 模式：重复触发

2. 定义渐变变量：

   • fade_level：当前亮度等级（0-10）
   • fade_direction：渐变方向（0=变亮，1=变暗）
3. 定时器超时动作：

void on_fade_timer_expired() {
    // 根据方向调整亮度等级
    if (fade_direction == 0) {
        fade_level++;
        if (fade_level >= 10) fade_direction = 1;
    } else {
        fade_level--;
        if (fade_level <= 0) fade_direction = 0;
    }

    // 根据亮度等级设置延时翻转时长
    // 亮度越高，高电平保持时间越长
    int high_time = fade_level * 10;  // 0-100ms
    int low_time = 100 - high_time;   // 100-0ms

    // 输出高电平
    set_gpio(LED_PIN, HIGH);
    delay_ms(high_time);

    // 输出低电平
    set_gpio(LED_PIN, LOW);
    delay_ms(low_time);

    // 继续定时器
    start_timer("fade_timer", 100);
}

六、3路 PWM 流水灯完整方案

针对用户问题："通过3路PWM实现流水灯效果"

6.1 问题分析

用户提到"参考了B站上的呼吸灯设置方法但是频率闪烁不对"，这通常是因为：

1. PWM 频率设置不合理
2. 多路 PWM 间缺少时序配合
3. 混淆了占空比与频率的用法

6.2 推荐方案：定时器 + PWM 渐变

步骤1：配置 3 路 PWM

步骤2：定义变量

变量名：pwm_index
类型：int
默认值：0
说明：当前激活的PWM通道（0-2）

步骤3：配置流水定时器

• 定时器名称：flow_timer
• 定时器时长：1000ms（每个LED渐变时长）
• 定时器模式：重复触发

步骤4：定时器超时逻辑

// 流水灯定时器处理
void on_flow_timer_expired() {
    // 步骤1：将当前PWM渐变到0（淡出）
    set_pwm_duty(pwm_index, 0);

    // 步骤2：切换到下一个PWM
    pwm_index = (pwm_index + 1) % 3;

    // 步骤3：将新PWM渐变到100（淡入）
    set_pwm_duty(pwm_index, 100);

    // 步骤4：继续定时器
    start_timer("flow_timer", 1000);
}

6.3 硬件连接

SmartPi 模组         LED电路
GPIO A0 (PWM0)  →    LED1 + 限流电阻 → GND
GPIO A1 (PWM1)  →    LED2 + 限流电阻 → GND
GPIO A2 (PWM2)  →    LED3 + 限流电阻 → GND

限流电阻计算：

假设：
- Vcc = 3.3V
- LED正向压降 Vf = 2.0V
- LED电流 If = 10mA

电阻值 = (3.3V - 2.0V) / 0.01A = 130Ω
推荐使用：150Ω 或 220Ω

七、常见问题与解决方案

7.1 PWM 频率闪烁问题

问题："参考了呼吸灯设置方法但是频率闪烁不对"

之所以出现"闪烁不对"，多半是下面几个参数没调对。最典型的坑有三个：

推荐 PWM 频率：

7.2 定时器资源不足

问题：需要多个定时器但模组资源有限

解决方案：

1. 合并相似功能：

   • 使用一个定时器控制多个相关的动作
   • 在定时器回调中依次处理

2. 使用变量替代部分定时器：

   • 用变量记录状态
   • 定时器轮询检查状态变化

3. 模组定时器限制：

   • CI-03T系列：最多5个定时器
   • SU-03T：支持定时器功能
   • 更高端模组：更多定时器资源

7.3 GPIO 驱动能力问题

注意：SmartPi 模组的 GPIO 直接驱动 LED 能力有限，建议：

推荐驱动方式：
GPIO → 限流电阻(220Ω-1kΩ) → LED → GND

高亮LED驱动：
GPIO → 三极管/MOSFET → LED → 电源

八、配置检查清单

完成流水灯配置后，用下面这个清单逐项核对，能省去大量排错时间：

硬件连接

• [ ] LED 极性正确（长脚为正）
• [ ] 限流电阻已连接
• [ ] GPIO 引脚分配正确
• [ ] 共地连接

参数配置

• [ ] PWM 占空比使用整数
• [ ] PWM 频率适合应用场景
• [ ] 定时器时长符合预期
• [ ] 变量初始值正确

功能验证

• [ ] 单个 LED 能正常点亮
• [ ] PWM 调光效果平滑
• [ ] 流水切换顺序正确
• [ ] 语音控制响应正常

九、总结

方案选择建议

关键要点

1. PWM 占空比必须用整数：根据频率和周期计算正确值
2. 多LED流水效果需要定时器：用定时器控制切换时序
3. 注意模组资源限制：PWM 和定时器数量有限，合理规划
4. 验证硬件连接：LED 极性和限流电阻是常见问题点

参考资料

• SmartPi 官方文档 - GPIO控制配置
• SmartPi 官方文档 - 定时器配置
• SmartPi 官方视频 - SU-03T定时器应用案例

关键词：流水灯、呼吸灯、PWM、占空比、定时器、GPIO翻转、LED控制、渐变效果、SmartPi、SU-03T、CI-03T

最后更新：2026-02-10 v1.0

数据来源说明：

• 用户真实提问：智能公元12群（2026-02-07）流水灯效果问题
• 用户真实提问：智能公元16群（2026-02-07）PWM占空比参数设置问题
• SmartPi官方文档：GPIO控制、定时器配置、PWM设置