RTTTL 蜂鸣器

rtttl 组件允许你轻松地将一个无源压电蜂鸣器连接到你的微控制器 并播放单音歌曲。它接受振铃音调文本传输语言（RTTTL）格式 （维基百科），该格式允许存储简单的旋律。

蜂鸣器模块

使用无源蜂鸣器的概述

你的蜂鸣器必须是无源的，这一点很重要；如果你给它接入 3.3V 时它会叫，那它就不是 无源蜂鸣器，这个库将无法正常工作。

音调生成器需要一个支持 PWM 的输出才能工作，目前仅支持 ESP8266 软件 PWM 输出 和 ESP32 LEDC 输出。

# 示例配置条目
output:
  - platform: ...
    id: rtttl_out
    ...

rtttl:
  output: rtttl_out
  id: my_rtttl
  gain: 60%

使用扬声器的概述

音调生成器也可以改用 Speaker 来输出音频。

# 示例配置条目
speaker:
  - platform: ...
    id: my_speaker
    ...

rtttl:
  speaker: my_speaker
  id: my_rtttl
  gain: 0.8

配置变量

• output (互斥, ID): 用于此蜂鸣器的浮点输出的 id。

• speaker (互斥, ID): 用于播放歌曲的 Speaker 的 id。

• id (可选, ID): 手动指定用于代码生成的 ID。

• gain (可选, Percentage): 使用此值可以设置声音的音量。

• on_finished_playback (可选, Automation): 播放完成时执行的操作。

NOTE

你只能使用 output 或 speaker 变量，不能同时使用两者。

所有操作和条件

• id (可选, ID): 如果你有多个组件，请手动指定 RTTTL 的 ID。

rtttl.play 操作

播放一个 RTTTL 音调。

on_...:
  then:
    - rtttl.play: 'siren:d=8,o=5,b=100:d,e,d,e,d,e,d,e'

配置选项：

• rtttl (必选, string, 可模板化): RTTTL 字符串。

NOTE

如果当前正在播放旋律，在开始新旋律之前，你必须调用 rtttl.stop 操作。

你可以在网上找到许多 RTTTL 字符串。在将它们添加到你的配置之前，你可以使用 RTTTL 在线播放器 测试旋律。细节参见下面的格式描述。

rtttl.stop 操作

停止播放。

on_...:
  then:
    - rtttl.stop

rtttl.is_playing 条件

当播放处于活动状态时，此条件返回 true。

# 在某个触发器中：
on_...:
  if:
    condition:
      rtttl.is_playing
    then:
      logger.log: 'Playback is active!'

RTTTL 格式

一个 RTTTL 字符串由三个用冒号（:）分隔的部分组成：

name:d=4,o=5,b=120:notes

1. Name（名称）：旋律的简短标识符（最多 10 个字符）
2. Control Parameters（控制参数）：包含 d、o 和 b 参数的控制部分
3. Notes（音符）：以音符数据编码的实际旋律

控制参数

• d（duration，时值）：默认音符时值。有效值为 1（全音符）、2（二分音符）、4（四分音符）、8（八分音符）、16（十六分音符）和 32（三十二分音符）。默认为 4。
• o（octave，八度）：音符的默认八度。有效值为 4、5、6 或 7。更高的值会产生更高音调的声音。默认为 6。
• b（beats，节拍）：以每分钟节拍数（BPM）表示的节拍速度。确定旋律播放的速度。默认为 63。

TIP

控制参数部分（例如 d=4,o=5,b=120）必须出现在字符串中音符部分之前。在此部分中，d、o 和 b 的顺序无关紧要，你可以指定其中任意子集。 任何未指定的参数将回退到上面列出的默认值。

音符格式

旋律中的每个音符遵循此模式：[duration][note][#][octave][.]

• duration（可选）：覆盖默认时值（1、2、4、8、16、32）
• note（音符）：音符名称：c、d、e、f、g、a、b，或 p 表示停顿
• #（可选）：升号修饰符，将音符升高半音
• octave（可选）：覆盖默认八度（4-7）
• . (dot)（可选）：附点音符，将时值延长 50%

示例

• 8e6 - 六八度的 E 八分音符
• 4c#5 - 五八度的 C# 四分音符
• 2g. - 默认八度的附点二分音符 G
• 4c#5. - 五八度的附点四分音符 C#
• 16p - 十六分音符停顿

提示：你可以尝试更改控制值来改变歌曲的听感。例如，增大 b 会使歌曲播放得更快，而更改 o 会改变音调的高低。

常用提示音

你也可以自己制作鸣叫模式！这里有一个简短的集合，你可以直接使用或按你的喜好调整：

two_short:d=4,o=5,b=100:16e6,16e6
long:d=1,o=5,b=100:e6
siren:d=8,o=5,b=100:d,e,d,e,d,e,d,e
scale_up:d=32,o=5,b=100:c,c#,d#,e,f#,g#,a#,b
star_wars:d=16,o=5,b=100:4e,4e,4e,8c,p,g,4e,8c,p,g,4e,4p,4b,4b,4b,8c6,p,g,4d#,8c,p,g,4e,8p
mission_imp:d=16,o=6,b=95:32d,32d#,32d,32d#,32d,32d#,32d,32d#,32d,32d,32d#,32e,32f,32f#,32g,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,a#,g,2d,32p,a#,g,2c#,32p,a#,g,2c,a#5,8c,2p,32p,a#5,g5,2f#,32p,a#5,g5,2f,32p,a#5,g5,2e,d#,8d
mario:d=4,o=5,b=100:16e6,16e6,32p,8e6,16c6,8e6,8g6,8p,8g,8p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,16p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16c7,16p,16c7,16c7,p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16d#6,8p,16d6,8p,16c6

测试设置

使用以下代码，你可以快速设置一个节点，并在开发者工具中使用 Home Assistant 的服务。 例如，要调用 rtttl.play，请选择服务 esphome.test_esp8266_rtttl_play，并在服务数据中输入

song_str: 'scale_up:d=32,o=5,b=100:c,c#,d#,e,f#,g#,a#,b'

示例代码

esphome:
  name: test_esp8266

esp8266:
  board: nodemcuv2

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

output:
  - platform: esp8266_pwm
    pin: GPIOXX
    id: rtttl_out

rtttl:
  output: rtttl_out
  on_finished_playback:
    - logger.log: 'Song ended!'

api:
  actions:
    - action: rtttl_play
      variables:
        song_str: string
      then:
        - rtttl.play:
            rtttl: !lambda 'return song_str;'

另请参阅

• ESP8266 软件 PWM 输出
• ESP32 LEDC 输出
• 扬声器组件
• API 参考：rtttl.h