Quick start

Get your Spotify MacroBoard up and running with this step-by-step guide

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

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

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

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

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

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

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

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