Chain Buzzer

BuzzerChain 是链式总线上蜂鸣器设备的辅助类。它提供了控制蜂鸣器频率、占空比、播放模式（自动播放、手动播放、音符播放）以及播放音符的方法。

支持以下产品：

UiFlow2 应用示例

按键音播放

在 UiFlow2 中打开 m5core_chain_buzzer_basic_example.m5f2 项目。

本示例演示如何在自动播放模式下使用 Chain Buzzer。它初始化蜂鸣器 RGB 指示灯，然后在按钮 A、B 或 C 被点击时播放 500 Hz、1000 Hz 或 1500 Hz 的音调。

UiFlow2 代码块：

示例输出：

None

MicroPython 应用示例

按键音播放

本示例演示如何在自动播放模式下使用 Chain Buzzer。它初始化蜂鸣器 RGB 指示灯，然后在按钮 A、B 或 C 被点击时播放 500 Hz、1000 Hz 或 1500 Hz 的音调。

MicroPython 代码块：

# SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
from chain import BuzzerChain
from chain import ChainBus


title0 = None
label_freq = None
label_tip = None
bus2 = None
chain_buzzer_0 = None


def btna_was_clicked_event(state):
    global title0, label_freq, label_tip, bus2, chain_buzzer_0
    label_freq.setText(str("Freq: 500 Hz"))
    chain_buzzer_0.tone(500, 50, 100)


def btnb_was_clicked_event(state):
    global title0, label_freq, label_tip, bus2, chain_buzzer_0
    label_freq.setText(str("Freq: 1000 Hz"))
    chain_buzzer_0.tone(1000, 50, 100)


def btnc_was_clicked_event(state):
    global title0, label_freq, label_tip, bus2, chain_buzzer_0
    label_freq.setText(str("Freq: 1500 Hz"))
    chain_buzzer_0.tone(1500, 50, 100)


def setup():
    global title0, label_freq, label_tip, bus2, chain_buzzer_0

    M5.begin()
    Widgets.setRotation(1)
    Widgets.fillScreen(0x000000)
    title0 = Widgets.Title(
        "Chain Buzzer Example", 3, 0xFFFFFF, 0x0000FF, Widgets.FONTS.Montserrat18
    )
    label_freq = Widgets.Label(
        "Freq: -- Hz", 107, 90, 1.0, 0xFFFFFF, 0x000000, Widgets.FONTS.Montserrat18
    )
    label_tip = Widgets.Label(
        "Press button tone", 78, 205, 1.0, 0xFFFFFF, 0x000000, Widgets.FONTS.Montserrat18
    )

    BtnA.setCallback(type=BtnA.CB_TYPE.WAS_CLICKED, cb=btna_was_clicked_event)
    BtnB.setCallback(type=BtnB.CB_TYPE.WAS_CLICKED, cb=btnb_was_clicked_event)
    BtnC.setCallback(type=BtnC.CB_TYPE.WAS_CLICKED, cb=btnc_was_clicked_event)

    bus2 = ChainBus(2, tx=21, rx=22)
    chain_buzzer_0 = BuzzerChain(bus2, 1)
    chain_buzzer_0.tone(2700, 50, 100)
    chain_buzzer_0.set_rgb_color(0x33FFFF)
    chain_buzzer_0.set_rgb_brightness(100, save=False)
    chain_buzzer_0.set_mode(BuzzerChain.MODE_AUTO_PLAY)


def loop():
    global title0, label_freq, label_tip, bus2, chain_buzzer_0
    M5.update()


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            bus2.deinit()
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

示例输出：

None

API 参考

BuzzerChain

class chain.buzzer.BuzzerChain(bus, device_id)

基类：KeyChain

用于通过链式总线与蜂鸣器设备交互的 Buzzer Chain 类。

参数:

bus (ChainBus) – Chain 总线实例。
device_id (int) – Chain 总线上蜂鸣器的设备 ID。

UiFlow2 代码块：

MicroPython 代码块：

from chain import ChainBus
from chain import BuzzerChain

bus2 = ChainBus(2, tx=21, rx=22)
chain_buzzer_0 = BuzzerChain(bus2, 1)

其他按钮和一些通用方法，请参考 ChainKey 类。

set_mode(mode)

设置蜂鸣器模式。

参数:: mode (int) – 蜂鸣器模式。使用 BuzzerChain.MODE_AUTO_PLAY (0)、BuzzerChain.MODE_MANUAL_PLAY (1) 或 BuzzerChain.MODE_NOTE_PLAY (2)。
返回:: 操作成功返回 True，否则返回 False。
返回类型:: bool

UiFlow2 代码块：

MicroPython 代码块：

success = chain_buzzer_0.set_mode(BuzzerChain.MODE_AUTO_PLAY)

get_mode()

获取蜂鸣器模式。

返回:: 蜂鸣器模式。BuzzerChain.MODE_AUTO_PLAY (0)、BuzzerChain.MODE_MANUAL_PLAY (1) 或 BuzzerChain.MODE_NOTE_PLAY (2)。失败时返回 None。
返回类型:: int

UiFlow2 代码块：

MicroPython 代码块：

mode = chain_buzzer_0.get_mode()

tone(freq=2700, duty=50, duration_ms=100)

播放音调（仅在 AUTO_PLAY 模式下有效）。

参数:

freq (int) – 频率（Hz）。范围：100-10000。默认值：2700。
duty (int) – 占空比（0-100）。默认值：50。
duration_ms (int) – 持续时间（毫秒）。默认值：100。

返回:

操作成功返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

MicroPython 代码块：

success = chain_buzzer_0.tone(2700, 50, 1000)
success = chain_buzzer_0.tone()  # Use default values: 2700Hz, 50% duty, 100ms

set_freq(freq=2700)

设置蜂鸣器频率。

参数:: freq (int) – 频率（Hz）。范围：100-10000。默认值：2700。
返回:: 操作成功返回 True，否则返回 False。
返回类型:: bool

UiFlow2 代码块：

MicroPython 代码块：

success = chain_buzzer_0.set_freq(2700)
success = chain_buzzer_0.set_freq()  # Use default: 2700Hz

get_freq()

获取蜂鸣器频率。

返回:: 频率（Hz），失败时返回 None。
返回类型:: int

UiFlow2 代码块：

MicroPython 代码块：

freq = chain_buzzer_0.get_freq()

set_duty(duty=50)

设置蜂鸣器占空比。

参数:: duty (int) – 占空比（0-100）。默认值：50。
返回:: 操作成功返回 True，否则返回 False。
返回类型:: bool

UiFlow2 代码块：

MicroPython 代码块：

success = chain_buzzer_0.set_duty(50)
success = chain_buzzer_0.set_duty()  # Use default: 50%

get_duty()

获取蜂鸣器占空比。

返回:: 占空比（0-100），失败时返回 None。
返回类型:: int

UiFlow2 代码块：

MicroPython 代码块：

duty = chain_buzzer_0.get_duty()

set_status(status)

设置蜂鸣器状态（仅在 MANUAL_PLAY 模式下有效）。

参数:: status (int) – 蜂鸣器状态。使用 BuzzerChain.STATUS_OFF (0) 或 BuzzerChain.STATUS_ON (1)。
返回:: 操作成功返回 True，否则返回 False。
返回类型:: bool

UiFlow2 代码块：

MicroPython 代码块：

success = chain_buzzer_0.set_status(BuzzerChain.STATUS_ON)

get_status()

获取蜂鸣器状态。

返回:: 蜂鸣器状态。BuzzerChain.STATUS_OFF (0) 或 BuzzerChain.STATUS_ON (1)。失败时返回 None。
返回类型:: int

UiFlow2 代码块：

MicroPython 代码块：

status = chain_buzzer_0.get_status()

note(note_index, duration_ms=100)

播放音符（仅在 NOTE_PLAY 模式下有效）。

参数:

note_index (int) – 音阶索引（0-61）。0 为休止符（静音），13 为 C4，61 为 C8。
duration_ms (int) – 持续时间（毫秒）。默认值：100。

返回:

操作成功返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

MicroPython 代码块：

success = chain_buzzer_0.note(25, 500)  # Play C5 for 500ms
success = chain_buzzer_0.note(25)  # Play C5 for 100ms (default duration)