跳至主要內容

Pwm模块用户手册

大约 9 分钟约 2705 字2025/12/26

Pwm模块用户手册

目录

1. 简介

本PWM驱动模块提供了对 CCP (通用型捕捉/比较/脉宽调制模块) 和 EPWM (增强型脉宽调制模块) 的抽象接口，旨在简化PWM信号的生成和控制。

主要功能包括：

  • 初始化与反初始化: 通过 HLI_Pwm_Init 和 HLI_Pwm_DeInit 对一个或多个PWM模块进行配置和资源释放。
  • 周期与占空比控制: 允许在运行时通过 HLI_Pwm_SetPeriodAndDuty、HLI_Pwm_SetDutyCycle 和 HLI_Pwm_SetDutyCyclePercent 等函数动态调整PWM的周期和占空比。
  • 输出控制: 提供 HLI_Pwm_SetOutputEnabled 和 HLI_Pwm_ForceOutput 函数，用于使能/禁止PWM输出，或将输出强制为高/低电平。
  • 极性控制: 支持设置PWM输出的正极性或负极性。

1.1 支持的设备

当前软件适用于以下芯片:

  • KF32A158xxxSF

1.2 名词及缩写

缩写解释
PWM脉冲宽度调制
CCP通用型捕捉/比较/脉宽调制模块
EPWM增强型脉冲宽度调制

2. 文件结构

文件名称描述
kf32axxx_hli_pwm.c此文件包含Pwm驱动程序的通用功能
kf32axxx_hli_pwm.h此头文件输出Pwm驱动程序的宏、类型定义和函数原型
kf32axxx_hli_pwm_Lcfg.c此文件包含Pwm初始化配置信息
kf32axxx_hli_pwm_Lcfg.h此文件包含Pwm声明初始化配置信息
kf32axxx_hli_pwm_cfg.h此文件包含Pwm模块、通道定义

3. 数据结构

3.1 数据类型

3.1.1 宏定义

无。

3.1.2 枚举

  1. PWM模块编号 (HLI_Pwm_ModuleType)

    枚举值解释
    HLI_PWM_MODULE_0 ~ HLI_PWM_MODULE_21PWM编号对应CCP0/1/2/3/4/20/21
    HLI_PWM_MODULE_11 ~ HLI_PWM_MODULE_36PWM编号对应EPWM11/12/13/16/31/32/33/36

  2. PWM通道编号 (HLI_Pwm_ChannelIndexType)

    枚举值解释
    HLI_PWM_CHANNEL_1 ~ HLI_PWM_CHANNEL_4PWM通道1~4, EPWM模块仅支持通道1和2

  3. PWM输出极性 (HLI_Pwm_PolarityType)

    枚举值解释
    HLI_PWM_ACTIVE_HIGH正极性输出
    HLI_PWM_ACTIVE_LOW负极性输出

  4. PWM初始化使能状态 (HLI_Pwm_InitialStateType)

    枚举值解释
    HLI_PWM_DISABLE初始化完成后关闭输出
    HLI_PWM_ENABLE初始化完成后开启输出

  5. PWM关闭时的输出状态 (HLI_Pwm_DisableLevelType)

    枚举值解释
    HLI_PWM_LOW_LEVEL输出关闭时引脚输出低
    HLI_PWM_HIGH_LEVEL输出关闭时引脚输出高

  6. PWM强制输出类型 (HLI_Pwm_ForceOutputType)

    枚举值解释
    HLI_PWM_FORCE_LOW强制输出低
    HLI_PWM_FORCE_HIGH强制输出高
    HLI_PWM_FORCE_DISABLE取消强制输出

  7. PWM函数执行状态 (HLI_Pwm_StatusType)

    枚举值解释
    HLI_PWM_OK执行成功
    HLI_PWM_DUTY_SETTING_FAILED占空设置失败
    HLI_PWM_PERIOD_SETTING_FAILED周期设置失败
    HLI_PWM_DUTY_PERIOD_SETTING_FAILED占空比和周期设置失败

3.1.3 类型定义

  1. PWM通道索引 (HLI_Pwm_ChlIndexType)
    typedef uint8_t HLI_Pwm_ChlIndexType;
    用于在API函数中唯一标识一个已配置的PWM通道。

3.2 配置项说明

  1. 模块配置 (HLI_Pwm_ModuleConfigType)

    成员解释取值范围
    ModulePWM模块硬件编号。可选范围参考HLI_Pwm_ModuleType
    Prescaler预分频值。uint32_t类型数据
    Period周期值。实际周期 T = (1/fsysclk) Prescaler Period。uint32_t类型数据

  2. 通道配置 (HLI_Pwm_ChannelConfigType)

    成员解释取值范围
    ModuleConfigIndex所属模块在 Pwm_ModuleConfig 数组中的索引。0 ~ (ModuleNum - 1)
    ChannelPWM通道硬件编号。可选范围参考HLI_Pwm_ChannelIndexType
    Duty初始占空比值。0 ~ Period
    Polarity输出极性。可选范围参考HLI_Pwm_PolarityType
    State初始化后的使能状态。可选范围参考HLI_Pwm_InitialStateType
    DisableLevelPWM输出关闭时的默认电平。可选范围参考HLI_Pwm_DisableLevelType

  3. 顶层配置 (HLI_Pwm_ConfigType)

    成员解释取值范围
    ModuleNum配置的模块总数。不超过实际模块配置数量。
    ChannelNum配置的通道总数。不超过实际通道配置数量。
    ModuleConfigPtr指向模块配置数组的指针。指向一个 HLI_Pwm_ModuleConfigType 类型的数组。
    ChannelConfigPtr指向通道配置数组的指针。指向一个 HLI_Pwm_ChannelConfigType 类型的数组。

4. 驱动函数

4.1 函数接口

4.1.1 HLI_Pwm_Init

NameDescription
函数名称HLI_Pwm_Init
语法void HLI_Pwm_Init(const HLI_Pwm_ConfigType *ConfigPtr)
同步/异步同步
重入性不可重入
形参(输入)ConfigPtr: 指向PWM多模块多通道配置结构体。
返回值无
描述配置多个PWM模块和多个PWM通道。
注意事项1. 该函数入参必须包含所有需要使用的模块和通道。
2. 模块和通道的索引编号由其在配置数组中的顺序自动确定。

4.1.2 HLI_Pwm_DeInit

NameDescription
函数名称HLI_Pwm_DeInit
语法void HLI_Pwm_DeInit(void)
同步/异步同步
重入性不可重入
形参(输入)无
返回值无
描述反初始化所有已开启的PWM模块。
注意事项无

4.1.3 HLI_Pwm_SetDutyCycle

NameDescription
函数名称HLI_Pwm_SetDutyCycle
语法HLI_Pwm_StatusType HLI_Pwm_SetDutyCycle(HLI_Pwm_ChlIndexType ChannelIndex, uint32_t Duty)
同步/异步同步
重入性通道索引编号不同时可重入
形参(输入)ChannelIndex: 通道索引编号。
形参(输入)Duty: 占空比值。
返回值HLI_PWM_OK: 设置成功。
返回值HLI_PWM_DUTY_SETTING_FAILED: 占空比设置失败（例如，占空比大于周期）。
描述配置一路PWM通道占空比。
注意事项占空比值 Duty 不能超过当前通道的周期值。

4.1.4 HLI_Pwm_SetDutyCyclePercent

NameDescription
函数名称HLI_Pwm_SetDutyCyclePercent
语法HLI_Pwm_StatusType HLI_Pwm_SetDutyCyclePercent(HLI_Pwm_ChlIndexType ChannelIndex, uint32_t DutyPercent)
同步/异步同步
重入性通道索引编号不同时可重入
形参(输入)ChannelIndex: 通道索引编号。
形参(输入)DutyPercent: 占空比百分比，范围 0 ~ 1000 (对应 0% ~ 100%)。
返回值HLI_PWM_OK: 设置成功。
返回值HLI_PWM_DUTY_SETTING_FAILED: 占空比设置失败（例如，DutyPercent > 1000）。
描述按百分比配置一路PWM通道占空比。
注意事项无

4.1.5 HLI_Pwm_SetPeriodAndDuty

NameDescription
函数名称HLI_Pwm_SetPeriodAndDuty
语法HLI_Pwm_StatusType HLI_Pwm_SetPeriodAndDuty(HLI_Pwm_ChlIndexType ChannelIndex, uint32_t Period, uint32_t Duty)
同步/异步同步
重入性通道索引编号不同时可重入
形参(输入)ChannelIndex: 通道索引编号。
形参(输入)Period: 周期值。
形参(输入)Duty: 占空比值。
返回值HLI_PWM_OK: 设置成功。
返回值HLI_PWM_PERIOD_SETTING_FAILED: 周期设置失败（例如，当模块内有多个通道使能时）。
返回值HLI_PWM_DUTY_PERIOD_SETTING_FAILED: 占空比和周期设置均失败。
描述配置一路PWM通道的周期和占空比。
注意事项当一个模块（如CCP0）内有多个（超过两个）PWM通道正在工作时，不建议使用此函数更改周期，否则会返回错误。此时应先停止其他通道。

4.1.6 HLI_Pwm_SetOutputEnabled

NameDescription
函数名称HLI_Pwm_SetOutputEnabled
语法void HLI_Pwm_SetOutputEnabled(HLI_Pwm_ChlIndexType ChannelIndex, bool State)
同步/异步同步
重入性通道索引编号不同时可重入
形参(输入)ChannelIndex: 通道索引编号。
形参(输入)State: true 为开启输出, false 为关闭输出。
返回值无
描述开启或关闭一路PWM通道的输出。
注意事项关闭输出后，引脚电平将恢复到初始化时 DisableLevel 配置的状态。

4.1.7 HLI_Pwm_ForceOutput

NameDescription
函数名称HLI_Pwm_ForceOutput
语法void HLI_Pwm_ForceOutput(HLI_Pwm_ChlIndexType ChannelIndex, HLI_Pwm_ForceOutputType State)
同步/异步同步
重入性通道索引编号不同时可重入
形参(输入)ChannelIndex: 通道索引编号。
形参(输入)State: 强制输出状态 (HLI_PWM_FORCE_LOW, HLI_PWM_FORCE_HIGH, HLI_PWM_FORCE_DISABLE)。
返回值无
描述设置一路PWM通道的强制输出状态。
注意事项可在运行时将PWM输出强制固定为高电平或低电平，或取消强制恢复正常PWM输出。

4.1.8 HLI_Pwm_GetDutyCycle

NameDescription
函数名称HLI_Pwm_GetDutyCycle
语法uint32_t HLI_Pwm_GetDutyCycle(HLI_Pwm_ChlIndexType ChannelIndex)
同步/异步同步
重入性可重入
形参(输入)ChannelIndex: 通道索引编号。
返回值uint32_t: 当前的占空比值。
描述获取一路PWM通道的占空比值。
注意事项无

4.1.9 HLI_Pwm_GetDutyCyclePercent

NameDescription
函数名称HLI_Pwm_GetDutyCyclePercent
语法uint32_t HLI_Pwm_GetDutyCyclePercent(HLI_Pwm_ChlIndexType ChannelIndex)
同步/异步同步
重入性可重入
形参(输入)ChannelIndex: 通道索引编号。
返回值uint32_t: 当前的占空比百分比 (0 ~ 1000)。
描述获取一路PWM通道的占空比百分比。
注意事项无

4.2 中断回调

本模块不提供中断回调函数。

5. 使用示例

注

示例中使用的参数仅用作示例演示，应用时以实际为准。

1. 基本PWM输出与动态调整

此示例展示了 Pwm 模块最核心的用法：在系统启动时通过 HLI_Pwm_Init 批量初始化PWM通道，然后在程序运行时通过 HLI_Pwm_SetDutyCycle 动态修改占空比。

6. 限制与假设

  1. 硬件资源复用: CCP模块如被用于其他功能(如ICU、OCU), 则不能作为PWM使用。
  2. 独立EPWM模式: 本驱动仅使用增强型脉宽调制模块EPWM的独立EPWM模式。
  3. 周期更新: 当一个模块（如CCP0）内有多个（超过2个）PWM通道正在工作时，不建议使用 HLI_Pwm_SetPeriodAndDuty 函数更新周期值，这可能会导致非预期的行为。如需更新周期，应先停止该模块下的所有其他通道。
  4. 索引编号: 模块和通道的索引编号根据初始化时使用的HLI_Pwm_ChannelConfigType数组内的定义顺序（从0开始）自动确定。
  5. 占空比范围: 设置占空比时，其数值（Duty）必须小于等于周期值（Period）。使用百分比设置时，数值范围为 0 ~ 1000，对应 0% ~ 100%。

7. 变更记录

版本时间变更记录
v1.02025-11-24新增初版文档
最近更新
贡献者: 翟宇