三步把 yoRadio 接入 Home Assistant：MQTT 完整打通

三步把 yoRadio 接入 Home Assistant：MQTT 完整打通

【免费下载链接】yoradioWeb-radio based on ESP32-audioI2S library项目地址: https://gitcode.com/GitHub_Trending/yo/yoradio

电台能放歌了，但切台还得走到机器前按按钮，或者打开网页。想从手机或语音助手控制它，而 yoRadio 的默认控制都在设备本身上。解决这个问题的关键就是让它会说 MQTT。加上这个协议后，局域网里任何设备都能给它发指令。

弄懂原理：4 个 topic 就像公告栏

MQTT 的工作方式像一组公告栏。broker（比如 Mosquitto）是公告栏的柱子，topic 是栏目名。yoRadio 订阅一个收件栏目 command，有人往上贴 next、vol 80 这类文字，它就照着做。

同时它往三个发件栏目发布信息：status、volume、playlist。其中 status 是 JSON，带着是否正在播放、当前台号、电台名和节目标题。想看实现，yoRadio/src/core/mqtt.cpp 里就是"收命令"和"发状态"两件事，别急着抄配置，先把这个收发关系看清楚。

配置 MQTT 控制的三步

第 1 步：打开 MQTT 编译开关

目标：让固件编入 MQTT 代码，并记住 broker 地址。把 examples 目录里的 mqttoptions.h 复制到 yoRadio/ 目录，和 yoRadio.ino 放一起，内容改成自己的参数：

#define MQTT_HOST "192.168.1.100" // broker 地址 #define MQTT_PORT 1883 #define MQTT_USER "" #define MQTT_PASS "" #define MQTT_ROOT_TOPIC "yoradio/100/" // 本设备的根 topic

这个文件本质是编译开关：options.h 用__has_include检查它，文件不在，所有 MQTT 代码直接被跳过。验证方式：编译烧录正常，首次上线后用任意订阅工具看 yoradio/100/status 能收到一条 JSON。

第 2 步：发出第一条控制指令

目标：用第三方客户端往 command 栏目贴指令，验证设备真的在听。用 mosquitto 客户端发两条：

mosquitto_pub -h 192.168.1.100 -t "yoradio/100/command" -m "next" mosquitto_pub -h 192.168.1.100 -t "yoradio/100/command" -m "vol 80"

next 和 vol 都是 mqtt.cpp 里 onMqttMessage 函数逐字匹配的指令。验证方式：发完第一条电台切到下一台，第二条发出后音量跟着变。

第 3 步：把电台挂进 Home Assistant

目标：用一张媒体卡片代替手动发命令。把仓库里的 HA/custom_components/yoradio 目录拷到 HA 的 .homeassistant/custom_components/ 下，再在 configuration.yaml 加：

media_player: - platform: yoradio name: YoRadio (kitchen) root_topic: yoradio/100

重启 HA。验证方式：前端出现 yoRadio 实体，卡片上显示当前电台名和正在播放的标题，点播放、上一台、下一台都有响应。组件源码在 HA/custom_components/yoradio/，状态、音量、播放列表三个监听器都在里面的 media_player.py。

调优 MQTT 接入：设备冲突与音量步进

• 家里两台 yoRadio，发一条 next 两台一起切台，因为 command 栏目是共享的。给每台设备配不同的 MQTT_ROOT_TOPIC，比如 yoradio/100/ 和 yoradio/101/，HA 里 root_topic 跟着改，指令就只落到一台设备上。
• 用 HA 卡片调音量，一步太猛，因为组件的音量加减是 ±5%，默认 254 的满量程一步就是十几格。在 configuration.yaml 里加max_volume: '100'，步进取值变小，音量变化明显柔和。
• 想临时放一个不在播放列表里的流地址，不用改列表。直接往 command 发一条 http 开头的地址，设备的 burl 逻辑会接管并播放这个 URL，听完再回列表不受影响。

MQTT 接入常见问题

烧录完设备不响应，和 mqttoptions.h 的位置有关吗？多半就是它。文件不在 yoRadio/ 目录，MQTT 相关代码在编译期就被整段跳过，设备自然不连 broker。把文件移到正确位置重新编译即可。

ESP 端 MQTT_ROOT_TOPIC 带斜杠，HA 的 root_topic 不带，会连不上吗？不会。ESP 端是在尾部斜杠后直接拼 command 栏目名，HA 组件则是自己拼 /command，两者指向同一个 topic，写法不同属正常。

断线重连后状态会自己恢复吗？会。客户端内置 2 秒重连定时器，重连成功后立即重发 status、volume、playlist 三个栏目，外部显示不会停留在旧状态上。

三步走完，手机上就多了一张电台卡片。先把 next、prev、vol 几条命令手动过一遍，再挂 HA 卡片；完整指令清单见 examples/mqttoptions.h 里的注释。

【免费下载链接】yoradioWeb-radio based on ESP32-audioI2S library项目地址: https://gitcode.com/GitHub_Trending/yo/yoradio