杰理平台time PWM实战：定时器比较输出的配置与踩坑指南

前阵子帮朋友调一块杰理平台的小板子，现象很蹊跷：按键控制LED亮度时，IO口确实有电平变化，但用示波器一看，波形完全不是PWM该有的样子，反而是一串不规则的脉冲，频率还飘。翻遍SDK里的例程，也没找到名字里带"time PWM"的现成demo。后来才搞清楚，在杰理这套体系里，time PWM并不是一个独立外设模块的官方名称，而是定时器与PWM输出协同工作的一种玩法，或者说是一种应用层习惯叫法。这篇就把我折腾下来的理解、配置思路、计算方法和踩过的坑整理出来，给后面接手杰理方案的兄弟一个参考。

这篇文章适合谁看？手头有杰理平台芯片、正在做LED调光、蜂鸣器音调、小电机调速、加热控制这类需要低成本PWM输出的开发者。哪怕你之前没用过杰理，只要对定时器、PWM这些基础概念有印象，也能顺着这篇文章把思路迁移过去。重点不是背参数，而是搞清楚"为什么这么配、为什么那么算、出了问题先查哪里"。

1. 为什么很少有人把time PWM当回事

1.1 我以为它在手册里写着，结果SDK里根本找不到这个名词

我一开始是奔着"time PWM"这个关键词去查资料的，结果芯片手册里没有专门一章叫这个名字，SDK例程里也没有。折腾一圈才明白，杰理平台里PWM相关的功能分散在几个地方：有独立的PWM外设驱动，有定时器中断翻转IO的软件PWM，再就是利用定时器的比较输出功能直接产生硬件PWM。大家口口相传的"time PWM"，多半指的是第三种，也就是定时器比较输出映射到指定引脚，由硬件自动翻转电平，不需要CPU在中断里频繁改IO。

理解这点非常重要，因为很多人被这个名字误导，拿着"time PWM"去搜，搜不到就开始怀疑自己拿的SDK不对。实际上你只要找定时器（Timer）模块的配置接口，再看有没有比较输出（Compare Output）或者PWM映射相关的枚举定义，基本就能对上号。

1.2 杰理平台上timer PWM到底是定时器还是PWM模块

从硬件结构上说，定时器负责计数和比较，PWM信号是定时器比较事件的"副产品"。定时器从0计数到设定的周期值，每计满一轮就溢出重新开始；在计数的过程中，如果计数值到达了我们设定的比较点，输出引脚的电平就会翻转。于是引脚上就产生了固定频率、固定占空比的方波，这就是PWM。

独立PWM模块和定时器比较输出的最大区别在于：独立PWM通常自带多路通道、死区控制、紧急刹车这些外设级功能，适合电机驱动；而定时器比较输出更多是"借用"通用定时器的能力，胜在引脚选择灵活、和定时中断能共用一套时间基准。在杰理这种以低成本、小封装见长的平台上，为了省资源，很多PWM需求就是用定时器比较输出实现的。

1.3 什么场景必须用它

我自己遇到过的典型场景有三个：

• LED亮度调节，要求调光过程平滑、频率高于人眼闪烁阈值，比如1kHz到20kHz之间；
• 无源蜂鸣器发声，需要输出固定频率方波驱动蜂鸣器响出不同音调；
• 小功率加热丝控制，用低频PWM控制平均功率，频率不高但占空比精度要有保证。

这三个场景的共同特点是：不要求极高的PWM性能指标、不需要多路高精度同步、但要求开发简单、资源占用少。如果用独立PWM模块当然也行，但引脚可能不够灵活，或者通道数不够用。定时器比较输出方案这时候就很有优势，一个通用定时器既能开中断做周期性任务，又能同时输出一路PWM，一鱼两吃。

2. 动手之前先把时钟、定时器、引脚映射这三件事盘清楚

2.1 时钟树是源头：PWM频率不是凭空来的

杰理芯片和大多数MCU一样，所有外设的时钟都来源于系统时钟的一路分频。你看到的PWM频率，本质上是外设时钟经过定时器预分频、再经过周期寄存器分频之后的结果。任何一个环节没配好，输出频率都会偏离预期。

我习惯在配置PWM之前，先去SDK的时钟配置文件里看一眼外设时钟是多少。很多杰理项目的系统时钟是24MHz或者48MHz，但不同型号、不同配置下PWM模块挂在哪个总线、是否开启时钟门控，都有差异。这个值搞错了，后面算出来的分频系数全部作废。

2.2 定时器的预分频、自动重载和比较寄存器

不管什么型号的MCU，定时器做PWM输出都离不开三个寄存器：

在杰理SDK里，这些寄存器通常会被封装成结构体或者初始化参数。比如周期值放在一个名为"period"的字段里，比较值放在"duty"或者"compare"字段里。你不需要手算每个寄存器位，但必须理解这三个值的含义，否则调出来的波形就是乱的。

2.3 引脚复用才是大多数人卡住的地方

定时器比较输出的信号要跑到芯片引脚上，中间还隔着一道"闸门"，就是引脚复用功能。很多第一次用杰理的人在这里翻车：定时器配置完全正确，软件上PWM也启动了，但量引脚就是没有波形，多半就是引脚复用没切换。

在杰理SDK中，GPIO复用通常通过一个类似gpio_set_function或者io_configure的接口配置。你需要找到当前芯片型号的引脚功能映射表，确认哪几个引脚能映射到哪个定时器通道。不同的封装型号，可用的映射引脚还不一样。比如同样是Timer2的PWM输出，某个型号可能只能映射到PA3，另一个型号可能能映射到PB1。这个只能查芯片手册里的"引脚复用表"，没有捷径。

提示：如果你用的是一块现成的开发板，最好先看板子的原理图，确认目标引脚的丝印名称和芯片引脚编号，再反查复用表。直接照着网上的例程抄引脚号，很容易因为封装不同而翻车。

3. SDK里落地的两种写法：外设接口封装和寄存器直操作

3.1 用SDK封装接口：先跑通例程再改参数

杰理SDK里大部分功能都有对应的外设驱动模块，你可以在工程目录下找到类似timer或pwm的驱动文件。稳妥的做法是：先找到一个能编译通过的例程，确认例程里的初始化流程，然后再改成自己需要的频率和占空比。

一个典型的初始化流程大致长这样（接口名以你实际SDK版本为准，但顺序和思路是通用的）：

// 伪代码，用于说明配置流程，具体函数名以杰理SDK实际接口为准 void time_pwm_demo_init(u16 freq_khz, u8 duty_percent) { // 1. 开启定时器和PWM相关外设时钟 system_set_clock_enable(TIMER_DEV, TRUE); system_set_clock_enable(PWM_IO_DEV, TRUE); // 2. 配置引脚复用，把定时器比较输出映射到目标引脚 gpio_set_function(TIMER_PWM_PIN, GPIO_FUNC_TIMER_PWM); // 3. 初始化定时器参数 timer_cfg_t cfg; cfg.period = timer_calc_period(freq_khz); // 根据目标频率计算周期值 cfg.compare = timer_calc_compare(cfg.period, duty_percent); // 根据占空比计算比较值 cfg.interrupt_enable = FALSE; // 纯PWM输出时可以不开中断 timer_init(TIMER_INDEX, &cfg); // 4. 启动PWM比较输出 timer_pwm_start(TIMER_INDEX); }

这里要注意一点：很多例程里会把"定时器中断翻转IO"和"定时器比较输出PWM"混在一起演示。如果你看到中断服务函数里有手动翻转IO的代码，那说明这个例程用的是软件PWM，不是硬件PWM。真正的硬件PWM，启动之后CPU完全不干预，引脚自己翻转波形，中断服务函数应该是空的或者不使能。

3.2 寄存器直操作：适合老工程师和喜欢抠细节的人

SDK封装虽然方便，但遇到两个场景你还是得去看寄存器：一是SDK版本太老、封装接口不全；二是你需要精细控制某些特殊行为，比如修改占空比时要不要同步更新。

寄存器直操作的思路就是：找到定时器的控制寄存器、预分频寄存器、周期寄存器、比较寄存器，把相应的位域填进去。不同型号的寄存器布局差异很大，我这里不能直接给你一个通用地址，但可以给一个操作模板：

// 伪代码，寄存器名和位域以具体芯片手册为准 void time_pwm_reg_demo(u32 clk_hz, u32 freq_hz, u8 duty_percent) { u32 divider = clk_hz / freq_hz; u32 period = divider - 1; u32 compare = period * duty_percent / 100; u32 reg_val = 0; // 关闭定时器，进入可配置状态 TIMER_CTRL_REG &= ~TIMER_EN; // 配置预分频，让计数时钟进入合适范围 reg_val = TIMER_CTRL_REG; reg_val &= ~TIMER_PRESCALER_MASK; reg_val |= (PRESCALER_VALUE << TIMER_PRESCALER_POS); TIMER_CTRL_REG = reg_val; // 写周期值和比较值 TIMER_PERIOD_REG = period; TIMER_COMPARE_REG = compare; // 选择PWM输出模式并启动 TIMER_MODE_REG |= TIMER_MODE_PWM; TIMER_CTRL_REG |= TIMER_EN; }

这种写法适合你已经读懂了数据手册、并且清楚当前芯片不会因为寄存器被误写而进入异常状态的情况。如果是产品初期，我建议还是先走SDK接口，等真正需要压榨资源的时候再降级到寄存器操作。

3.3 改占空比的时候要不要先停PWM

这是一个很实际的问题。占空比在运行过程中需要动态调整的场景太常见了——LED呼吸灯、电机调速、加热功率调节，都要在运行时改比较值。

关键点在于：如果你直接写比较寄存器，而定时器还在高速计数，那么新值可能会在下一个计数周期才生效，也可能立即生效，取决于芯片的设计。有些芯片会在计数到周期值溢出时自动加载新比较值，这样改起来很平滑；有些芯片则会在写入瞬间马上改变输出状态，导致半个周期出现异常波形。

稳妥的做法是：先把PWM输出关闭，写入新的周期值和比较值，再重新启动。代价是会有一个极短的时间窗口没有输出，但对LED调光、蜂鸣器变调来说完全感受不到。如果你追求无缝切换，那就查一下SDK里是否有"影子寄存器"或者"缓冲加载"的机制，有的话用缓冲加载，没有的话就老实先停再写。

注意：对于蜂鸣器发声，如果突然停止PWM再启动，中间那个小缺口会变成一个"咔哒"声。要避免这个声音，可以考虑在定时器中断里、恰好计数到0的那一瞬间更新比较值，让切换点落在波形周期的边界上。这个技巧我在后面"实测踩坑"里会再提到。

4. 频率和占空比的计算：先列公式再填表，基本不会错

4.1 一条公式把所有参数串起来

PWM输出频率和占空比的底层公式其实非常简单：

• PWM频率 = 外设时钟频率 / ((预分频系数 + 1) * (周期值 + 1))
• 占空比 = 比较值 / (周期值 + 1)

注意这里有个很容易忽略的"+1"：很多定时器的计数范围是从0开始到寄存器的值为止，所以实际计数的次数是"寄存器值 + 1"。如果你直接把目标频率除以外设时钟、忘了加一，算出来的实际频率会有一点偏差。精度要求不高时无所谓，但如果要用PWM做载频驱动蜂鸣器，偏了100Hz人耳都能听出来。

举个例子。假设外设时钟是24MHz，我想要20kHz的PWM频率做蜂鸣器驱动：

目标频率 = 24000000 / ((预分频 + 1) * (周期 + 1)) = 20000

如果预分频系数选0，也就是不做分频，那周期值 + 1 = 1200，周期值就是1199。占空比50%的话，比较值就是600。配置后实际频率就是：

24000000 / (1 * 1200) = 20000Hz

完美命中。

4.2 三个典型场景的算表

很多时候大家不知道怎么选预分频系数。原则很粗暴：先让"外设时钟 / 目标频率"得到一个总的分频比，然后把这个总分频比拆成"预分频"和"周期值"两部分。预分频用来保证周期值不溢出，周期值越大，占空比分辨率越高。

我整理了几个常用场景，时钟统一按24MHz算：

从表里能看出，只要总计数需求不超过定时器的位数上限，预分频保持0就能得到最大占空比分辨率。只有当目标频率低到周期值溢出时，才需要加大预分频。比如一个16位定时器，周期值最大65535，如果你需要10Hz的PWM信号，24MHz时钟下总计数需求是2400000，远超65535，这时就必须加大预分频。

4.3 动态调整频率时怎么避免"霹雳啪啦"的杂音

动态调频率比调占空比更麻烦，因为在改周期值的那一刻，输出波形可能不完整。比如上一秒是20kHz，下一秒你要改成15kHz，如果直接在运行中改了周期值，当前这个周期的长度就可能变成"新周期"的长度，给人一种卡了一拍的感觉。

我试过几种方案，最省心的是：

1. 先停止PWM输出；
2. 写新的周期值和比较值；
3. 重新启动PWM输出；
4. 对于音频提示音类应用，把切换动作放在定时器中断里同步执行。

在杰理平台上做蜂鸣器变调提示音时，我会把"当前音符的频率"作为全局变量，定时器中断里检测到这个变量变化，就重新算周期值和比较值，然后趁着计数溢出瞬间写入寄存器。这样做出来的变调非常干净，不会有杂音。

5. 实测踩坑记录：从"没波形"到"复位死循环"的完整排查

5.1 症状一：引脚上量不到任何电平变化

这是我遇到最多的一个问题，也是排查步骤最固定的一个问题。我建议按照下面的链路走一遍：

1. 先用万用表量引脚电平，确认不是悬空或者被外部电路拉死；
2. 检查GPIO复用配置，确认引脚功能确实切到了定时器PWM输出通道，这一步可以直接读寄存器确认；
3. 检查PWM对应的外设时钟有没有开，很多SDK里外设默认是关时钟的，没开时钟会表现为配置寄存器写进去没反应；
4. 检查周期寄存器是否为0或者异常值，如果周期值是0，计数永远不会溢出，也就不会产生PWM输出。

按照这个顺序排查，绝大多数"没波形"的问题在第二步就被揪出来了。我之前有一次就是复用函数里传错了通道号，看起来配置了，实际上配到了另一组引脚上。

5.2 症状二：波形频率是预期的两倍或者乱码

波形频率是预期两倍，大概率是引脚复用到了两个不同的定时器通道，或者PWM输出模式配置成了"翻转模式"而不是"PWM模式"。定时器比较输出通常有两种模式：一种是比较匹配时输出高、溢出时输出低；另一种是比较匹配时翻转电平。如果你配置成了翻转模式，那么一个完整PWM周期里电平要翻转两次，信号频率就是预期频率的两倍。

乱码则多半是周期值越界了。比如目标频率很低、你算出来的周期值超过了定时器的最大位宽，高位被丢弃，计数器每次数到一半就溢出，波形自然一塌糊涂。这种情况在基础频率选太高、又需要低频输出时特别容易发生。

5.3 症状三：系统跑到一半卡死或反复复位

这个坑最隐蔽。我在一次做LED调光实验时，开了PWM输出之后系统正常跑，但只要一触发定时器中断，整机就复位。排查了半天，发现是中断服务函数里访问了外设寄存器，而这个外设的时钟在低功耗模式下被关了，读寄存器直接触发总线错误。

另一种常见卡死原因是中断优先级问题。如果定时器中断优先级设置得和系统调度器中断一样高，或者中断服务函数里做了延时等待，就会导致系统任务切换被卡死。如果你只是需要PWM输出而不需要在中断里做事情，最干脆的方法就是把中断使能关掉，让PWM完全由硬件跑，CPU不参与。

我把三个症状的原因和解决方式汇总一下：

6. 进阶玩法：呼吸灯、互补输出、低功耗下的小心机

6.1 呼吸灯：占空比按指数曲线走，别用线性

用PWM做呼吸灯，很多新手会直接用线性递增的占空比，从0每隔几毫秒加1一直到100，再从100减到0。看起来简单，实际上眼睛看着很生硬——因为人对亮度的感知不是线性的，而是近似对数的。同样的占空比变化量，在低亮度区域人眼感觉很敏感，在高亮度区域几乎看不出变化。

正确的做法是准备一张指数表，让占空比按指数曲线的规律变化。比如把0到255的索引值映射成1%到100%的占空比：

// 伪代码：生成指数调光表，避免呼吸灯忽快忽慢 static u8 exp_table[256]; void build_exp_table(void) { for (int i = 0; i < 256; i++) { float v = (float)i / 255.0f; // 指数映射，v^2.2 是一种常见近似 float duty = v * v * 1.2f; if (duty > 1.0f) duty = 1.0f; exp_table[i] = (u8)(duty * 255.0f); } }

在定时器中断里，每次只改一个表索引值，占空比直接查表更新。配合杰理平台的低功耗定时唤醒，呼吸灯效果能做到很丝滑，而且CPU占用率极低。

6.2 互补PWM和死区：驱动半桥前先想想直通的事

如果你用杰理这颗芯片去驱动小电机、继电器或者半桥电路，可能需要两路相位相反的PWM信号。这时注意一个致命问题：上下管切换的瞬间，如果一路还没完全关断、另一路就导通了，会形成直通短路。

解决手段是加死区时间。杰理部分型号的定时器PWM输出支持死区配置，你可以在初始化参数里找到dead_zone或者dead_time字段，单位通常是定时器时钟的周期数。死区时间太长会降低有效占空比，太短则起不到保护作用。对于普通小功率MOS管驱动，微秒级别的死区一般够用；具体数值根据你的功率管开关时间和负载特性来调。

如果没有硬件死区功能，那就在软件层面保证：先关掉全部输出，延时几个微秒，再开启互补的那一路。

6.3 睡眠前后把PWM外围处理干净

低功耗是杰理芯片的强项，很多产品要求待机电流做到微安级别。但如果你在睡眠前不处理PWM输出，系统可能根本睡不下去，或者在睡眠状态下引脚持续输出高电平，白白耗电。

我的习惯是在进入睡眠前做三件事：

1. 关闭PWM输出，让引脚恢复成普通GPIO，并且配置成输入模式，避免引脚对外驱动电流；
2. 关闭定时器外设时钟，让定时器停止计数；
3. 把相关中断标志位清干净，防止一唤醒就误入中断。

唤醒之后，再按照初始化的流程重新配置一遍即可。这里强调一下：不要图省事直接复位外设寄存器，因为杰理不同型号的复位行为差异比较大，有些外设复位后寄存器值不可预测，重新走一遍完整初始化反而更可靠。

6.4 一个小技巧：用定时器联动实现无CPU干预的变频音调

最后分享一个从老工程师那里学来的技巧。无源蜂鸣器发声时，如果希望发出"滴滴-滴-滴滴"这种不同音调组合，常规做法是CPU频繁改频率，占用较高。其实可以这样：把PWM频率设置成两种频率中的一个，然后用另一个定时器在特定时间后触发中断，在中断里切换PWM参数。这样高频的PWM波形完全由硬件维持，CPU只需要在音符切换点醒一次。

实测下来，同样的功能用纯软件实现大概要占用不少CPU资源，用这个方案后整机跑起来流畅很多。这种"硬件干苦力、软件只在边界出现"的思路，在低成本MCU平台上非常值得推广。

回头再看这次调试经历，最大的感悟是：很多所谓"找不到的功能"，其实只是名字没对上。time PWM没有单独的教程、单独的寄存器，它就藏在定时器的比较输出能力里。先把硬件的信号链路走通，再回头理解SDK的接口设计，你会觉得一切都顺理成章。这也是我一直建议新手别急着抄代码、先拿示波器看波形的原因——波形永远不会骗你。