APWM 开发指导_Rev1.0

修订记录

版本	日期	作者	审核	修订内容
Rev1.0	2026-03-27	zlc		创建文档

1 简介

本文档介绍 LTE-EC71X APWM（高级脉宽调制）接口 API 情况，API 接口位于 components/kernel/lierda_api/liot_apwm/liot_apwm.h 文件声明。

APWM（AON Pulse Width Modulation）是在模组在休眠模式下，通过AON引脚实现脉冲。APWM 时钟源为 32 kHz，支持最大周期从 32ms 到 4096ms，典型应用场景为在休眠下，用户可以用AON驱动呼吸灯。

2 API 函数概览

函数	说明
`Liot_ApwmCfg()`	配置 APWM 参数
`Liot_ApwmEnable()`	启用或禁用 APWM 通道

3 类型说明

3.1 liot_apwm_errcode_e

APWM 错误码表示函数是否执行成功，若失败则返回错误原因。APWM 复用 PWM 的错误码定义，详见 PWM 文档中的 liot_pwm_errcode_e。

3.2 Liot_ApwmIndex_e

APWM 通道索引枚举，定义如下：

声明

typedef enum
{
    LIOT_APWM_INDEX_0,
    LIOT_APWM_INDEX_1,
    LIOT_APWM_INDEX_2,
    LIOT_APWM_INDEX_MAX,
}Liot_ApwmIndex_e;

参数

LIOT_APWM_INDEX_0：APWM 通道索引 0
LIOT_APWM_INDEX_1：APWM 通道索引 1
LIOT_APWM_INDEX_2：APWM 通道索引 2

说明

APWM 支持 3 个通道，每个通道可以独立配置和控制。通道对应引脚号请参考硬件引脚复用表。

3.3 Liot_ApwmPeriod_e

APWM 最大周期选项枚举，定义如下：

声明

typedef enum
{
    LIOT_APWM_MAX_PERIOD_4096MS = 0,
    LIOT_APWM_MAX_PERIOD_2048MS,
    LIOT_APWM_MAX_PERIOD_1024MS,
    LIOT_APWM_MAX_PERIOD_512MS,
    LIOT_APWM_MAX_PERIOD_256MS,
    LIOT_APWM_MAX_PERIOD_128MS,
    LIOT_APWM_MAX_PERIOD_64MS,
    LIOT_APWM_MAX_PERIOD_32MS,
    LIOT_APWM_MAX_PERIOD_MAX,
}Liot_ApwmPeriod_e;

参数

LIOT_APWM_MAX_PERIOD_4096MS：最大周期 4096ms
LIOT_APWM_MAX_PERIOD_2048MS：最大周期 2048ms
LIOT_APWM_MAX_PERIOD_1024MS：最大周期 1024ms
LIOT_APWM_MAX_PERIOD_512MS：最大周期 512ms
LIOT_APWM_MAX_PERIOD_256MS：最大周期 256ms
LIOT_APWM_MAX_PERIOD_128MS：最大周期 128ms
LIOT_APWM_MAX_PERIOD_64MS：最大周期 64ms
LIOT_APWM_MAX_PERIOD_32MS：最大周期 32ms

说明

APWM 时钟源为 32 kHz。随着频率增加，PWM 信号的精度会降低。选择合适的周期需要平衡精度和频率需求。

3.4 Liot_ApwmAccuracy_e

APWM 精度选项枚举，定义如下：

声明

typedef enum
{
    LIOT_APWM_ACCURACY_0 = 0,
    LIOT_APWM_ACCURACY_6 = 6,
    LIOT_APWM_ACCURACY_7 = 7,
    LIOT_APWM_ACCURACY_8 = 8,
}Liot_ApwmAccuracy_e;

参数

LIOT_APWM_ACCURACY_0：未设置精度
LIOT_APWM_ACCURACY_6：周期为 Liot_ApwmPeriod_e 枚举值 / 2
LIOT_APWM_ACCURACY_7：周期从 Liot_ApwmPeriod_e 枚举值选择
LIOT_APWM_ACCURACY_8：周期为 Liot_ApwmPeriod_e 枚举值 * 2

说明

精度值影响 APWM 的实际周期。根据精度设置的不同，实际周期会基于 Liot_ApwmPeriod_e 进行调整，从而实现不同时间分辨率的 PWM 输出。

3.5 Liot_ApwmCfg_t

APWM 配置参数结构体，定义如下：

声明

typedef struct
{
    Liot_ApwmIndex_e idx;
    Liot_ApwmPeriod_e Period;
    Liot_ApwmAccuracy_e accuracy;
    uint16_t highPeriod;
    uint16_t lowPeriod;
}Liot_ApwmCfg_t;

参数

idx：APWM 通道索引，范围 0 到 2，对应 4.2 Liot_ApwmIndex_e 枚举
Period：APWM 周期，取值来自 4.3 Liot_ApwmPeriod_e 枚举
accuracy：APWM 精度，取值来自 4.4 Liot_ApwmAccuracy_e 枚举
highPeriod：高电平持续时间，范围 0 到 100
lowPeriod：低电平持续时间，范围 0 到 100

说明

highPeriod 和 lowPeriod 共同决定占空比。例如，当 highPeriod 为 70，lowPeriod 为 20 时，占空比为 50%（高电平 50%，低电平 50%）。

4 API 函数详解

4.1 Liot_ApwmCfg

该函数用于配置 APWM 参数。

声明

liot_pwm_errcode_e Liot_ApwmCfg(Liot_ApwmCfg_t cfg);

参数

cfg：[In] APWM 配置参数指针，类型为 3.5 Liot_ApwmCfg_t.
返回值

liot_pwm_errcode_e：执行结果码

4.2 Liot_ApwmEnable

该函数用于启用或禁用指定的 APWM 通道。

声明

liot_pwm_errcode_e Liot_ApwmEnable(Liot_ApwmIndex_e idx, bool en);

参数

idx：[In] APWM 通道索引，范围 0 到 2，对应 3.2 Liot_ApwmIndex_e 枚举
en：[In] 布尔值，指示启用或禁用通道：
- true：启用 APWM 通道
- false：禁用 APWM 通道

返回值

liot_pwm_errcode_e：执行结果码
说明

该函数控制 APWM 输出通道的开关状态。在调用此函数前，应先通过 Liot_ApwmCfg 配置好参数。禁用通道后，APWM 输出将停止，但配置参数保持不变，重新启用时无需重新配置。

5 代码示例

示例代码参考 APWM 相关示例文件。

#include <stdio.h>
#include "liot_apwm.h"
#include "liot_gpio.h"
#include "liot_os.h"

/
* @brief APWM 示例线程
*/
void apwm_demo_thread(void *argv)
{
    Liot_ApwmCfg_t apwm_cfg;
    liot_pwm_errcode_e ret;

    // 配置引脚功能（需要根据实际硬件修改）
    liot_pin_set_func(20, 5); // 配置 APWM 通道 0 对应引脚
    liot_pin_set_func(106, 5); // 配置 APWM 通道 1 对应引脚
    liot_pin_set_func(25, 5); // 配置 APWM 通道 2 对应引脚

    // 配置 APWM 通道 0 - 1秒周期，50%占空比
    apwm_cfg.idx = LIOT_APWM_INDEX_0;
    apwm_cfg.Period = LIOT_APWM_MAX_PERIOD_1024MS;
    apwm_cfg.accuracy = LIOT_APWM_ACCURACY_7;
    apwm_cfg.highPeriod = 50;
    apwm_cfg.lowPeriod = 50;

    ret = Liot_ApwmCfg(&apwm_cfg);
    if (ret == LIOT_PWM_SUCCESS) {
        printf("APWM 0 配置成功\r\n");
        ret = Liot_ApwmEnable(LIOT_APWM_INDEX_0, true);
        if (ret != LIOT_PWM_SUCCESS) {
            printf("APWM 0 启用失败: %d\r\n", ret);
        }
    } else {
        printf("APWM 0 配置失败: %d\r\n", ret);
    }

    // 配置 APWM 通道 1 - 500ms周期，70%占空比
    apwm_cfg.idx = LIOT_APWM_INDEX_1;
    apwm_cfg.Period = LIOT_APWM_MAX_PERIOD_512MS;
    apwm_cfg.accuracy = LIOT_APWM_ACCURACY_7;
    apwm_cfg.highPeriod = 70;
    apwm_cfg.lowPeriod = 30;

    ret = Liot_ApwmCfg(&apwm_cfg);
    if (ret == LIOT_PWM_SUCCESS) {
        printf("APWM 1 配置成功\r\n");
        ret = Liot_ApwmEnable(LIOT_APWM_INDEX_1, true);
        if (ret != LIOT_PWM_SUCCESS) {
            printf("APWM 1 启用失败: %d\r\n", ret);
        }
    } else {
        printf("APWM 1 配置失败: %d\r\n", ret);
    }

    // 配置 APWM 通道 2 - 100ms周期，30%占空比
    apwm_cfg.idx = LIOT_APWM_INDEX_2;
    apwm_cfg.Period = LIOT_APWM_MAX_PERIOD_128MS;
    apwm_cfg.accuracy = LIOT_APWM_ACCURACY_7;
    apwm_cfg.highPeriod = 30;
    apwm_cfg.lowPeriod = 70;

    ret = Liot_ApwmCfg(&apwm_cfg);
    if (ret == LIOT_PWM_SUCCESS) {
        printf("APWM 2 配置成功\r\n");
        ret = Liot_ApwmEnable(LIOT_APWM_INDEX_2, true);
        if (ret != LIOT_PWM_SUCCESS) {
            printf("APWM 2 启用失败: %d\r\n", ret);
        }
    } else {
        printf("APWM 2 配置失败: %d\r\n", ret);
    }

    // 运行一段时间后禁用 APWM 通道 0
    liot_rtos_task_sleep_ms(5000);
    ret = Liot_ApwmEnable(LIOT_APWM_INDEX_0, false);
    if (ret == LIOT_PWM_SUCCESS) {
        printf("APWM 0 已禁用\r\n");
    }

    while (1)
    {
        liot_rtos_task_sleep_ms(1000);
    }
}

运行结果：

运行 DEMO 程序后模组共输出三路 APWM 信号，上图为逻辑分析仪捕获的信号，周期分别为1s、500ms、100ms。

6 注意事项

APWM 时钟源固定为 32 kHz，不可更改。
随着频率增加，PWM 信号的精度会降低。在高频率应用中，精度可能无法满足需求。
highPeriod 和 lowPeriod 的总和应小于等于 100，否则可能导致输出异常。
在使用 APWM 前，需要先配置对应的引脚功能为 APWM 输出。
APWM 通道索引范围是 0 到 2，共 3 个通道，请勿超出范围。
在禁用 APWM 通道前，确保该通道已启用且正在运行。
APWM 复用 PWM 的错误码定义，错误处理逻辑与 PWM 相同。