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

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

<Note>
  Before you begin, ensure you have an ESP32 development board and the Arduino IDE installed on your computer.
</Note>

## Prerequisites

<Steps>
  <Step title="Install Arduino IDE">
    Download and install the [Arduino IDE](https://www.arduino.cc/en/software) (version 1.8.x or 2.x recommended).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.

    <Warning>
      If your router only broadcasts on 5 GHz, you'll need to enable the 2.4 GHz band or use a different network.
    </Warning>
  </Step>
</Steps>

## Installation

<Steps>
  <Step title="Clone the repository">
    Open your terminal and clone the Spotify MacroBoard repository:

    ```bash theme={null}
    git clone https://github.com/Leg3ndary/SpotifyMacroBoard.git
    cd SpotifyMacroBoard
    ```
  </Step>

  <Step title="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

    <Info>
      Search for each library name in the Library Manager and click "Install". Make sure to install any dependencies when prompted.
    </Info>
  </Step>

  <Step title="Configure your credentials">
    Navigate to the `src/` directory and create a file named `SMBCredentials.h` based on the `SampleCredentials.h` template:

    ```cpp theme={null}
    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:

    ```cpp theme={null}
    #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
    ```

    <Warning>
      Never commit your credentials file to version control. The `.gitignore` file should exclude your credentials.
    </Warning>
  </Step>
</Steps>

## Configure Arduino IDE

<Steps>
  <Step title="Open the sketch">
    In Arduino IDE, open the file `src/src.ino` from your cloned repository.
  </Step>

  <Step title="Select your board">
    Go to **Tools → Board → ESP32 Arduino** and select **ESP32 Dev Module**.
  </Step>

  <Step title="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

    <Info>
      These settings match the configuration in `.vscode/arduino.json:2` and ensure optimal performance.
    </Info>
  </Step>

  <Step title="Select your port">
    Connect your ESP32 to your computer via USB, then select the appropriate port from **Tools → Port**.

    <Tip>
      If you don't see a port, you may need to install CH340 or CP2102 USB drivers depending on your ESP32 board.
    </Tip>
  </Step>
</Steps>

## Upload and test

<Steps>
  <Step title="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.
  </Step>

  <Step title="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........_____.....
    ```

    <Note>
      If the upload fails, try holding the BOOT button on your ESP32 when you see "Connecting...".
    </Note>
  </Step>

  <Step title="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

    ```cpp theme={null}
    // 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();
        }
    }
    ```
  </Step>

  <Step title="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)

    <Warning>
      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).
    </Warning>
  </Step>
</Steps>

## Test the controls

<Steps>
  <Step title="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 |
  </Step>

  <Step title="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
  </Step>

  <Step title="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).

    ```cpp theme={null}
    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;
    }
    ```
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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?
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Next steps

Now that you have a working Spotify MacroBoard, explore these guides:

<CardGroup cols={2}>
  <Card title="Hardware assembly" icon="screwdriver-wrench" href="/hardware/assembly">
    Build the custom PCB and assemble the complete macroboard
  </Card>

  <Card title="Server setup" icon="server" href="/api/server-setup">
    Set up your personal Spotify API server backend
  </Card>

  <Card title="Code overview" icon="code" href="/software/code-overview">
    Understand the code structure and key functions
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/reference/troubleshooting">
    Detailed troubleshooting guide for common issues
  </Card>
</CardGroup>