A little radio for the whole world.
Firmware that turns an ESP32-S3 board into an internet radio playing the 60,000 stations of
airdrift.stream: on a Waveshare board with a round touch screen,
or on a dev board with a knob, two speakers and some soldering.
Plug a speaker into a £20 board, give it your WiFi, and it plays live radio from almost every country on earth. No account, no app, no subscription: the stations come from Air Drift, a free directory of internet radio, and play straight from their own streams.
Press Drift and it lands on a station somewhere on Earth. Left alone while it plays, the screen becomes a visualiser: the music radiating from the song's cover, with the station and the song running round the rim. The radio has its own web page on your network for searching and picking stations from a phone or laptop, remembers what it was playing, saves favourites to flash, and updates its own firmware over WiFi.
Install it from your browser: plug the board in by USB, press one button in Chrome or Edge, and it is a radio.
- What you get
- The two radios
- Quick start
- The screen
- The web page
- First boot
- Updating the firmware
- The custom build
- Build and flash
- Serial console
- API
- How it fits Air Drift
- Development
- Contributing
- Air Drift everywhere else
- Credits
- Use at your own risk
- Licence
- 60,000 stations, the Air Drift directory: Popular and Trending lists, every country, 160 genres, and search by name. The lists come as single static files from the site, so browsing costs one request and playing costs none.
- Any stream. Paste an
airdrift.stream/listen/…link or a plain stream URL on the web page. MP3, AAC and HLS, plus FLAC, Opus and Vorbis through the decoder library. - Now playing from the stream's own title, on the screen and on the page.
- Favourites saved to flash: a star on the screen, on the page, and at the end of every list row.
- A touch screen that does the whole job on the Waveshare board: pick a station, save it, change the volume, see what is on. Nothing else is needed once it is online.
- A branded web page at
http://airdrift.localwith the lists, search, transport, volume and favourites, and a Device tab with the board, memory, WiFi signal, CPU load per core, chip temperature, the audio pipeline and the task list. - WiFi setup from a phone: the screen shows a QR code, the phone joins the radio's setup network, and an Air Drift setup page opens by itself, like hotel WiFi.
- Firmware updates over WiFi from the Device tab, or with one script.
- Remembers the last station and volume and resumes after a power cut; reconnects a dropped stream on its own.
- A serial console for anyone who prefers typing, and a JSON API for everyone else: Home Assistant, a shortcut on a phone, a cron job.
- Private. No account, no telemetry. The radio talks to airdrift.stream for lists, to Radio Browser for search and play counts, and to the station you are listening to.
One codebase, two PlatformIO environments.
| The self-contained unit | The custom build | |
|---|---|---|
| Env | waveshare-185 |
devkit (devkit-quad for quad PSRAM) |
| Board | Waveshare ESP32-S3-Touch-LCD-1.85, either revision | ESP32-S3-DevKitC-1 with PSRAM (N16R8 is the usual one) |
| Sound | the board's own codec and amplifier; plug a speaker into its header | a PCM5102A DAC into a TPA3116D2 amplifier and two speakers |
| Controls | the round 360×360 touch screen | a rotary encoder (volume, push for play/pause) and two buttons |
| Setup | by QR code on the screen | from the serial console, or the same setup network |
| Soldering | none | yes, see The custom build |
Both are driven the same way from the web page, the console and the API, and both play the same stations.
Nothing to build. The easiest way is the installer at airdrift.stream/esp32: plug the board in by USB, open the page in Chrome or Edge on a computer, press Install on my board and pick its port. It writes the newest release, for either board.
Or from a terminal: every release on the Releases page has a ready-made image for each board, and the newest is always at the same address. For the Waveshare board, plug it in by USB and write it at address 0 with esptool:
pip install esptool
curl -LO https://github.com/Air-Drift/ESP32-S3/releases/latest/download/airdrift-waveshare-185-full.bin
esptool --chip esp32s3 --baud 921600 write-flash 0x0 airdrift-waveshare-185-full.binThat one file holds the bootloader, the partition table and the firmware, so it works on a board that has never seen Air Drift. It is a fresh start: a radio that already had WiFi forgets it (favourites survive), which is why a radio that is already running Air Drift updates from its Device tab instead. When the screen lights up, follow it: scan the QR code with your phone, pick your WiFi, done. From then on the radio is at http://airdrift.local on your network and on its own screen, and later releases install from its Device tab without a cable.
For the custom build, the same with airdrift-devkit-full.bin
(or airdrift-devkit-quad-full.bin for a board with quad PSRAM), then see
First boot. To build from source instead, see
Build and flash.
The Waveshare board's round screen is the whole interface. It draws in Air Drift's own palette, with the volume on a ring around the edge and the battery in the ring's gap at the bottom.
| Home. The station and its country, volume down and up, and Drift: a random country, weighted by how many stations it has, and one of its most played. A station that does not answer is drifted on from. While a drift tunes, the button greys out. Swipe left or right for the next or previous station in the drift. | Visualiser. Left alone while it plays, the screen becomes the music: a spectrum radiating from the song's cover (found on MusicBrainz and the Cover Art Archive), else the station's logo, with the station, its country and the song running round the rim. A touch brings home back. In low power mode the screen sleeps instead. | Favourites. Three to a page: tap a row to play it, its star to drop it, the arrows (or a swipe up or down) to page. The station playing, if it is not saved yet, waits at the top to be added. |
| The button. The button on the side pauses the music and opens a menu: Resume (or press the button again; Close when nothing was playing), New WiFi to set up another network, Reset device. The last two ask for a second tap. | Remote. Searching needs a keyboard, so Remote shows a QR code for the radio's web page. Pick a station there and the screen goes home with it. | Let's get you online. With no WiFi stored, a QR code that joins the radio's setup network. See First boot. |
Volume buttons repeat while held. A tap on the logo always leads home; holding it shows the connect screen, with the page's address, the WiFi signal and the firmware version. Plugged in to charge, the radio starts on a charge screen rather than playing; a touch or the button starts the radio.
Every radio serves its own page at http://airdrift.local (or its IP),
styled like the site, light or dark with the phone. Station logos load in
the browser from their own hosts, never through the radio.
A third tab, Apps, links Air Drift's apps for phones, computers, TVs and Alexa. The page is plain HTML and JavaScript served from flash: one file, no build step, no framework. Anything it does, the API does too.
The Waveshare unit walks you through it on its screen:
- With no WiFi stored it shows Let's get you online and a QR code. Scan it with a phone to join the Air Drift Setup network (or join it from WiFi settings), and the setup page opens by itself. It lists the networks in range, strongest first; pick yours, type the password, Connect. The screen says "Joining…", then the setup network switches itself off.
- Once online, press Drift. Remote shows a QR code for the radio's
own web page, with the address in words (
airdrift.local), for searching. - For a new network, press the button on the side and pick New WiFi: it starts over at step 1. Reset device there forgets WiFi, favourites and the last station too, for moving house or handing it on.
The custom build has no screen, so:
- Open the serial monitor (
pio device monitor, 115200). The radio prints its state; typehelp. - Give it WiFi: join the Air Drift Setup network from a phone and pick your
network on the page that opens, or type
wifi <ssid> <password>(quote a name with spaces). - It prints its address. Open http://airdrift.local on a phone or laptop on the same network and pick a station.
With a bare dev board and no DAC wired, everything except the sound works: the lists load, the stream opens, the titles print.
The radio updates itself. Open its page, Device tab: it asks the
Releases page what the
newest version is and, if that is newer than what it runs, offers
Install it. The radio downloads the firmware straight from GitHub, shows
the progress on its screen, writes it to its spare app partition, checks it
and restarts on it; the page reconnects when it is back. About a minute in
all. Keep the power on. On the console, update checks and update now
installs.
The same tab takes an upload of your own build (firmware.bin, which
PlatformIO leaves in .pio/build/<env>/, or a release's
airdrift-<board>.bin).
From a shell, one step:
scripts/ota.sh waveshare-185 # build and send to airdrift.local
scripts/ota.sh devkit 192.168.1.50 # or to an addressOver USB, scripts/flash.sh still works and also resets the boot selector
to the first partition.
Releases are built by GitHub Actions: a push to main that touches the
firmware, with a new version in include/config.h, builds every board and
publishes the images under a v<version> tag. A change to the README, or
code without a version bump, builds nothing. scripts/release-images.sh
makes the same images locally in dist/.
An ESP32-S3 dev board, a PCM5102A DAC, a TPA3116D2 amplifier and two small speakers, all fed from one USB-C PD charger.
| Part | Notes |
|---|---|
| ESP32-S3 dev board with PSRAM | The decoder refuses to start without PSRAM. N16R8 (16 MB flash, 8 MB octal PSRAM) is the common one; N8R2 also works with the devkit-quad build. |
| PCM5102A DAC (GY-PCM5102) | I2S in, stereo line out. |
| TPA3116D2 amplifier board | Takes the DAC's line out; 12–24 V supply; its own volume pots. |
| Two 4 Ω speakers | 78 mm, 15 W. |
| USB-C PD trigger board, set to 20 V | Pulls 20 V from a 30 W PD charger for the amplifier. |
| MP1584EN buck converter, trimmed to 5 V | Feeds the ESP32 from the same 20 V. |
| EC11 rotary encoder with push switch | Volume, and play/pause on the push. |
| Two tact switches | Next and previous. |
| Later: 3.5" ILI9488 touch display | GPIO 8–14 are kept free for it. |
A MAX98357A (DAC and 3 W mono amp in one, speaker wired straight to it) is the simpler alternative: the same three I2S wires, no amplifier board.
Defaults in include/config.h; any free GPIO works on the S3, but avoid the
strapping pins (0, 3, 45, 46) and the USB pins (19, 20).
| PCM5102A pin | ESP32-S3 pin | config.h |
|---|---|---|
| BCK | GPIO 5 | PIN_I2S_BCLK |
| LCK | GPIO 6 | PIN_I2S_LRC |
| DIN | GPIO 7 | PIN_I2S_DOUT |
| SCK | GND | |
| VIN | 5V (3V3 also works) | |
| GND | GND |
The GY-PCM5102 has four solder jumpers on the back and stays muted until they are set: 1 = L, 2 = L, 3 = H, 4 = L. Many ship unset.
DAC line out (L, GND, R) to the amplifier's input header, speakers on the amplifier's L and R terminals, and the amplifier's power terminals on the 20 V from the PD trigger. The buck converter takes the same 20 V down to 5 V for the ESP32's 5V pin; set it with a meter before connecting the board. All grounds are common.
| Control | ESP32-S3 pin | config.h |
|---|---|---|
| Encoder A | GPIO 15 | PIN_ENC_A |
| Encoder B | GPIO 16 | PIN_ENC_B |
| Encoder common (middle of the three) | GND | |
| Encoder push switch | GPIO 17 | PIN_BTN_PLAY (play / pause) |
| Encoder switch, other side | GND | |
| Next button | GPIO 18 to GND | PIN_BTN_NEXT |
| Previous button | GPIO 4 to GND | PIN_BTN_PREV |
Internal pull-ups, no resistors.
PlatformIO does everything, on the pioarduino platform so the Arduino core is 3.x, which the audio library needs.
| Env | Board |
|---|---|
waveshare-185 |
Waveshare ESP32-S3-Touch-LCD-1.85 and 1.85C |
devkit (default) |
DevKitC with octal PSRAM: N16R8, N8R8 |
devkit-quad |
DevKitC with quad PSRAM: N8R2, N4R2 |
scripts/flash.sh waveshare-185 [/dev/ttyACM0] # build, verify the image, flash over USB
scripts/ota.sh waveshare-185 [airdrift.local] # build, verify, send over WiFi
pio run -e devkit # just build
pio device monitor # the serial console, 115200To find out which PSRAM a DevKitC has, read the Embedded PSRAM line of
pio pkg exec -- esptool.py --port /dev/ttyACM0 flash_id. With the wrong env
the radio boots but prints no PSRAM.
Linux needs permission on the serial port once: copy
udev/99-airdrift-esp32.rules to /etc/udev/rules.d/ and run
sudo udevadm control --reload-rules && sudo udevadm trigger, or add
yourself to the dialout group and log in again.
If pio run fails with a Python AttributeError or TypeError from
inside PlatformIO itself, run it again: PlatformIO 6.2 has an intermittent
fault in its library builder, and the scripts already retry. The image it
writes can also come out with a bad checksum, so the scripts rebuild it from
the ELF and check it with esptool before flashing.
The Waveshare board has two revisions and the firmware tells them apart at boot by what answers on the I2C bus:
| DAC | Amplifier enable | Touch bus | |
|---|---|---|---|
| 1.85 | PCM5101, plain I2S | always on | its own (GPIO 1/3) |
| 1.85C | ES8311 codec at 0x18, needs register setup and MCLK | GPIO 15 | the system bus (GPIO 10/11) |
wifi <ssid> <password> join a network
forget erase WiFi and restart into setup
factory erase WiFi, favourites and the last station, then restart
popular | trending load that list from airdrift.stream
favourites load the saved stations
country <CC> load a country, e.g. country GB
genre <name> load a genre, e.g. genre jazz
search <words> search stations by name
list show the loaded list
play <n> play station n from the list
play <air drift link> play a shared https://airdrift.stream/listen/... link
play <stream url> play any stream
next | prev | pause | stop
vol <0-21>
fav save or unsave the playing station
resample on|off 48 kHz output through the library's resampler (off: it falls behind)
core 0|1 which CPU core decodes
debug on|off show the decoder's own messages
update [now] check the project's releases for a newer firmware; now installs it
screen the screen as a BMP in base64, between marker lines
ui <name> show a screen for a screenshot: home empty list about phone setup busy; ui off
status | help | reboot
Everything the page does is a plain HTTP call, so anything on the network can
drive the radio: a Home Assistant rest_command, a shortcut on a phone, a
button on a desk.
| Call | Does |
|---|---|
GET /api/state |
playing, station, title, codec, volume, favourite, list source |
GET /api/list |
the loaded list |
GET /api/load?source=popular |
load a list: favourites, popular, trending, country:US, tag:jazz |
GET /api/search?q=words |
search by name |
GET /api/play?i=3 |
play the n-th station of the loaded list |
GET /api/play?link=… |
play a shared airdrift.stream/listen/<id> link, or any stream URL |
GET /api/stop, /api/pause, /api/next, /api/prev |
transport (pause toggles) |
GET /api/volume?v=0..21 |
volume |
GET /api/fav |
save or unsave the playing station |
GET /api/device |
board, chip, memory, WiFi, CPU load per core, audio pipeline, task list |
GET /api/update/check |
the newest release's version, and whether it is newer than this |
GET /api/update/install |
download the newest release from GitHub and restart on it |
POST /api/update |
the firmware image as a multipart file field: curl -F firmware=@firmware.bin |
GET /screen.bmp |
the screen right now (boards with a screen) |
curl "http://airdrift.local/api/load?source=tag:jazz"
curl "http://airdrift.local/api/play?i=0"
curl "http://airdrift.local/api/volume?v=10"The radio is a client of the site, nothing more: no servers of its own.
| On the site | On the radio |
|---|---|
data/v1/popular.json, trending.json |
the Popular and Trending lists |
data/v1/country/XX.head.json |
one country, first page of stations |
data/v1/index.json + data/v1/tag/<file>.head.json |
one genre |
| live search on Radio Browser | search |
/listen/<id> links |
paste to play |
| play report to Radio Browser | sent on every play, so what the radio plays counts in the rankings (REPORT_PLAYS turns it off) |
| ICY stream title | "now playing" |
css/app.css palette, icons/icon.svg |
the screen's and the page's colours and logo |
The radio keeps at most MAX_STATIONS (60) of any list in RAM, fetches only
when asked, and is one request per list and none while playing.
platformio.ini boards, envs, libraries
include/config.h pins and defaults, per board
src/main.cpp boot and the main loop
src/net.* WiFi, the setup portal, mDNS
src/directory.* the station lists, search, links, play reports
src/player.* the decoder and I2S output, on its own task
src/display.* the Waveshare screen and touch (empty on the devkit)
src/boards/es8311.h the 1.85C's codec bring-up
src/boards/waveshare185_init.h the panel's init table
src/webui.* the web page and JSON API, firmware upload
src/updater.* firmware from the project's releases, on request
src/console.* serial commands
src/controls.* buttons and encoder
src/favourites.* saved stations, in LittleFS
src/devinfo.* what the Device tab shows
src/icons.h the page's icons, from the site
docs/ banner, screenshots, fonts for the banner
scripts/flash.sh build, re-image and flash over USB
scripts/ota.sh build and send over WiFi
udev/ serial port permissions for Linux
How the screen is driven. ESP-IDF's esp_lcd SPI panel IO in quad mode,
the way Waveshare's own demo does it (the Arduino_GFX QSPI bus garbles this
panel). Drawing goes into an Arduino_GFX canvas in PSRAM for its fonts and
shapes, and the frame is pushed in row chunks through internal DMA buffers
whenever something changes. Touch is a CST816; the firmware polls it while a
finger is down because its interrupt line goes quiet under a still finger.
How the audio stays smooth. Opening a stream, the play report, and the
decoder all run off the main loop, which only draws, reads the touch and
answers the web page. Streams play at their own sample rate: the library's
resampler falls behind real time (resample on to hear it).
Screenshots in this README are the real thing: GET /screen.bmp returns
the framebuffer, and the console's ui <name> shows any screen on demand, so
ui setup captures the setup screen without forgetting the WiFi. The
screen command prints the same image in base64 over USB for when there is
no WiFi at all. docs/banner.html is the banner, rendered with headless
Chromium.
Libraries: ESP32-audioI2S (decoding and I2S), ArduinoJson, WiFiManager (the access point and captive portal; the pages are Air Drift's own), and for the screen Arduino_GFX with U8g2's fonts and QRCode.
- The custom build's 3.5" ILI9488 touch display (SPI, FT6236 touch).
- A case for the custom build, and a board layout once the parts are settled.
- A "play on my radio" hand-off from the site, if the site ever gains a way to reach a device on the LAN.
Found a bug, or want to add something? Pull requests are welcome.
- Fixes and features: fork the repository, make the change on a branch and
open a pull request against
main. Both envs should still build (pio run -e waveshare-185 && pio run -e devkit). - Bugs you cannot fix yourself: open an issue with the board, the firmware version from the Device tab, and what the serial console printed.
- Other boards: a port to another ESP32-S3 board with a screen or a DAC
is mostly a new block in
include/config.hand, for a screen, an init table insrc/boards/. A pull request that adds one is very welcome.
Contributions are accepted under the project's MIT licence.
Air Drift is a free internet radio player: a globe of more than 60,000 live stations, no account, no adverts of its own. The same stations that are on this radio are available on:
| Web | airdrift.stream, in any browser, installable as an app |
| iPhone, iPad, Apple TV, Apple Watch, CarPlay | Air Drift on the App Store |
| Android and Android Auto | Air Drift on Google Play |
| Amazon Fire TV and Fire tablets | Air Drift on the Amazon Appstore |
| Amazon Alexa and Echo | "Alexa, open Air Drift" |
| Windows | Air Drift on the Microsoft Store |
| Bose SoundTouch speakers | Air Drift for SoundTouch, the preset buttons playing again |
All of them are listed at airdrift.stream/apps.
- ESP32-audioI2S by Wolle, which does the hard part: every codec, over the network, on a microcontroller.
- Radio Browser, the community directory that Air Drift's lists are built from.
- Waveshare, for the ESP32-S3-Touch-LCD-1.85 wiki and demos, where the panel's init sequence and the codec's registers come from.
- tzapu's WiFiManager, ArduinoJson, Arduino_GFX, U8g2 and QRCode.
This software is provided as is, with no warranty of any kind. It drives hardware: a speaker amplifier, a display, and on the custom build a 20 V supply you wire yourself. It has been written with care, but you run it at your own risk: the authors accept no liability for any damage, loss of settings, loss of service or other harm that comes from using it, or from building the hardware described here. Check your wiring with a meter before you power it. The full terms are in the licence.
The code is released under the MIT licence: use it, change it and share it freely, with no warranty and no liability on the authors.
The licence covers the code, not the brand. The Air Drift name, logo and wordmark are trademarks of the Air Drift project, with all rights reserved: you may build and run this firmware with its branding as it comes, but a modified version that you publish needs its own name and mark. The terms are in TRADEMARKS.md.
The fonts in docs/fonts are Archivo and IBM Plex Mono, under the SIL Open
Font Licence (included beside them); they are only used to draw the banner.
Air Drift for ESP32-S3 is an independent project. It is not affiliated with, endorsed by or supported by Waveshare or Espressif. Their names are used only to say what this firmware runs on.
Made by Air Drift, free internet radio from everywhere.