版本信息 ：v1.0 | 更新日期 ：2026-02-10
适用模组 ：SU-03T、CI-03T、CI-33T、CI-73T、SU-32T 等支持 GPIO/PWM 输出的 SmartPi 模组
素材来源：技术交流群真实用户提问 + SmartPi 官方文档
前言
流水灯效果是语音交互产品中常用的视觉反馈方式，能够让用户直观地感受到设备的工作状态。然而，许多开发者在尝试实现流水灯或渐变效果时会遇到各种问题。
用户真实提问 （智能公元12群，2026-02-07）：
"请问想通过3路PWM实现流水灯效果应该如何设置，我参考了B站上的呼吸灯设置方法但是频率闪烁不对"
官方解答 ："用定时器和IO输出的延时反转功能去试试"
本文将系统讲解在 SmartPi 平台上实现流水灯效果的多种方案，包括基础的 GPIO 翻转、PWM 调光、定时器控制等，帮助开发者选择最适合自己项目的方案。
一、流水灯效果概述
1.1 常见流水灯效果类型
| 效果类型 | 视觉表现 | 技术难度 | 典型应用 |
|---|---|---|---|
| 开关闪烁 | LED 亮灭交替 | ★☆☆ | 状态指示、报警提示 |
| 渐变呼吸 | 亮度缓慢变化 | ★★☆ | 等待提示、氛围灯 |
| 流水跑马 | 多个LED依次点亮 | ★★★ | 装饰灯、展示效果 |
| 彩虹渐变 | RGB颜色渐变 | ★★★ | 氛围灯、彩灯 |
1.2 实现方案对比
| 方案 | 硬件要求 | PWM数量 | 定时器 | 效果质量 |
|---|---|---|---|---|
| GPIO延时翻转 | 仅需GPIO | 不需要 | 可选 | 基础闪烁 |
| PWM占空比控制 | 支持PWM的GPIO | 需要 | 可选 | 亮度可调 |
| 定时器+GPIO | 仅需GPIO | 不需要 | 必须 | 精确时序 |
| 软件模拟PWM | 仅需GPIO | 不需要 | 必须 | 渐变效果 |
二、方案一：GPIO 延时电平翻转（基础闪烁）
2.1 适用场景
- 需要简单的亮灭交替效果
- 对时序精度要求不高
- LED数量较少（1-2个）
2.2 配置方法
步骤1：GPIO 延时翻转配置
在智能公元平台的 GPIO 配置页面：
-
选择需要控制的 GPIO 引脚
-
开启 "延时电平翻转" 开关
-
设置 "延时时长"（单位：毫秒）
配置示例：
GPIO引脚：A0
初始状态：高电平（点亮LED）
延时时长：500ms（0.5秒后自动翻转）
步骤2：语音命令配置
| 命令词 | 执行动作 |
|---|---|
| "开始闪烁" | GPIO A0 输出高电平 |
| "停止闪烁" | GPIO A0 输出低电平 |
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 占空比参数必须填写整数，不能使用小数点。
占空比计算方法
占空比参数 = (目标时间 / PWM周期) × 100计算示例：
| 目标占空比时间 | PWM频率 | PWM周期 | 占空比参数 |
|---|---|---|---|
| 2.5ms | 100Hz (10ms周期) | 10ms | 25 |
| 5.0ms | 100Hz (10ms周期) | 10ms | 50 |
| 1.0ms | 1kHz (1ms周期) | 1ms | 100 |
配置示例：
假设PWM频率100Hz（周期10ms），要实现25%占空比：
1. 目标时间 = 2.5ms
2. PWM周期 = 10ms
3. 占空比参数 = (2.5 / 10) × 100 = 253.2 呼吸灯效果配置
方法一：使用多个固定占空比命令
| 命令词 | PWM占空比 | 效果 |
|---|---|---|
| "最亮" | 100 | 全亮 |
| "较亮" | 75 | 75%亮度 |
| "中等" | 50 | 50%亮度 |
| "较暗" | 25 | 25%亮度 |
| "最暗" | 10 | 10%亮度 |
方法二：使用变量动态控制
-
定义亮度变量：
- 变量名：
brightness - 类型：
int - 默认值：
50
- 变量名：
-
PWM 配置：
- PWM输出引脚：选择支持PWM的GPIO
- 占空比变量：
brightness
-
语音命令：
- "变亮一点" →
brightness = brightness + 10 - "变暗一点" →
brightness = brightness - 10
- "变亮一点" →
3.3 不同模组的 PWM 资源
| 模组型号 | PWM数量 | PWM引脚 | 说明 |
|---|---|---|---|
| SU-03T | 2路 | 可配置引脚 | 基础款 |
| CI-03T | 4路 | 可配置引脚 | 标准款 |
| CI-33T | 4路 | 可配置引脚 | 双麦克风款 |
| CI-73T | 多路 | 可配置引脚 | 高性价比 |
| SU-32T | 多路 | 可配置引脚 | 双麦降噪款 |
四、方案三：定时器 + 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：语音控制
| 命令词 | 执行动作 |
|---|---|
| "开始流水灯" | led_index=0，启动定时器 |
| "停止流水灯" | 停止定时器，关闭所有LED |
4.3 工作流程
上电/启动 → [A0亮] → 200ms → [A1亮] → 200ms → [A2亮] → 200ms → [A0亮] → 循环...4.4 实际配置代码示例
c
// 定时器超时事件处理
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 延时翻转
-
创建渐变定时器：
- 名称：
fade_timer - 时长：
100ms（渐变步进时间） - 模式：重复触发
- 名称：
-
定义渐变变量：
fade_level：当前亮度等级（0-10）fade_direction：渐变方向（0=变亮，1=变暗）
-
定时器超时动作：
c
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站上的呼吸灯设置方法但是频率闪烁不对"，这通常是因为：
- PWM 频率设置不当
- 多路 PWM 没有正确的时序配合
- 混淆了占空比和频率的概念
6.2 推荐方案：定时器 + PWM 渐变
步骤1：配置 3 路 PWM
| PWM通道 | GPIO引脚 | 初始占空比 |
|---|---|---|
| PWM0 | A0 | 0（关闭） |
| PWM1 | A1 | 0（关闭） |
| PWM2 | A2 | 0（关闭） |
步骤2：定义变量
变量名：pwm_index
类型：int
默认值：0
说明：当前激活的PWM通道（0-2）步骤3：配置流水定时器
- 定时器名称：
flow_timer - 定时器时长：
1000ms（每个LED渐变时长） - 定时器模式：重复触发
步骤4：定时器超时逻辑
c
// 流水灯定时器处理
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频率过低 | 将频率提高到50Hz以上 |
| 占空比设置错误 | 使用整数，参考计算公式 |
| 多路PWM时序冲突 | 使用定时器同步控制 |
推荐 PWM 频率：
| 应用场景 | 推荐频率 |
|---|---|
| LED闪烁 | 50-100Hz |
| 呼吸灯效果 | 100-200Hz |
| 舵机控制 | 50Hz |
| 电机调速 | 10-20kHz |
7.2 定时器资源不足
问题：需要多个定时器但模组资源有限
解决方案：
-
合并相似功能：
- 使用一个定时器控制多个相关的动作
- 在定时器回调中依次处理
-
使用变量替代部分定时器：
- 用变量记录状态
- 定时器轮询检查状态变化
-
模组定时器限制：
- 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 调光效果平滑
- 流水切换顺序正确
- 语音控制响应正常
九、总结
方案选择建议
| 需求 | 推荐方案 | 复杂度 |
|---|---|---|
| 简单闪烁 | GPIO延时翻转 | ★☆☆ |
| 亮度调节 | PWM占空比 | ★★☆ |
| 流水跑马 | 定时器+GPIO/PWM | ★★★ |
| 平滑渐变 | 软件模拟PWM | ★★★ |
关键要点
- PWM 占空比必须用整数：根据频率和周期计算正确值
- 多LED流水效果需要定时器：用定时器控制切换时序
- 注意模组资源限制：PWM 和定时器数量有限，合理规划
- 验证硬件连接：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设置