# PWM

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 功能概述

## PWM的基本概念

PWM（Pulse Width Modulation，脉冲宽度调制）是一种利用脉冲信号的宽度来调制输出信号的技术。通过改变脉冲的宽度（即高电平持续的时间），PWM能够有效地控制输出信号的平均电压，从而实现对模拟信号的数字编码和控制。 

## 工作原理

1. **占空比**：PWM信号的占空比是指高电平持续时间与一个完整周期的比例。通过调节占空比，可以控制输出信号的平均电压值。 

2. **周期与频率**：PWM信号的周期是指完成一个完整的高低电平循环所需的时间，频率则是单位时间内周期的数量。不同的应用场景可能需要不同的工作频率，常见的PWM频率范围从数百Hz到几MHz不等。 

3. **面积等效原理**：PWM的基本原理之一是面积等效原理，即冲量（面积）相等而形状不同的脉冲，作用于惯性环节时效果基本相同。通过调节脉冲的宽度，可以实现与目标波形相等的效果。

```{image} images/image_WSGZboCaAornmvxn60bcSpI0nOh.webp
:width: 1821px
:height: 427px
:align: center
```

## 应用领域

PWM技术广泛应用于多个领域，包括但不限于：

- **电机控制**：用于调节电机的转速和转矩，广泛应用于电动车、风力发电等。 

- **开关电源**：在电源管理中，PWM技术能够提高效率和功率密度，降低系统成本和功耗。 

- **通信系统**：PWM可以用于信号传输，增强抗干扰能力，延长通信距离。 

# PWM API

## 头文件

*qosa_pwm.h*

## 函数概览

| **函数** | **说明** |
| --- | --- |
| *qosa_pwm_config()* | 配置PWM功能 |
| *qosa_pwm_enable()* | 启用PWM输出功能并配置其参数 |
| *qosa_pwm_disable()* | 禁用PWM输出功能 |

## 函数详解

### qosa_pwm_config

- **功能描述**  
  配置PWM功能。

- **函数原型**

```c
qosa_pwm_error_e qosa_pwm_config(unsigned char pwm_sel, qosa_pwm_info_t *pwm_info);
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *pwm_sel* | 输入 | unsigned char | PWM通道标识符；范围：0~4 |
| *pwm_info* | 输入 | *qosa_pwm_info_t** | 指向PWM配置信息结构体的指针；详见 [*qosa_pwm_info_t*](#qosapwminfo_t) |

- **返回值说明**  
  *QOSA_PWM_SUCCESS*：函数执行成功  
  其他值（详见 [*qosa_pwm_error_e*](#qosapwmerror_e)）：函数执行失败

### qosa_pwm_enable

- **功能描述**  
  启用PWM输出功能并配置其参数。

- **函数原型**

```c
qosa_pwm_error_e qosa_pwm_enable(unsigned char pwm_sel, unsigned int high_one_cycle_duration);
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *pwm_sel* | 输入 | unsigned char | PWM通道标识符；范围：0~4 |
| *high_one_cycle_duration* | 输入 | unsigned int | 单周期内PWM输出保持高电平的持续时间；单位：定时器计数值；范围：0~total_one_cycle_duration。若传入此参数，将覆盖 *qosa_pwm_config()* 初始化时设置的初值 |

- **返回值说明**  
  *QOSA_PWM_SUCCESS*：函数执行成功  
  其他值（详见 [*qosa_pwm_error_e*](#qosapwmerror_e)）：函数执行失败

### qosa_pwm_disable

- **功能描述**  
  禁用PWM输出功能。

- **函数原型**

```c
qosa_pwm_error_e qosa_pwm_disable(unsigned char pwm_sel);
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *pwm_sel* | 输入 | unsigned char | PWM通道标识符；范围：0~4 |

- **返回值说明**  
  *QOSA_PWM_SUCCESS*：函数执行成功  
  其他值（详见 [*qosa_pwm_error_e*](#qosapwmerror_e)）：函数执行失败

## 结构体定义

### qosa_pwm_info_t

PWM配置信息结构体定义如下：

```c
typedef struct {
    unsigned int       high_one_cycle_duration;  
    unsigned int       total_one_cycle_duration; 
    unsigned int       pwm_psc;                  
    qosa_pwm_clk_src_e clk_src;                
} qosa_pwm_info_t;
```

| **参数** | **类型** | **说明** |
| --- | --- | --- |
| *high_one_cycle_duration* | unsigned int | 单周期内PWM输出保持高电平的持续时间；单位：定时器计数值；范围：0~total_one_cycle_duration。仅作为PWM初始化时的初值，后续实际生效值为 *qosa_pwm_enable()* 传入的参数 |
| *total_one_cycle_duration* | unsigned int | 一个完整PWM周期的总持续时间；单位：定时器计数值；取值不可为 *0* |
| *pwm_psc* | unsigned int | 时钟分频系数；取值不可为 *0* |
| *clk_src* | *qosa_pwm_clk_src_e* | 时钟源选择；详见 [*qosa_pwm_clk_src_e*](#qosapwmclksrce) |

## 枚举定义

### qosa_pwm_clk_src_e

PWM时钟源选择枚举定义如下：

```c
typedef enum {
    QOSA_FCLK_SEL_32K = 0,  
    QOSA_FCLK_SEL_13M,      
    QOSA_FCLK_SEL_26M,      
} qosa_pwm_clk_src_e;
```

| **成员** | **说明** |
| --- | --- |
| *QOSA_FCLK_SEL_32K* | 32 kHz时钟源；当需要在睡眠期间维持输出时可选 |
| *QOSA_FCLK_SEL_13M* | 13 MHz时钟源（暂不支持） |
| *QOSA_FCLK_SEL_26M* | 26 MHz时钟源 |

### qosa_pwm_error_e

PWM错误码枚举定义如下：

```c
typedef enum {
    QOSA_PWM_SUCCESS = 0,                                       
    QOSA_PWM_EXECUTE_ERR = 1 | (QOSA_COMPONENT_BSP_PWM << 16), 
    QOSA_PWM_INVALID_PARAM_ERR,                                
    QOSA_PWM_FUNC_SET_ERR,                                     
    QOSA_PWM_START_ERR,                                        
    QOSA_PWM_STOP_ERR,                                         
    QOSA_PWM_REPEAT_OPEN_ERR,                                  
    QOSA_PWM_REPEAT_CLOSE_ERR,                                 
    QOSA_PWM_NO_OPEN_ERR,                                      
    QOSA_PWM_SET_CLK_ERR,                                      
} qosa_pwm_error_e;
```

| **成员** | **说明** |
| --- | --- |
| *QOSA_PWM_SUCCESS* | 函数执行成功 |
| *QOSA_PWM_EXECUTE_ERR* | 函数执行失败 |
| *QOSA_PWM_INVALID_PARAM_ERR* | 输入参数无效 |
| *QOSA_PWM_FUNC_SET_ERR* | 功能设置失败 |
| *QOSA_PWM_START_ERR* | 启动失败 |
| *QOSA_PWM_STOP_ERR* | 停止失败 |
| *QOSA_PWM_REPEAT_OPEN_ERR* | 重复打开失败 |
| *QOSA_PWM_REPEAT_CLOSE_ERR* | 重复关闭失败 |
| *QOSA_PWM_NO_OPEN_ERR* | 打开配置失败 |
| *QOSA_PWM_SET_CLK_ERR* | 时钟设置失败 |

```{note}
*QOSA_COMPONENT_BSP_PWM* 为PWM组件ID，定义于 *qosa_def.h* 中。
```

# 应用逻辑流程图

```{figure} images/board_D1LZw5t9ohPtYTbGkpoceP4fnuK.jpg
:align: center
:alt: image
```

# 示例代码

完整示例代码请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/peripheral/pwm/pwm_demo.c