06 PWM

作者：沈园园

一、PWM 概述

1.1 pwm 是什么

脉冲宽度调制(PWM)，是英文“Pulse Width Modulation”的缩写，简称脉宽调制，是利用微处理器的数字输出来对模拟电路进行控制的一种非常有效的技术，广泛应用在从测量、通信到功率控制与变换的许多领域中。

要想使用 pwm 还需了解 PWM 的相关参数：

PWM 的频率：是指 1 秒钟内信号从高电平到低电平再回到高电平的次数（一个周期），也就是说一秒钟 PWM 有多少个周期单位：Hz

PWM 的周期： T=1/f 周期=1/频率例：如果频率为 50Hz ，也就是说一个周期是 20ms，那么一秒钟就有 50 次 PWM 周期

PWM 的占空比：是一个脉冲周期内，高电平的时间占整个周期时间的比例单位： % (0%-100%) 例：一个周期 10ms,高电平占 8ms，那么此占空比就是 8/10=80%

1.2 pwm 原理

单片机的 IO 引脚输出的是数字信号，且只能输出 1 和 0，那如果 TTL 电平中，高电平为 5V，低电平为 0V，但是我们想要输出不同的模拟电压，比如输出 3.75V 应该怎么操作？

此时要用到 PWM，通过改变 IO 口输出方波的占空比，得到不同的模拟电压。3.75/5=0.75 ，也就是高电平时间占整个周期的 75%，即占空比为 75%，可得到模拟电压 3.75V。

注意上图中蓝线，代表着输出的模拟电压，占空比越大，则模拟电压也越大。

1.3 pwm 通道说明

查阅 Air780Exx系列模组管脚说明内的PWM章节描述，可知 Air780EHV 的实际可用 PWM 通道有 4 个(0/1/2/4), 4 个通道可单独使用,互不影响。3/5 已经被底层使用。

二、演示模块概述

1、main.lua：主程序入口；

2、pwm_app.lua：PWM 输出功能模块；

3、pins_air780ehv.json：用于配置管脚复用功能的 json 文件；

关于如何生成 json 文件参考：https://docs.openluat.com/air780epm/common/luatio/
示例代码中使用的是 Air780EHV 模组的 PWM4 通道（GPIO27，PIN16），参考完上述文档后通过 LuatIO 工具配置好并保存，最后连同脚本一起烧录到 Air780EHV 模组中即可实现 PWM 输出功能；

三、演示功能概述

使用 Air780EHV 核心板搭配 PWM 库演示 PWM 输出功能；

PWM 库目前有两套 API 风格：

1、旧风格 PWM 演示：

使用 pwm.open() 函数一次性完成 PWM 通道的配置与启动
使用 pwm.close() 函数关闭 PWM 通道
旧风格 PWM 接口不支持动态调整参数

2、新风格 PWM 演示：

使用 pwm.setup() 函数进行 PWM 参数配置
使用 pwm.start() 函数开启 PWM 通道进行 PWM 输出
使用 pwm.setDuty() 函数动态调整占空比，支持在开启 PWM 通道后调用
使用 pwm.setFreq() 函数动态调整信号频率，支持在开启 PWM 通道后调用
新风格 PWM 接口支持实时动态调整占空比和信号频率

四、准备硬件环境

1、Air780EHV核心板一块

2、TYPE-C USB数据线一根

3、Air780EHV核心板和数据线的硬件接线方式为

Air780EHV核心板通过TYPE-C USB口连接TYPE-C USB 数据线，数据线的另外一端连接电脑的USB口；
核心板正面的 ON/OFF 拨动开关拨到ON一端；

4、杜邦线若干

5、逻辑分析仪或者示波器，用于观察 PWM 输出的波形

6、代码中选用的 PWM 通道是 Air780EHV 模组的 PWM4（GPIO27，PIN16）

五、准备软件环境

5.1 软件环境

在开始实践本示例之前，先筹备一下软件环境：

1、烧录工具：Luatools 下载调试工具

2、内核固件：Air780EHV 最新版本的内核固件

3、脚本文件：https://gitee.com/openLuat/LuatOS/tree/master/module/Air780EHM_Air780EHV_Air780EGH/demo/pwm

4、lib脚本文件：使用Luatools烧录时，勾选添加默认lib 选项，使用默认lib脚本文件

准备好软件环境之后，接下来查看如何烧录项目文件到Air780EHV核心板，将本篇文章中演示使用的项目文件烧录到Air780EHV核心板中。

5.2 API 介绍

pwm 库：https://docs.openluat.com/osapi/core/pwm/

六、程序结构

pwm/
│── main.lua
│── pins_air780ehv.json
│── pwm_app.lua
│── readme.md

6.1 文件说明

main.lua：主程序入口文件。
pins_air780ehv.json：用于配置管脚复用功能的 json 文件。
pwm_app.lua：PWM 输出功能模块。

七、代码详解

7.1 main.lua

主程序文件 main.lua 是整个项目的入口点。它负责初始化系统环境。

7.2 pwm_app.lua

PWM 输出功能模块。

7.2.1 旧风格 PWM 演示

--[[
旧风格 PWM 演示函数
使用 pwm.open() 一次性完成配置和启动
适合固定频率/占空比、无需中途调整的场景
]]
local function task1_old_pwm()
    log.info("PWM", "旧风格 PWM 示例开始")

    -- 选择 PWM 通道 4
    -- 注意：本 demo 演示所使用的是 Air780EHM/EHV/EGH 模组的 PWM4 通道（GPIO27，PIN16）；
    -- 该引脚需要通过 LuatIO 工具进行复用配置，详细说明看最顶部的注意事项；
    local pwm_channel = 4

    -- 第一次输出：1 kHz，45% 占空比，分频精度 100
    local pwm_success = pwm.open(pwm_channel, 1000, 45, 0, 100)
    if pwm_success then
        log.info("PWM", "PWM4 通道开启成功: 信号频率 1000 Hz, 分频精度 100, 占空比 45%")
    else
        log.info("PWM", "PWM4 通道开启失败")
    end

    -- 持续 1 s 后关闭
    sys.wait(1000)
    pwm.close(pwm_channel)
    log.info("PWM", "PWM4 通道已关闭")

    -- 增加 1 秒的间隔时间
    sys.wait(1000)

    -- 第二次输出：500 Hz，60% 占空比，分频精度 100
    local pwm_success = pwm.open(pwm_channel, 500, 60, 0, 100)
    if pwm_success then
        log.info("PWM", "PWM4 通道开启成功: 信号频率 500 Hz, 分频精度 100, 占空比 60%")
    else
        log.info("PWM", "PWM4 通道开启失败")
    end

    -- 持续 2 s 后关闭
    sys.wait(2000)
    pwm.close(pwm_channel)
    log.info("PWM", "PWM4 通道已关闭")

    -- 增加 1 秒的间隔时间
    sys.wait(1000)

    -- 第三次输出：300 Hz，80% 占空比，分频精度 100
    local pwm_success = pwm.open(pwm_channel, 300, 80, 0, 100)
    if pwm_success then
        log.info("PWM", "PWM4 通道开启成功: 信号频率 300 Hz, 分频精度 100, 占空比 80%")
    else
        log.info("PWM", "PWM4 通道开启失败")
    end

    -- 持续 3 s 后关闭
    sys.wait(3000)
    pwm.close(pwm_channel)
    log.info("PWM", "PWM4 通道已关闭")

    log.info("PWM", "旧风格 PWM 示例结束")
end

7.2.2 新风格 PWM 演示

--[[
新风格 PWM 演示函数
使用 pwm.setup() 分步完成配置与启动，支持运行中动态修改频率和占空比
适合需要实时调节输出参数的场景
]]
local function task2_new_pwm()
    log.info("PWM", "新风格 PWM 示例开始")

    -- 选择 PWM 通道 4
    -- 注意：本 demo 演示所使用的是 Air780EHM/EHV/EGH 模组的 PWM4 通道（GPIO27，PIN16）；
    -- 该引脚需要通过 LuatIO 工具进行复用配置，详细说明看最顶部的注意事项；
    local pwm_channel = 4

    -- 配置 PWM 参数：频率 1000 Hz、占空比 50%、分频精度 100
    local setup_success = pwm.setup(pwm_channel, 1000, 50, 0, 100)
    if setup_success then
        log.info("PWM", "PWM4 配置成功: 信号频率 1000 Hz, 分频精度 100, 占空比 50%")
    else
        log.info("PWM", "PWM4 配置失败")
    end

    -- 启动 PWM 输出
    local pwm_success = pwm.start(pwm_channel)
    if pwm_success then
        log.info("PWM", "PWM4 启动成功")
    else
        log.info("PWM", "PWM4 启动失败")
    end

    -- 持续输出 2 秒
    sys.wait(2000)

    -- 动态调整占空比至 25%
    local setduty_success = pwm.setDuty(pwm_channel, 25)
    if setduty_success then
        log.info("PWM", "PWM4 占空比更新为 25%")
    else
        log.info("PWM", "PWM4 占空比设置失败")
    end

    -- 持续输出 2 秒
    sys.wait(2000)

    -- 动态调整信号频率为 2000 Hz
    local setfreq_success = pwm.setFreq(pwm_channel, 2000)
    if setfreq_success then
        log.info("PWM", "PWM4 频率更新为 2000 Hz")
    else
        log.error("PWM", "PWM4 频率设置失败")
    end

    -- 持续输出 2 秒
    sys.wait(2000)

    -- 停止 PWM 输出
    local pwm_success = pwm.stop(pwm_channel)
    if pwm_success then
        log.info("PWM", "PWM4 停止成功")
    else
        log.info("PWM", "PWM4 停止失败")
    end

    log.info("PWM", "新风格 PWM 示例结束")
end

7.2.3 主演示任务

--[[
主演示任务：
顺序调用旧风格与新风格 PWM 示例函数
并在两者之间插入 3 秒间隔方便区分新旧风格示例输出情况
]]
local function pwm_demo_task()
    log.info("PWM", "PWM 综合演示任务开始")

    -- 运行旧风格 PWM 示例
    task1_old_pwm()

    -- 间隔 3 秒
    sys.wait(3000)

    -- 运行新风格 PWM 示例
    task2_new_pwm()

    log.info("PWM", "PWM 综合演示任务结束")
end

八、运行结果展示

出现类似于下面的日志，使用逻辑分析仪或者示波器观察 PWM 输出波形是否与配置的参数一致，如一致，就表示运行成功

8.1 打印日志

[000000000.427] I/user.main PWM 001.000.000
[000000000.434] I/user.PWM PWM 综合演示任务开始
[000000000.434] I/user.PWM 旧风格 PWM 示例开始
[000000000.435] I/user.PWM PWM4 通道开启成功: 信号频率 1000 Hz, 分频精度 100, 占空比 45%
[000000001.435] I/user.PWM PWM4 通道已关闭
[000000002.435] I/user.PWM PWM4 通道开启成功: 信号频率 500 Hz, 分频精度 100, 占空比 60%
[000000004.436] I/user.PWM PWM4 通道已关闭
[000000005.436] I/user.PWM PWM4 通道开启成功: 信号频率 300 Hz, 分频精度 100, 占空比 80%
[000000008.437] I/user.PWM PWM4 通道已关闭
[000000008.437] I/user.PWM 旧风格 PWM 示例结束
[000000011.437] I/user.PWM 新风格 PWM 示例开始
[000000011.438] I/user.PWM PWM4 配置成功: 信号频率 1000 Hz, 分频精度 100, 占空比 50%
[000000011.438] I/user.PWM PWM4 启动成功
[000000013.438] I/user.PWM PWM4 占空比更新为 25%
[000000015.439] I/user.PWM PWM4 频率更新为 2000 Hz
[000000017.439] I/user.PWM PWM4 停止成功
[000000017.440] I/user.PWM 新风格 PWM 示例结束
[000000017.440] I/user.PWM PWM 综合演示任务结束