05 - 无源蜂鸣器应用

本章节介绍 Pico-G1 扩展板上的无源蜂鸣器应用示例 —— buzzer。该应用演示了如何使用 GPIO 接口生成软件方波来驱动无源蜂鸣器产生声音。这是学习 GPIO 定时控制和音频信号生成的基础示例，展示了通过软件延时实现精确时序控制的技术。

应用源码位于 SDK 目录 source/app/05_buzzer/，提供了完整的 GPIO 方波生成实现，是学习音频控制和定时器编程的重要参考。

1 应用概述

1.1 功能特性

  • GPIO 方波生成：通过软件延时产生精确频率的方波信号
  • 无源蜂鸣器驱动：演示无源蜂鸣器与有源蜂鸣器的区别和使用方法
  • 频率可调：支持自定义发声频率（推荐 2~4kHz）
  • 时长控制：支持自定义发声时长
  • 简单高效：最小代码实现，适合嵌入式学习和快速应用

1.2 技术参数

参数值
控制引脚GPIO5_5
默认频率2kHz（2000Hz）
默认时长1 秒
推荐频率2~4kHz（最响）
GPIO 接口Linux GPIO 字符设备 v1 ABI
实现方式软件方波（clock_gettime busy-wait）
CPU 占用发声期间 100% 单核占用

1.3 测试用例列表

index名称测试指令预期现象（成功）失败可能原因
1基础发声./buzzer蜂鸣器响 1 秒（2kHz）后自动关闭GPIO 引脚配置错误、蜂鸣器损坏
2自定义频率修改代码频率参数蜂鸣器按新频率发声频率超出可听范围
3自定义时长修改代码时长参数蜂鸣器按新时长发声时长参数设置错误
4多次发声循环调用发声函数蜂鸣器发出滴滴滴等多声延时时间过短导致连续发声

1.4 目录结构

source/app/05_buzzer/
├── Makefile              # 构建脚本
├── main.c                # 主程序
├── buzzer.c              # 蜂鸣器驱动实现
├── buzzer.h              # 蜂鸣器驱动头文件
├── gpio_hal.c            # GPIO HAL 层实现
├── gpio_hal.h            # GPIO HAL 层头文件
└── README.md             # 说明文档

2 硬件连接说明

2.1 引脚定义

信号板上 GPIO节点说明
控制脚（CTRL/SIG）GPIO5_5/dev/gpiochip5 line5方波驱动输入
VCC3.3V 或 5V—供电（按蜂鸣器模块标称）
GNDGND—地线

2.2 硬件电路

标准无源蜂鸣器接线：

     Pico-G1              无源蜂鸣器模块
  ┌───────────┐         ┌──────────────┐
  │           │         │              │
  │ GPIO5_5 ──┼─────────┤ SIG/CTRL     │
  │           │         │              │
  │    3.3V ──┼─────────┤ VCC          │
  │           │         │              │
  │     GND ──┼─────────┤ GND          │
  │           │         │              │
  └───────────┘         └──────────────┘

供电电压选择

  • 3.3V 供电：安全、功耗低，适合大多数应用
  • 5V 供电：音量更大，功耗较高，需确认模块支持
  • 建议优先使用 3.3V，如音量不足再尝试 5V

2.3 无源 vs 有源蜂鸣器

无源蜂鸣器（本模块）：

  • 没有内部振荡器，必须用方波驱动
  • 给直流电只会"咔"一声，不会持续发声
  • 频率可调，音调随频率变化
  • 需要持续的方波输入才能持续发声

有源蜂鸣器：

  • 内部振荡器，给直流电就响
  • 固定频率，音调不可调
  • 控制简单，高电平响、低电平停
  • 本模块的方波也能驱动有源蜂鸣器（方波的平均电压）

如何区分蜂鸣器类型

  • 看标签：有源通常标有"有源"或"Active"，无源标有"无源"或"Passive"
  • 看封装：有源通常稍高（内部有振荡电路），无源较薄
  • 测试：给直流电，持续响为有源，只"咔"一声为无源

2.4 引脚复用说明

GPIO5_5 引脚的物理地址配置：

  • 寄存器地址：iocfg_reg60 @ 0x100C0040
  • 默认功能：func0 = GPIO
  • 复用功能：func1 = PWM0（硬件 PWM）
  • 当前配置：0x00001000（输入使能 | GPIO 功能）

GPIO5_5 默认就是 GPIO 功能，无需修改 IOCFG 寄存器。如果需要使用硬件 PWM，需要配置为 func1。

3 编译与部署

3.1 前置条件

在编译本应用之前，请确保已完成以下准备工作：

  1. SDK 环境已搭建：参照 开发环境搭建 完成交叉编译工具链和 SDK 配置
  2. 硬件已连接：蜂鸣器正确连接到 GPIO5_5、VCC 和 GND

3.2 编译应用

# 设置工具链路径
export PATH=$PATH:<SDK>/tools/linux/toolchains/arm-gcc12.2.0-linux-uclibceabi/bin

# 进入示例目录
cd <SDK>/source/app/05_buzzer

# 编译
make

# 清理
make clean

编译成功后，在当前目录下生成可执行文件 buzzer。

3.3 部署到板端

# 使用 SCP 传输到开发板
scp buzzer root@<板端IP>:/usr/bin/

# 或通过 TFTP 下载
tftp -g -r buzzer <板端IP>

3.4 运行应用

# 添加执行权限
chmod +x /usr/bin/buzzer

# 运行蜂鸣器示例
/usr/bin/buzzer

应用启动后，蜂鸣器将响 1 秒（2kHz 方波）后自动关闭，程序退出。

3.5 预期输出

控制台输出

/mnt # ./buzzer
[buzzer] pad 复用：GPIO5_5 -> func0(GPIO)
[buzzer] pad 0x100C0040 -> 0x00001000
[buzzer] GPIO5_5 就绪。
[buzzer] 响 1s（2kHz 方波）...
[buzzer] 已关闭，退出。

实际现象

蜂鸣器发出"嘀——"的单音，持续 1 秒后停止。

固定与可变部分说明

  • 固定部分：发声时长和频率（对于固定的代码）
  • 可变部分：无（此程序输出完全固定）

4 内部执行逻辑详解

4.1 应用架构

本应用采用分层设计，包括硬件抽象层、驱动层和应用层：

// 应用层（main.c）
int main(int argc, char *argv[])
{
    // 1. 初始化蜂鸣器
    buzzer_init();

    // 2. 发声 1 秒（2kHz）
    buzzer_beep(1000, 2000);

    // 3. 关闭蜂鸣器
    buzzer_off();
    buzzer_deinit();

    return 0;
}

4.2 蜂鸣器驱动实现

蜂鸣器驱动实现了软件方波生成功能：

// 蜂鸣器初始化
int buzzer_init(void)
{
    // 配置 GPIO5_5 为输出
    if (gpio_set_direction(BUZZER_GPIO_CHIP, BUZZER_GPIO_LINE, GPIO_OUTPUT) < 0) {
        return -1;
    }

    // 初始状态为低电平
    gpio_set_value(BUZZER_GPIO_CHIP, BUZZER_GPIO_LINE, 0);

    return 0;
}

// 发声函数
void buzzer_beep(int duration_ms, int frequency_hz)
{
    if (frequency_hz <= 0 || duration_ms <= 0)
        return;

    // 计算半周期时长（微秒）
    int half_period_us = 1000000 / (2 * frequency_hz);
    int cycles = (duration_ms * 1000) / (2 * half_period_us);

    struct timespec start, current;
    clock_gettime(CLOCK_MONOTONIC, &start);

    int state = 0;
    for (int i = 0; i < cycles; i++) {
        // 翻转 GPIO 状态
        state = !state;
        gpio_set_value(BUZZER_GPIO_CHIP, BUZZER_GPIO_LINE, state);

        // 精确延时半周期
        clock_gettime(CLOCK_MONOTONIC, &current);
        long elapsed_us = (current.tv_sec - start.tv_sec) * 1000000 +
                         (current.tv_nsec - start.tv_nsec) / 1000;
        long target_us = (2 * i + 1) * half_period_us;
        long delay_us = target_us - elapsed_us;

        if (delay_us > 0) {
            usleep(delay_us);
        }
    }

    // 恢复低电平
    gpio_set_value(BUZZER_GPIO_CHIP, BUZZER_GPIO_LINE, 0);
}

// 关闭蜂鸣器
void buzzer_off(void)
{
    gpio_set_value(BUZZER_GPIO_CHIP, BUZZER_GPIO_LINE, 0);
}

// 蜂鸣器清理
void buzzer_deinit(void)
{
    buzzer_off();
}

4.3 软件方波原理

软件方波通过 GPIO 定时翻转实现：

关键点：

  1. 频率控制：通过控制半周期时长实现不同频率
  2. 占空比：50%（高电平和低电平时间相等）
  3. 精度保证：使用 clock_gettime() 获得精确时间戳

4.4 精确延时实现

使用 clock_gettime() 和 usleep() 实现精确延时：

// 获取单调时钟时间（不受系统时间调整影响）
clock_gettime(CLOCK_MONOTONIC, &current);

// 计算已过时间（微秒）
long elapsed_us = (current.tv_sec - start.tv_sec) * 1000000 +
                 (current.tv_nsec - start.tv_nsec) / 1000;

// 计算目标时间
long target_us = (2 * i + 1) * half_period_us;

// 计算剩余延时时间
long delay_us = target_us - elapsed_us;

// 执行延时
if (delay_us > 0) {
    usleep(delay_us);
}

为什么使用单调时钟

  • CLOCK_MONOTONIC：不受系统时间调整影响，保证定时准确
  • CLOCK_REALTIME：受系统时间调整影响，不适合定时应用

5 关键编程要点

5.1 GPIO 输出操作

控制流程：

  1. 配置 GPIO 为输出方向
  2. 设置初始值为低电平
  3. 定期翻转 GPIO 状态
  4. 结束时恢复低电平

注意事项：

  • 每次翻转后要精确延时
  • 使用 clock_gettime() 保证时间精度
  • 避免延时过长导致频率不准

5.2 频率与音调关系

不同频率对应不同音调：

频率音调音名说明
261HzDo（C4）中央C基准音，偏低
294HzRe（D4）——
330HzMi（E4）——
349HzFa（F4）——
392HzSol（G4）——
440HzLa（A4）标准音A调音基准
494HzSi（B4）——
523HzDo（C5）高音C高八度
1000~2000Hz——常用蜂鸣频率
2000~4000Hz——最响范围

推荐频率选择

  • 2000Hz：适中响度，人耳敏感
  • 2700Hz：较响，常用报警频率
  • 4000Hz：很响，但可能刺耳

5.3 时长与节奏控制

通过组合不同时长实现节奏：

// 短"滴"
buzzer_beep(100, 2700);
usleep(100000);  // 间隔 100ms

// 长"嘀"
buzzer_beep(500, 2700);
usleep(200000);  // 间隔 200ms

// 双"滴滴"
buzzer_beep(100, 2700);
usleep(50000);   // 间隔 50ms
buzzer_beep(100, 2700);
usleep(200000);

5.4 CPU 占用问题

软件方波的缺点：

  • 发声期间 100% 占用单个 CPU 核心
  • 无法实现复杂的多任务处理
  • 功耗较高

解决方案：

  1. 硬件 PWM：使用 GPIO5_5 的 PWM0 功能，CPU 占用极低
  2. 多线程：在独立线程中运行方波生成
  3. 专用音频芯片：使用外部音频驱动芯片

6 代码定制说明

6.1 修改频率和时长

编辑 main.c 中的调用参数：

// buzzer_beep(时长ms, 频率Hz);
buzzer_beep(1000, 2000);   // 1秒，2kHz
buzzer_beep(500, 2700);    // 0.5秒，2.7kHz
buzzer_beep(100, 4000);    // 0.1秒，4kHz（短促）

6.2 实现多声效果

在 main() 中循环调用：

// "滴滴滴"效果
for (int i = 0; i < 3; i++) {
    buzzer_beep(100, 2700);
    usleep(100000);  // 间隔100ms
}

// "嘀—嘀—嘀"效果（SOS节奏）
for (int i = 0; i < 3; i++) {
    buzzer_beep(200, 2700);
    usleep(100000);
}
usleep(200000);
for (int i = 0; i < 3; i++) {
    buzzer_beep(500, 2700);
    usleep(200000);
}
usleep(200000);
for (int i = 0; i < 3; i++) {
    buzzer_beep(200, 2700);
    usleep(100000);
}

6.3 播放简单旋律

实现简单歌曲播放：

// 简单音阶
#define NOTE_C4  262
#define NOTE_D4  294
#define NOTE_E4  330
#define NOTE_F4  349
#define NOTE_G4  392
#define NOTE_A4  440
#define NOTE_B4  494
#define NOTE_C5  523

// 音符结构
struct note {
    int frequency;
    int duration;
};

// 小星星旋律
struct note twinkle_star[] = {
    {NOTE_C4, 500}, {NOTE_C4, 500}, {NOTE_G4, 500}, {NOTE_G4, 500},
    {NOTE_A4, 500}, {NOTE_A4, 500}, {NOTE_G4, 1000},
    {NOTE_F4, 500}, {NOTE_F4, 500}, {NOTE_E4, 500}, {NOTE_E4, 500},
    {NOTE_D4, 500}, {NOTE_D4, 500}, {NOTE_C4, 1000},
};

void play_melody(struct note *melody, int length)
{
    for (int i = 0; i < length; i++) {
        buzzer_beep(melody[i].duration, melody[i].frequency);
        usleep(melody[i].duration * 1000);
    }
}

int main()
{
    buzzer_init();
    play_melody(twinkle_star, sizeof(twinkle_star)/sizeof(twinkle_star[0]));
    buzzer_deinit();
    return 0;
}

7 常见问题排查

问题可能原因解决方案
蜂鸣器不响蜂鸣器类型错误、接线错误、GPIO配置错误确认是无源蜂鸣器、检查接线、验证GPIO输出
只"咔"一声是有源蜂鸣器但用方波驱动给持续高电平而非方波
声音太小频率不在谐振点、供电电压不足调整频率到2700~4000Hz、提高供电电压
声音发闷频率过低提高频率到2000Hz以上
声音刺耳频率过高降低频率到2000~3000Hz范围
频率不准延时不精确使用硬件PWM或改进延时算法

8 进阶扩展

8.1 使用硬件PWM

改进为使用硬件PWM，CPU占用极低：

# 查看PWM控制器
ls /sys/class/pwm/

# 导出PWM通道
echo 0 > /sys/class/pwm/pwmchip0/export

# 配置PWM参数
echo 2000000 > /sys/class/pwm/pwmchip0/pwm0/period    # 2kHz周期（500ns）
echo 1000000 > /sys/class/pwm/pwmchip0/pwm0/duty_cycle # 50%占空比
echo 1 > /sys/class/pwm/pwmchip0/pwm0/enable         # 启用PWM

# 关闭PWM
echo 0 > /sys/class/pwm/pwmchip0/pwm0/enable

硬件PWM优势

  • CPU占用几乎为零
  • 频率精确，无抖动
  • 可以同时运行其他任务

8.2 多线程实现

在独立线程中运行方波生成：

#include <pthread.h>

struct buzzer_params {
    int duration_ms;
    int frequency_hz;
};

void *buzzer_thread(void *arg)
{
    struct buzzer_params *params = (struct buzzer_params *)arg;
    buzzer_beep(params->duration_ms, params->frequency_hz);
    free(params);
    return NULL;
}

// 异步发声
void buzzer_beep_async(int duration_ms, int frequency_hz)
{
    pthread_t thread;
    struct buzzer_params *params = malloc(sizeof(struct buzzer_params));
    params->duration_ms = duration_ms;
    params->frequency_hz = frequency_hz;

    pthread_create(&thread, NULL, buzzer_thread, params);
    pthread_detach(thread);
}

8.3 实现音量控制

通过改变占空比实现音量控制：

void buzzer_beep_volume(int duration_ms, int frequency_hz, int volume_percent)
{
    if (volume_percent < 0 || volume_percent > 100)
        volume_percent = 50;

    int half_period_us = 1000000 / (2 * frequency_hz);
    int on_us = half_period_us * volume_percent / 100;
    int off_us = half_period_us * 2 - on_us;

    for (int i = 0; i < duration_ms * frequency_hz; i++) {
        gpio_set_value(BUZZER_GPIO_CHIP, BUZZER_GPIO_LINE, 1);
        usleep(on_us);
        gpio_set_value(BUZZER_GPIO_CHIP, BUZZER_GPIO_LINE, 0);
        usleep(off_us);
    }
}

占空比与音量关系

  • 50%占空比：最大音量
  • 25%占空比：音量减半
  • 非线性关系，实际效果取决于蜂鸣器特性

9 参考链接