用 ESP32 从零搭建一台网络收音机：YoRadio 快速上手完整指南

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

家里躺着一块 ESP32，想让它收网络电台、把歌曲信息投到屏幕上，还能用手机远程切台，却又不想从零写底层驱动？ESP32 YoRadio 就是为这件事准备的：把 ESP32 变成一台可联网、可显示、能接入智能家居的网络收音机，支持 MP3、AAC、FLAC 流媒体播放。下面按"先跑起来，再接入，最后定制"的顺序带你走完一遍。

能力速览：它到底能做什么

先看结论，再决定要不要折腾。YoRadio 的核心能力如下：

它同时支持联网（WEB）模式和 SD 卡本地（SD）模式，可以互相切换，断网时也能播卡内音乐。

把硬件跑起来：从源码到点亮的五步

第一步：获取源码并确认环境

把仓库克隆到本地：

git clone https://gitcode.com/GitHub_Trending/yo/yoradio

环境有两个硬要求，先核对，省得后面卡住：

• 使用Arduino IDE 1.8.19（暂不支持 2.x 系列）。
• ESP32 core 版本 ≥ 2.0.0。

主工程在yoRadio/目录下，入口是yoRadio.ino。

第二步：生成并修改硬件配置

硬件全部由一个文件决定：examples/myoptions.h。把它复制到yoRadio.ino同级目录，只打开你需要的行来覆盖默认值。项目还提供了一个可视化的引脚表生成工具，画好接线就能导出这份文件，省去手查引脚：

有两个宏最容易踩坑，务必二选一：

// 用 I2S DAC 时： #define I2S_DOUT 27 #define VS1053_CS 255 // 255 表示该模块不启用 // 用 VS1053b 时： #define I2S_DOUT 255 #define VS1053_CS 27

再按实接屏幕设定#define DSP_MODEL DSP_ST7735（不接屏就填DSP_DUMMY）。其余旋钮、按键、I2C、红外等引脚也都在这一个文件里。

第三步：替换字体文件

把yoRadio/fonts/glcdfont.c覆盖到 Arduino 的Adafruit_GFX_Library/glcdfont.c。这一步是为了让界面里的天气、WiFi 信号、音量等新图标正常显示，替换后重启一次 Arduino IDE。

第四步：上传数据与固件

在 Arduino IDE 里分两步（顺序别反）：

1. 工具 →ESP32 Sketch Data Upload，先把yoRadio/data/里的网页和配置写进 SPIFFS；
2. 再点上传，把固件烧进 ESP32。

第五步：配网并加入第一台电台

上电后 ESP32 会自建热点yoRadioAP（密码12345987），用手机或电脑连上，访问http://192.168.4.1/填入家里 WiFi。连上后设备会拿到局域网 IP，访问http://<设备IP>/在播放列表里加电台，或导入 KaRadio 的WebStations.txt。想省掉这一步，也可以提前把SSID<TAB>密码写进yoRadio/data/data/wifi.csv再上传数据。

接入你的家：MQTT 与 Home Assistant

接进智能家居后，YoRadio 从"台面上的播放器"变成可以被调度的设备。两条路径：MQTT 直连，或走 Home Assistant。

只开 MQTT 就够用时

把examples/mqttoptions.h复制到yoRadio/目录，填上 broker 地址、端口和主题前缀。四个主题分工很清晰：

• <ROOT>/command：下发指令，如next、prev、toggle、stop、vol 80、play 3；
• <ROOT>/status：回报播放状态；
• <ROOT>/volume：回报当前音量；
• <ROOT>/playlist：回报播放列表地址。

也就是说，你发一条play 3就能让设备播第 3 台，发vol 80直接定音量，而不必碰机器。

用 Home Assistant 做自动化

项目自带 HA 组件。步骤：

1. 把HA/custom_components/yoradio复制到.homeassistant/custom_components/；
2. 在configuration.yaml里按HA/example_configuration.yaml加一个media_player实体（填name和root_topic）；
3. 重启 Home Assistant，在 Lovelace 里加一张 Media Player 卡片即可。

接进来之后能玩出具体场景，举几个能直接抄的：

• 每天早上 7 点，自动化触发play并把音量提到 40；
• 有人回家时切换到新闻台，离家时stop；
• 把它和灯联动：播放开始时开小夜灯，停止后延时关灯。

因为 HA 组件支持远程媒体播放（本地媒体、Radio Browser、TTS），你甚至能语音让 YoRadio 播一段文本播报。

按硬件定制外观与手感

同一套固件，换不同的屏、不同的输入、不同的音频模块，成品气质完全不同。按预算和摆放位置来选。

显示：单色、彩色、大屏

• 单色 OLED（SSD1306、SH1106、N5110 等）：功耗低、对比高，适合"信息型"收音机，床头、书桌都够看。
• 彩色 TFT（ST7735、ILI9341、ST7789、GC9106 等）：支持 VU 表、位深和主题配色，视觉反馈更足，是多数人的默认选择。
• 高分辨率大屏（ILI9488、ST7796，480×320）：信息密度高，适合客厅、远距离观看。

每种屏在yoRadio/src/displays/都有独立驱动，配套默认布局放在yoRadio/src/displays/conf/下的displayXXXconf.h，想改界面布局就从这里入手。不接屏也可以，填DSP_DUMMY后设备照常出声，靠网页或 MQTT 控制。

控制：按键、旋钮、摇杆、触摸、红外

控制方式按使用场景选，且可以混用：

• 按键：3 个起步（左/中/右），加上下键共 5 个，操作最直观；
• 旋转编码器：一个旋钮就能同时管"音量"和"选台"，手感最好，是台机常见配置；
• 摇杆：一个器件顶替 5 个按键，布线更省；
• 触摸屏：横向滑是音量、纵向滑是选台、点按播放/选台，更像手机；
• 红外遥控：在网页设置里录制按键码，最多绑 3 个遥控器，适合客厅沙发场景。

各输入的引脚都写在myoptions.h，具体每个键的行为见仓库根目录的Controls.md。

音频模块：I2S DAC 还是 VS1053b

• I2S DAC：接法简单、解码交给 ESP32，适合求稳的入门方案；
• VS1053b：板载解码，额外支持左右平衡和图形均衡器，且对 SD 卡播放更友好；少数绿色板无声音时，在myoptions.h里加#define VS_PATCH_ENABLE false即可。

两者在固件里互斥，就是前面I2S_DOUT/VS1053_CS那对宏。

进阶与二次开发：源码结构与插件机制

想深挖时，按目录找就能定位，不必通读全量代码：

• yoRadio/src/core/：核心逻辑，player（播放）、display（显示调度）、netserver（Web）、mqtt、network、controls各管一摊；
• yoRadio/src/audioI2S/与yoRadio/src/audioVS1053/：两套音频解码，含 MP3/AAC/FLAC 解码子模块；
• yoRadio/src/displays/：屏幕驱动 +conf/（各屏布局）+widgets/（界面组件）；
• yoRadio/src/pluginsManager/：插件基类与事件调度；
• yoRadio/src/plugins/：放你自己的插件。

插件怎么写

插件就是继承Plugin基类，只重写你关心的事件，例如on_setup、on_start_play、on_stop_play、on_track_change、on_btn_click、on_ticker（每秒一次）。写好后把整个文件夹复制到yoRadio/src/plugins/<MyPlugin>即被识别，同一事件可以挂多个插件。

仓库给了三个能直接照抄的样例，都在examples/plugins/：

• helloWorld：把每个事件都打印一遍，适合先看事件流；
• backlightControls：按播放状态开关背光；
• deepsleep：停止播放时让 ESP32 进入深度睡眠省电。

插件机制的完整事件清单见yoRadio/src/pluginsManager/pluginsManager.h里的注释。此外，主题配色在examples/mytheme.h，界面语言在yoRadio/locale/（EN / RU），都是低风险的自定义点。

上手清单：动手前逐项核对

• Arduino IDE 是 1.8.19，ESP32 core ≥ 2.0.0
• myoptions.h已放到yoRadio.ino同级，I2S_DOUT与VS1053_CS只启用了一个
• DSP_MODEL与实接屏幕一致，无屏则填DSP_DUMMY
• 已用yoRadio/fonts/glcdfont.c覆盖 Adafruit_GFX 库的同名文件
• 先传 Sketch Data（SPIFFS），再传固件
• 通过yoRadioAP完成配网，并加入至少一台电台
• 需要远程控制时，已复制并填好mqttoptions.h，或装好 Home Assistant 的 yoradio 组件
• 有 SD 卡/RTC 需求时，相关引脚已在myoptions.h里配好

照这份清单走完，绝大多数"第一次不响"的问题都能在上传前被拦下。剩下的，就是选一块你喜欢的屏，把它挂上墙或摆上桌了。

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