Documentation Index
Fetch the complete documentation index at: https://mintlify.com/benz206/SpotifyMacroBoard/llms.txt
Use this file to discover all available pages before exploring further.
Get started in minutes
This guide will walk you through setting up your Spotify MacroBoard from cloning the repository to uploading code to your ESP32.Before you begin, ensure you have an ESP32 development board and the Arduino IDE installed on your computer.
Prerequisites
Install Arduino IDE
Download and install the Arduino IDE (version 1.8.x or 2.x recommended).
Add ESP32 board support
Open Arduino IDE and navigate to File → Preferences. Add this URL to “Additional Board Manager URLs”:Then go to Tools → Board → Boards Manager, search for “esp32”, and install the ESP32 board package.
Installation
Install required libraries
Install the following libraries using the Arduino IDE Library Manager (Sketch → Include Library → Manage Libraries):
- Adafruit GFX Library - Graphics core library for displays
- Adafruit SSD1306 - Driver for SSD1306 OLED displays
- FastLED - High-performance LED control library
- WiFiClientSecure - Built-in ESP32 library for HTTPS
Search for each library name in the Library Manager and click “Install”. Make sure to install any dependencies when prompted.
Configure Arduino IDE
Configure board settings
Set the following board configuration (Tools menu):
- Flash Frequency: 80 MHz
- Flash Mode: QIO
- Flash Size: 4MB
- Partition Scheme: Default
- CPU Frequency: 240 MHz
- Upload Speed: 921600
These settings match the configuration in
.vscode/arduino.json:2 and ensure optimal performance.Upload and test
Verify the code
Click the checkmark icon (Verify) to compile the code. The compilation should complete with:This confirms all libraries are installed correctly.
Upload to ESP32
Click the arrow icon (Upload) to upload the code to your ESP32. The upload process should take about 30-60 seconds.During upload, you may see:
If the upload fails, try holding the BOOT button on your ESP32 when you see “Connecting…”.
Observe the LED behavior
After successful upload, the ESP32 will restart. Watch the LED behavior:
- White LEDs - Initial startup (src.ino:59)
- Pulsing white - Connecting to WiFi (src.ino:79-87)
- Fade to green - Successfully connected (src.ino:89-95)
- Red LEDs - Connection failed
Test the controls
Verify button mapping
Test each button to ensure it’s working correctly:
| Button Pin | Function | Description |
|---|---|---|
| GPIO 4 | Shuffle | Toggle shuffle mode |
| GPIO 5 | Volume Down | Decrease volume |
| GPIO 12 | Volume Up | Increase volume |
| GPIO 13 | Loop | Toggle repeat mode |
| GPIO 14 | Back | Previous track |
| GPIO 25 | Play/Pause | Toggle playback |
| GPIO 26 | Skip | Next track |
Monitor track information
The display updates every 5 seconds with current track info (src.ino:396). When you change tracks, you should see:
- Track title and artist update
- LEDs smoothly fade to new album colors (src.ino:292-304)
- Progress bar reset to beginning
Troubleshooting
LEDs stay red after upload
LEDs stay red after upload
Red LEDs indicate a server connection failure. Check:
- Is your server running and accessible?
- Is the server certificate correct in
SMBCredentials.h? - Can you ping your server from your network?
- Is port 443 (HTTPS) open on your server?
LEDs turn yellow during operation
LEDs turn yellow during operation
Yellow LEDs indicate a server timeout (src.ino:225). The ESP32 waited more than 5 seconds for a response. Check:
- Server response time
- Network latency
- Server load
LEDs turn orange during operation
LEDs turn orange during operation
Orange LEDs indicate the HTTP response headers couldn’t be found (src.ino:234). This suggests:
- Malformed server response
- Connection interrupted mid-response
- Server not following HTTP/1.1 protocol
Display shows only WiFi/volume icons
Display shows only WiFi/volume icons
If the display doesn’t show track information:
- Verify your server is returning track data
- Check that Spotify is actively playing music
- Ensure the API credentials on your server are valid
- Wait up to 5 seconds for the first update (src.ino:395-398)
Can't connect to WiFi
Can't connect to WiFi
If LEDs pulse white indefinitely:
- Verify SSID and password in
SMBCredentials.h - Confirm your network is 2.4 GHz (not 5 GHz)
- Check router settings for MAC address filtering
- Try moving closer to the router
Buttons don't respond
Buttons don't respond
Next steps
Now that you have a working Spotify MacroBoard, explore these guides:Hardware assembly
Build the custom PCB and assemble the complete macroboard
Server setup
Set up your personal Spotify API server backend
Code overview
Understand the code structure and key functions
Troubleshooting
Detailed troubleshooting guide for common issues