Skip to main content

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

1

Install Arduino IDE

Download and install the Arduino IDE (version 1.8.x or 2.x recommended).
2

Add ESP32 board support

Open Arduino IDE and navigate to File → Preferences. Add this URL to “Additional Board Manager URLs”:
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
Then go to Tools → Board → Boards Manager, search for “esp32”, and install the ESP32 board package.
3

Verify 2.4 GHz WiFi network

The ESP32 only supports 2.4 GHz WiFi networks, not 5 GHz. Ensure you have access to a 2.4 GHz network.
If your router only broadcasts on 5 GHz, you’ll need to enable the 2.4 GHz band or use a different network.

Installation

1

Clone the repository

Open your terminal and clone the Spotify MacroBoard repository:
git clone https://github.com/Leg3ndary/SpotifyMacroBoard.git
cd SpotifyMacroBoard
2

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.
3

Configure your credentials

Navigate to the src/ directory and create a file named SMBCredentials.h based on the SampleCredentials.h template:
const String PASSWORD = "your_server_password";

const char SSID[] = "YourWiFiNetwork";
const char SSID_PASS[] = "YourWiFiPassword";

const char *benzServerCert =
    "-----BEGIN CERTIFICATE-----\n"
    "YOUR_SERVER_SSL_CERTIFICATE_HERE\n"
    "-----END CERTIFICATE-----";
You’ll also need to include your pin definitions and display settings:
#define RGB_PIN 18
#define RGB_LED_NUM 20
#define BRIGHTNESS 230
#define CHIP_SET WS2812B
#define COLOR_CODE GRB

#define SHUFFLE 4
#define VOLUME_DEC 5
#define VOLUME_INC 12
#define LOOP 13
#define BACK 14
#define PAUSE_PLAY 25
#define SKIP 26

#define SCL 19
#define SDA 21
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
Never commit your credentials file to version control. The .gitignore file should exclude your credentials.

Configure Arduino IDE

1

Open the sketch

In Arduino IDE, open the file src/src.ino from your cloned repository.
2

Select your board

Go to Tools → Board → ESP32 Arduino and select ESP32 Dev Module.
3

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.
4

Select your port

Connect your ESP32 to your computer via USB, then select the appropriate port from Tools → Port.
If you don’t see a port, you may need to install CH340 or CP2102 USB drivers depending on your ESP32 board.

Upload and test

1

Verify the code

Click the checkmark icon (Verify) to compile the code. The compilation should complete with:
Sketch uses 886189 bytes (67%) of program storage space.
Global variables use 45808 bytes (13%) of dynamic memory.
This confirms all libraries are installed correctly.
2

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:
Connecting........_____.....
If the upload fails, try holding the BOOT button on your ESP32 when you see “Connecting…”.
3

Observe the LED behavior

After successful upload, the ESP32 will restart. Watch the LED behavior:
  1. White LEDs - Initial startup (src.ino:59)
  2. Pulsing white - Connecting to WiFi (src.ino:79-87)
  3. Fade to green - Successfully connected (src.ino:89-95)
  4. Red LEDs - Connection failed
// WiFi connection indication
while (WiFi.status() != WL_CONNECTED) {
    for (int times = 0; times < 20; times++) {
        for (int i = 0; i < RGB_LED_NUM; i++) {
            byte brightness = 140 + 110 * sin(millis() / 250.0);
            LEDs[i] = CRGB::White;
            LEDs[i].fadeToBlackBy(255 - brightness);
        }
        delay(25);
        FastLED.show();
    }
}
4

Check the OLED display

If everything is working correctly, the OLED display should show:
  • WiFi signal strength indicator (top left)
  • Volume level indicator (top right)
  • Current track title (center)
  • Artist name (below title)
  • Playback progress bar (bottom)
If the LEDs turn orange-red on startup, the OLED display failed to initialize. Check your I2C connections on pins 19 (SCL) and 21 (SDA).

Test the controls

1

Verify button mapping

Test each button to ensure it’s working correctly:
Button PinFunctionDescription
GPIO 4ShuffleToggle shuffle mode
GPIO 5Volume DownDecrease volume
GPIO 12Volume UpIncrease volume
GPIO 13LoopToggle repeat mode
GPIO 14BackPrevious track
GPIO 25Play/PauseToggle playback
GPIO 26SkipNext track
2

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
3

Verify LED color sync

When a new track plays, the RGB LEDs should smoothly fade to colors extracted from the album artwork. The fade animation takes approximately 1 second (256 steps at 4ms intervals).
bool fadeLED() {
    if (step > 255) {
        step = 0;
        return false;
    }
    for (int i = 0; i < RGB_LED_NUM; i++) {
        LEDs[i] = blend(CRGB(prevRed, prevGreen, prevBlue),
                        CRGB(red, green, blue), step);
    }
    FastLED.show();
    step += 1;
    return true;
}

Troubleshooting

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?
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
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
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)
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
If button presses don’t trigger actions:
  • Verify switches are properly connected to GPIO pins
  • Check that pins are configured as INPUT_PULLUP (src.ino:45-47)
  • Test individual pins with a multimeter
  • Ensure switches are normally-open type

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

Build docs developers (and LLMs) love