Як зібрати і прошити yoradio на ESP32: детальний гайд для новачків

Ця стаття — покроковий посібник з установки і налаштування прошивки yoradio на модуль ESP32. Ви отримаєте повноцінне стаціонарне інтернет-радіо з дисплеєм, керуванням, веб-інтерфейсом і можливістю слухати сотні станцій з усього світу. Гайд написаний для тих, хто вперше стикається з ESP32 або давно не займався цим і встиг усе забути.

Що таке yoradio

yoradio — це відкрита прошивка від розробника e2002, яка перетворює звичайний модуль ESP32 на повноцінний веб-радіоприймач. Проект живий, регулярно оновлюється, підтримує велику кількість дисплеїв, аудіомодулів, органів керування (кнопки, енкодери, IR-пульти, тачскріни), має веб-інтерфейс для керування станціями, підтримку MQTT, інтеграцію з Home Assistant, відтворення з SD-карти і купу інших приємних дрібниць.

Офіційний репозиторій: https://github.com/e2002/yoradio

Готовий результат виглядає так: невелика коробочка з дисплеєм, на якому відображається назва станції, назва треку, годинник, іконка WiFi, іноді VU-мітер і погода. Керується енкодером або кнопками. Плюс веб-інтерфейс за IP-адресою пристрою, звідки додаєте станції і налаштовуєте все, що завгодно.

Що потрібно з заліза

Мінімальний набір: плата ESP32 (найпоширеніший варіант — ESP32 DevKit v1 або аналог), аудіомодуль (I2S DAC на кшталт PCM5102 чи MAX98357, або окремий модуль VS1053b з декодером на борту), дисплей (ST7789, ST7735, SSD1306, ILI9341 та багато інших), органи керування (кнопки, енкодер, IR-приймач — на смак), USB-кабель для прошивки, живлення (5V через MicroUSB підходить для більшості схем).

Точні схеми з'єднань і повний перелік підтримуваного обладнання є в вікі проекту та у зручному онлайн-генераторі: https://e2002.github.io/docs/myoptions-generator.html — це ключовий інструмент, до нього ще повернемось.

Arduino IDE — тільки 1.8.19

Це найважливіший момент, з якого починаються всі проблеми. yoradio не підтримує Arduino IDE 2.x. Не намагайтеся зібрати проект у новій IDE — це заощадить вам кілька годин ловіння дивних помилок.

Потрібна саме версія 1.8.19. Скачати її можна тут: https://www.arduino.cc/en/software/OldSoftwareReleases. Обирайте Windows Installer, ставте зі стандартними опціями.

Якщо у вас уже є новіша Arduino IDE 2.x, старіша версія 1.8.19 нормально стоїть паралельно і нічого не ламає — вони незалежні.

Робочі папки Arduino на Windows 11

Після установки IDE знадобиться орієнтуватися в кількох папках, які створюються автоматично. Головні дві:

C:\Users\<ваше_ім'я>\Documents\Arduino\ — це папка скетчів (Sketchbook). Сюди ви будете класти проект yoradio, тут же живе підпапка libraries, у яку Library Manager встановлює бібліотеки. Якщо папки немає — запустіть Arduino IDE один раз, вона створиться автоматично.

C:\Users\<ваше_ім'я>\AppData\Local\Arduino15\ — прихована папка з ядром ESP32 і внутрішніми налаштуваннями. Щоб її побачити, у Провіднику ввімкніть відображення прихованих файлів (View → Show → Hidden items), або просто вставте шлях в адресний рядок.

Додаємо підтримку ESP32

За замовчуванням Arduino IDE знає тільки про класичні плати Arduino. Щоб з'явилася підтримка ESP32, треба додати відповідне ядро.

Відкрийте File → Preferences. У полі Additional Boards Manager URLs вставте:

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

Натисніть OK. Далі Tools → Board → Boards Manager, у пошуку введіть esp32, знайдіть пакет esp32 by Espressif Systems і встановіть. Yoradio вимагає версію 2.0.0 або вищу — беріть 2.0.14 або 3.0.x, обидві працюють коректно з останніми версіями yoradio.

Установка ядра займає кілька хвилин, воно вагоме. Після завершення в списку плат з'явиться цілий підрозділ ESP32 Arduino.

Скачуємо і кладемо yoradio на місце

Заходьте на https://github.com/e2002/yoradio, тисніть зелену кнопку Code → Download ZIP. Або візьміть останній стабільний реліз зі сторінки Releases. Розпакуйте архів у зручному місці.

Всередині розпакованого архіву буде папка yoradio-main (або з номером версії). Всередині неї — папка yoRadio з файлом yoRadio.ino. Ось саме цю папку yoRadio треба скопіювати в Documents\Arduino\. Тобто фінальна структура має виглядати так:

Documents\Arduino\yoRadio\yoRadio.ino
Documents\Arduino\yoRadio\options.h
Documents\Arduino\yoRadio\data\
Documents\Arduino\yoRadio\src\
Documents\Arduino\yoRadio\locale\

Ключове правило Arduino: папка з ino-файлом має називатися точно так само, як сам файл (без розширення). Тобто папка yoRadio містить yoRadio.ino. Якщо перейменувати папку — IDE не відкриє проект.

Генеруємо myoptions.h під ваше залізо

Файл options.h містить усі можливі налаштування прошивки зі значеннями за замовчуванням. Його не чіпаємо — оновлення yoradio перезапише ваші зміни. Замість цього створюємо файл myoptions.h, у якому вказуємо тільки те, що відрізняється від дефолту: модель дисплея, піни підключення, тип аудіомодуля, які кнопки чи енкодери використовуємо, мову інтерфейсу.

Писати цей файл вручну болісно і легко помилитися. Тому автор yoradio зробив зручний онлайн-генератор: https://e2002.github.io/docs/myoptions-generator.html

Відкриваєте його в браузері, вибираєте зі списків свою модель ESP32, тип дисплея, аудіомодуль, вказуєте, до яких пінів усе підключено, вибираєте органи керування. Праворуч живою пливе візуальна схема з'єднань, знизу генерується готовий текст myoptions.h. Це можна експортувати як файл або просто скопіювати.

Отриманий myoptions.h кладемо в папку Documents\Arduino\yoRadio\ — поруч з yoRadio.ino. Це критично: файл має лежати саме поряд, інакше проект його не побачить.

Кілька практичних порад по заповненню генератора. Якщо у вас I2S DAC — типові піни для більшості схем: I2S_DOUT=27, I2S_BCLK=26, I2S_LRC=25. Якщо у вас ST7789 SPI — типові піни дисплея: TFT_CS=5, TFT_DC=4, TFT_RST=2 (можна також залишити -1 і з'єднати RST з EN пінами ESP32). Для кнопок і енкодерів на ESP32 підходять піни 32-39 (окремі з них — 34, 35, 36, 39 — тільки для input, це нормально для кнопок). Мову інтерфейсу поки залишайте EN — про українізацію є окрема стаття, посилання внизу.

Встановлюємо бібліотеки

У згенерованому myoptions.h зверху є коментар зі списком бібліотек, які потрібні для вашої конфігурації. Це важлива підказка — читайте її.

Відкривайте Sketch → Include Library → Manage Libraries. Треба знайти і встановити:

Adafruit GFX Library — основа для роботи з дисплеями. Обов'язково для більшості конфігурацій.

Драйвер конкретного дисплея — залежить від моделі. Для ST7789 і ST7735 — Adafruit ST7735 and ST7789 Library. Для SSD1306 — Adafruit SSD1306. Для ILI9341 — Adafruit ILI9341. І так далі. Ці бібліотеки зазвичай самі підтягують Adafruit_GFX і Adafruit_BusIO — погоджуйтесь на пропозицію встановити залежності.

OneButton — для обробки натискань і подвійних кліків.

Опційно: IRremoteESP8266 (якщо є ІЧ-пульт), RTCLib (якщо є RTC-модуль DS3231 або DS1307), XPT2046_Touchscreen (якщо є тачскрін).

Бібліотеки для роботи мережі (ESPAsyncWebServer, AsyncTCP, async-mqtt-client) окремо встановлювати не треба — з версії 0.8.920 yoradio вбудував їх у сам проект.

Замінюємо файл glcdfont.c

Це крок, який легко пропустити, а потім довго думати, чому на дисплеї криво відображаються іконки і кирилиця. Стандартний шрифт бібліотеки Adafruit_GFX не містить деяких спеціальних символів, які yoradio використовує (WiFi, гучномовець, градус тощо), і має обмежену підтримку кирилиці.

Тому yoradio постачається зі своєю версією файлу glcdfont.c, яка лежить у Documents\Arduino\yoRadio\fonts\glcdfont.c. Цим файлом треба замінити оригінальний, який Library Manager поставив разом з Adafruit_GFX. Оригінал живе за адресою:

Documents\Arduino\libraries\Adafruit_GFX_Library\glcdfont.c

Просто скопіюйте файл з проекту yoradio на місце файлу з бібліотеки. Після заміни перезапустіть Arduino IDE, щоб вона підтягла новий файл.

Налаштування плати перед прошивкою

Підключіть ESP32 до комп'ютера через USB. У диспетчері пристроїв Windows має з'явитися новий COM-порт. Якщо не з'явився — швидше за все не встановлений драйвер USB-UART чіпа, який стоїть на вашій платі. Найпоширеніші: CP210x (від Silicon Labs) або CH340 (WCH). Дивитесь у диспетчер пристроїв — там буде "Unknown device" з характерною назвою, за нею гуглиться потрібний драйвер. Ставите — з'являється COM-порт.

Тепер у Arduino IDE відкрийте Documents\Arduino\yoRadio\yoRadio.ino. IDE підтягне купу вкладок — це нормально, там багато файлів. У меню Tools виставте:

Board → ESP32 Arduino → ESP32 Dev Module. Це єдина плата, з якою yoradio точно збереться (з версії 0.9.141 додано жорстку перевірку — при виборі інших плат буде помилка компіляції). Виняток — якщо у вас модуль з PSRAM, тоді можна вибрати ESP32 Wrover Module.

Partition Scheme → Minimal SPIFFS (1.9MB APP with OTA / 190KB SPIFFS) або No OTA (2MB APP / 2MB SPIFFS). Стандартна схема розділів не підходить — скетч не влізе.

Port → ваш COM-порт з ESP32.

Решту параметрів можна залишити за замовчуванням.

Плагін ESP32 Filesystem Uploader

Yoradio використовує SPIFFS — вбудовану файлову систему ESP32 — для зберігання веб-інтерфейсу, шрифтів і даних станцій. Це окремий образ, що заливається на плату не разом зі скетчем, а окремо. Для цього потрібен плагін до Arduino IDE.

Скачайте останню версію звідси: https://github.com/lorol/arduino-esp32fs-plugin/releases. У архіві є файл esp32fs.jar. Його треба покласти за наступним шляхом:

Documents\Arduino\tools\ESP32FS\tool\esp32fs.jar

Папок tools\ESP32FS\tool\ за замовчуванням не існує — створіть їх вручну. Після цього перезапустіть Arduino IDE. Якщо все зроблено правильно, у меню Tools з'явиться новий пункт ESP32 Sketch Data Upload.

Перша прошивка

Порядок дій має значення. Спочатку залийте файлову систему, потім скетч.

Крок 1: закрийте Serial Monitor, якщо він відкритий (інакше буде помилка "Serial port busy"). Тисніть Tools → ESP32 Sketch Data Upload. Знизу побіжить лог: спочатку створення образу з вмісту папки yoRadio\data\, потім заливка через COM-порт. Триває приблизно хвилину. Успіх — коли внизу з'явиться повідомлення про завершення.

Крок 2: тисніть кнопку Upload (стрілка вправо на панелі, або Sketch → Upload). Спочатку скетч скомпілюється — при першому разі це може зайняти 5–10 хвилин, ESP32-компілятор повільний, а файлів у проекті багато. Наступні компіляції будуть значно швидшими за рахунок кешу.

На деяких ESP32-платах треба тримати кнопку BOOT під час старту заливки — якщо в лозі побачите нескінченні "Connecting............." і не приконнектиться, натисніть і тримайте BOOT, поки не з'явиться "Writing at 0x...". На платах з нормальною авто-перезаваньтаженням це не потрібно.

Успішна заливка закінчується словами "Hard resetting via RTS pin..." і плата сама перезавантажиться.

Перший старт та підключення до Wi-Fi

Відкрийте Serial Monitor (Tools → Serial Monitor), встановіть швидкість 115200 baud. Натисніть кнопку RESET на платі. У логу побачите послідовність запуску yoradio — версію прошивки, ініціалізацію дисплея, спробу підключитися до Wi-Fi.

Оскільки Wi-Fi ще не налаштований, плата підніме власну точку доступу з ім'ям yoRadioAP і паролем 12345987. Це також буде показано на дисплеї — там з'явиться заставка з IP-адресою 192.168.4.1.

З телефона або ноутбука знайдіть мережу yoRadioAP, підключіться до неї (пароль 12345987), у браузері відкрийте http://192.168.4.1/. Побачите просту форму з полями для SSID і пароля вашого домашнього Wi-Fi. Введіть, збережіть. Плата перезавантажиться і підключиться вже до вашої мережі. У Serial Monitor побачите отриману IP-адресу — щось на кшталт 192.168.1.xx. Ця адреса ж з'явиться і на дисплеї.

Веб-інтерфейс і станції

Заходьте з браузера на http://<ip_плати>/. Відкриється основний веб-інтерфейс yoradio: плеєр з кнопкою play/stop, регулятором гучності, списком станцій, посиланнями на плейлист-редактор і налаштування.

Спочатку список станцій порожній. Заходьте в Playlist Editor, додавайте перші станції. Формат простий: назва + пряме посилання на потік. Наприклад, для тесту візьміть щось перевірене:

• Radio Paradise (Main Mix): https://stream.radioparadise.com/aac-320
• Радіо Промінь: https://radio.ukr.radio/ur2-mp3
• Hit FM Український: https://online.hitfm.ua/HitFM_Ukr

Дивітьться також повний список українських інтернет-радіостанцій 2026.

Збережіть плейлист, поверніться на головну сторінку, виберіть станцію, натисніть play — має піти звук з вашого DAC.

Якщо звуку немає, а лог показує, що потік підключився і буферизується — швидше за все проблема в піновці DAC або в тому, що модуль підключений неправильно. Перевіряйте фізичні з'єднання, свою myoptions.h, живлення DAC.

Якщо картинка на дисплеї повернута не в той бік — додайте в myoptions.h рядок #define TFT_ROTATE 3 і перезалийте скетч. Значення 0, 1, 2 або 3 — крутіть, поки не стане правильно.

Резервне копіювання і оновлення

Коли все запрацює, зробіть бекап. У веб-інтерфейсі в налаштуваннях є експорт налаштувань, або можна просто скачати файли:

• http://<ip_плати>/data/playlist.csv — ваш список станцій
• http://<ip_плати>/data/wifi.csv — збережені Wi-Fi мережі

Збережіть їх у папці Documents\Arduino\yoRadio\data\data\ — тоді при наступному ESP32 Sketch Data Upload ваші налаштування збережуться.

Для оновлення прошивки в майбутньому: скачайте нову версію yoradio, покладіть свій myoptions.h у нову папку yoRadio\, перенесіть свої резервні playlist.csv і wifi.csv у data\data\, зробіть ESP32 Sketch Data Upload, потім Upload скетча. Все повернеться.

Альтернативний спосіб оновлення — через веб-інтерфейс. У yoradio є розділ http://<ip_плати>/update, куди можна залити бінарники: спочатку прошивку (Sketch → Export compiled binary у Arduino IDE), потім SPIFFS-образ. Без USB-кабеля, дистанційно.

Українські літери

Якщо ви додали станцію з назвою українською мовою — швидше за все побачите, що літери є, і, ї, ґ просто пропадають з тексту. Замість "Радіо Промінь" буде "Радо Промнь". Це відомий недолік базової прошивки: yoradio офіційно підтримує тільки англійську і російську, для української доводиться допрацьовувати кілька файлів.

Про те, як додати повноцінну підтримку українських літер (гліфи в шрифті, конвертація UTF-8, локалізація інтерфейсу) — окрема стаття: Українська локалізація yoradio: підтримка літер і переклад інтерфейсу. Там будуть готові модифіковані файли, які можна скачати і замінити у себе.

На завершення

Ось і все. У вас є повнофункціональне інтернет-радіо на ESP32, яким можна керувати з дисплея, енкодера, веб-інтерфейсу, а за бажанням — з мобільного застосунку через Home Assistant або з голосового помічника через MQTT.

Найпоширеніші місця, де новачки застряють, я перерахував по ходу тексту: не та версія Arduino IDE, забутий glcdfont.c, неправильна схема розділів, драйвер USB-UART, шлях через OneDrive. Якщо все це врахувати наперед — робота з yoradio виявляється досить приємною.

Якщо щось не пішло — офіційна вікі проекту https://github.com/e2002/yoradio/wiki має відповіді на більшість типових питань. Ще є чат користувачів у Telegram, обговорення на 4PDA, і Issues на GitHub.

Успіхів у збірці!