Bop is a source-only Spotify remote for the Waveshare ESP32-S3 Touch AMOLED 1.8 board.
It shows the current track and sends touch controls to Spotify. It does not play audio.
Use these gestures on the Bop screen:
| Gesture | Action |
|---|---|
| Swipe left | Previous track ⏮️ |
| Swipe right | Next track ⏭️ |
| Drag up | Increase volume 🔊 |
| Drag down | Decrease volume 🔉 |
| Short press | Play or pause |
| Long press | Show the Spotify screen with a QR code for the current track 🎵 |
Tap the Spotify screen to return to the current track.
Bop is source software for personal experimentation. It is not an official Spotify product.
This repository provides no firmware binary, package, GitHub Release, release tag, or shared Spotify client ID. You build the firmware and create your own Spotify application.
Spotify restricts Streaming integrations to its Approved Devices. Spotify terms do not clearly state how that restriction applies to a source-only ESP32 repository. Bop makes no claim of Spotify approval.
You need these items:
- A Waveshare ESP32-S3 Touch AMOLED 1.8 board.
- A USB data cable.
- A macOS, Linux, or Windows host computer.
- A WiFi network.
- A Spotify Premium account.
- Your own Spotify application and Client ID.
| Host | Support level |
|---|---|
| macOS | Hardware-tested installation |
| Linux | Firmware builds in CI |
| Windows | Host tools support it. Hardware installation is untested. |
CI runs on Linux only. Use macOS for the supported hardware procedure.
- Install Git and mise.
- Run
git clone https://github.com/markphelps/bop-esp32.git. - Run
cd bop-esp32. - Read INSTALL.md, EULA.md, and PRIVACY.md.
- Connect the board with a USB data cable.
- Run
mise install. - Run
mise run flashwithout--force. - Scan the QR code on Bop and join the Bop setup AP.
- Use the captive portal to save WiFi.
- Run the USB provisioning command,
mise run provision. - Enter the Spotify Client ID and complete Spotify authorization.
The first flash takes a credential-free factory backup. The captive portal then writes only the verified WiFi values.
The USB provisioning command queries the device state, then sends only the Spotify Client ID and refresh token. It never reads or rewrites WiFi values.
CAUTION: Do not use mise run flash -- --force for the first flash. It takes no backup. After portal setup, mise run provision cannot make its required credential-free backup.
If a valid backup exists, the backup task validates it and does not read the board. If an incomplete or invalid backup exists, the task stops. Move that backup out of backups/ before you try again.
If no backup exists, the task reads the credential partition first. It reads all flash only when the partition has no credentials.
- INSTALL.md gives the installation, update, removal, and factory-recovery procedures.
- docs/HOW-IT-WORKS.md explains the hardware, firmware, data flow, and every
misetask. - docs/TROUBLESHOOTING.md lists recovery steps for common device and provisioning problems.
- CONTRIBUTING.md explains the contribution workflow, checks, and pull-request requirements.
- SECURITY.md explains the security policy and the plaintext NVS credential risk.
- EULA.md and PRIVACY.md describe the terms and data use.
- THIRD_PARTY_LICENSES.md lists third-party components and their licenses.
Bop stores WiFi values, the Spotify Client ID, and the Spotify refresh token as plaintext in device NVS.
A person with physical access to the board can read these values. Read SECURITY.md before you provision the device.
Run mise run deprovision before you give away, sell, or discard the board. The command removes device credentials after you remove Bop access from Spotify.
Project code uses the Apache License 2.0. Read LICENSE.
The Montserrat font uses the SIL Open Font License. Read THIRD_PARTY_LICENSES.md.
Bop is an independent project. Spotify is a trademark of Spotify AB. Espressif, ESP32, and Waveshare are trademarks of their respective owners.