跳转至

蜂鸣器（Buzzer）设备组件

理论

蜂鸣器是一种能够通过电子信号控制的发声器件，能够为用户提供直观的声音信息，是一种常见的人机交互设备，实车上用于播放开机音乐，或进行警示、报错。

常见的蜂鸣器封装有插针型和贴片型，根据是否内置震荡电路可分为有源蜂鸣器和无源蜂鸣器。有源蜂鸣器只需提供直流电压，即可通过内部的震荡电路产生震荡电流进而鸣响；无源蜂鸣器则需要输入一定频率的方波来驱动，可以通过改变输入方波的频率发出不同音调的声音。

以 RoboMaster 开发板 C 型为例，使用的蜂鸣器为贴片型，原理图与实物图如下图所示：

image-20221208075947613

image-20221208075600049

对应的控制 IO 为 PD14，PWM 由定时器 TIM4 CHANNEL3 输出。

快速开始

组件源码仓库地址：https://github.com/ZJU-HelloWorld/HW-Components

外设驱动配置

在使用 PWM 波控制蜂鸣器时，使用 CubeMX 配置时将对应定时器预分频至 1MHz，以方便控制。例如对于 RoboMaster 开发板 C 型板载的蜂鸣器，驱动流程如下：

  • 对于 TIM4，查看数据手册可知其挂载在 APB1 总线上，时钟频率 84MHz，为达到 1MHz 需要 84 分频 ，因此将预分频值（Prescaler）设置为 83；
  • 工作频率与鸣响音调相关，因此重载值（Counter Period）在运行时由指定的音调频率计算得到，设频率 \(f\)，则重载值为 \(1000000 / f-1\)，CubeMX 配置可随意（注意：重载值不能为 0，否则将导致运行错误）；
  • 高电平时间即脉宽（Pulse）与鸣响强弱相关，可在组件运行时更改输出不同占空比的方波，来控制声音的强弱，CubeMX 配置可随意。

image-20221208093940723

使用前准备

使用前需要做以下准备：

  • 在 config.cmake 文件中设置 use_hwcomponents_devices_buzzer 选项为 ON，开启该设备文件的编译，若为 OFF 则根驱动配置需求在 CMakeLists.txt 文件中重配置为 ON。

示例

在项目中引用头文件：

C++
1
2
3
#include "buzzer.hpp"

namespace hw_buzzer = hello_world::buzzer;

实例化一个蜂鸣器设备并初始化，默认使能，如：

C++
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
/* 请确保该变量在播放期间不会被释放，建议为静态变量或全局变量 */
static hw_buzzer::TuneListInfo tune_list_info = { // 配置乐曲信息
    .intensity_scale = 1.0f,
    .tune_duration = 500,
    .list = {
        hw_buzzer::kTuneC4,
        hw_buzzer::kTuneD4,
        hw_buzzer::kTuneE4,
        hw_buzzer::kTuneF4,
        hw_buzzer::kTuneG4,
        hw_buzzer::kTuneA5,
        hw_buzzer::kTuneB5,
        hw_buzzer::kTuneC5,
        hw_buzzer::kTuneEnd,
    },
};
hw_buzzer::Buzzer* buzzer_ptr = nullptr;

buzzer_ptr = new hw_buzzer::Buzzer(
      &htim4, TIM_CHANNEL_3, hw_buzzer::PlayConfig::kLoopPlayback,
      &tune_list_info);

指定每个音符的时长和整体强度 \(\in (0,1]\)（数值太小可能无法正常播放），编写需要播放的音符列表（类型 Tune，音符表示如 kTuneA4：基本音，kTuneA4S：升，kTuneA4F：降，kTuneRet：休止），以 kTuneEnd 结尾

指定单次或循环播放选项，开始播放：

C++
1
2
3
buzzer_ptr = new hw_buzzer::Buzzer(
  &htim4, TIM_CHANNEL_3, hw_buzzer::PlayConfig::kSinglePlayback,
  &tune_list_info);
或：
C++
1
buzzer_ptr->set_play_config(hw_buzzer::PlayConfig::kSinglePlayback);

C++
1
2
3
buzzer_ptr = new hw_buzzer::Buzzer(
  &htim4, TIM_CHANNEL_3, hw_buzzer::PlayConfig::kLoopPlayback,
  &tune_list_info);
或：
C++
1
buzzer_ptr->set_play_config(hw_buzzer::PlayConfig::kLoopPlayback);

在播放过程中，需要不断调用 play 方法来控制音符时长和切换音调，调用频率至少为 1kHz。例如在一个 1kHz 的定时器中断回调函数中：

C++
1
2
3
if (buzzer_ptr->is_playing()) {
  buzzer_ptr->play();
}

单次播放完毕后将自动失能蜂鸣器，循环播放模式下则在手动调用 mute 方法时失能蜂鸣器。

注意：由于内部使用了硬件句柄，因此如果计划将实例作为全局变量时（全局变量初始化时对应的硬件句柄可能会还未初始化完毕），建议采取一下方法：

  1. 声明指针，后续通过 new 的方式进行初始化。
  2. 声明指针，后续通过返回函数（CreateXXXIns）中的静态变量（因为该变量只有在第一次调用该函数时才会运行初始化程序）进行初始化。
  3. 使用无参构造函数，后续调用 init 方法进行初始化。
  4. 使用无参构造函数，后续使用拷贝赋值函数或是移动赋值函数进行初始化。

附录

版本说明

版本号 发布日期 说明 贡献者
2022.12.08 发布蜂鸣器组件 薛东来
2023.12.10 发布蜂鸣器组件（Cpp） 蔡坤镇

参考资料

[1] RoboMaster 开发板 C 型嵌入式软件教程文档. Github 仓库