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.

​
Architecture overview

The Spotify MacroBoard uses a three-tier architecture to communicate with the Spotify API: 
ESP32 MacroBoard → Personal Server (benzhou.tech) → Spotify Web API
This proxy architecture provides several key benefits:
  • Performance: The personal server caches authentication tokens and handles OAuth flows, eliminating the need for the ESP32 to manage complex authentication
  • Security: Sensitive credentials (client ID, client secret, refresh tokens) are stored on the server, not hardcoded in the ESP32
  • Simplicity: The ESP32 only needs to make simple HTTPS GET requests with a password parameter
  • Speed: Server-side caching and connection pooling significantly reduces response times

​
Communication flow

​
Control actions

When you press a button on the MacroBoard:
  1. ESP32 detects the button press (src/src.ino:381-387)
  2. ESP32 sends an HTTPS GET request to /api/manageState/{password}/{action}
  3. Personal server receives the request and validates the password
  4. Personal server makes an authenticated request to Spotify Web API
  5. Spotify processes the action (play/pause, skip, volume change, etc.)
  6. Server returns a response to the ESP32

​
State synchronization

The MacroBoard polls for current playback state every 5 seconds:
  1. ESP32 sends a request to /api/getCurrent/{password} (src/src.ino:395-398)
  2. Personal server queries Spotify’s current playback endpoint
  3. Server returns JSON with track info, playback state, and album art color
  4. ESP32 updates the OLED display and RGB LEDs (src/src.ino:247-289)
The 5-second polling interval (defined by currentDelay at src/src.ino:25) balances real-time updates with ESP32 power consumption and API rate limits.

​
HTTPS certificate authentication

The ESP32 uses certificate-based HTTPS to ensure secure communication with the personal server: 
WiFiClientSecure wifiClient;
wifiClient.setCACert(benzServerCert);
The certificate is defined in SampleCredentials.h and must match the SSL certificate installed on your personal server. This prevents man-in-the-middle attacks and ensures the ESP32 only communicates with your trusted server.
If you change your server’s SSL certificate, you must update the benzServerCert constant in your credentials file and re-upload the code to the ESP32.

​
Connection management

The ESP32 maintains a persistent HTTPS connection using HTTP Keep-Alive: 
if (!wifiClient.connected()) {
    if (!wifiClient.connect("benzhou.tech", 443)) {
        // Connection failed - show red LEDs
        for (int i = 0; i < RGB_LED_NUM; i++) LEDs[i] = CRGB::Red;
        FastLED.show();
        return;
    }
}
This approach minimizes TLS handshake overhead by reusing the same connection for multiple requests. If the connection drops, the ESP32 automatically reconnects on the next request.

​
Error handling

The MacroBoard provides visual feedback for different error conditions:
LED colorMeaningLocation
RedFailed to connect to serversrc/src.ino:196, 211
YellowRequest timeout (>5 seconds)src/src.ino:225
OrangeInvalid response formatsrc/src.ino:234
Orange-redOLED display initialization failedsrc/src.ino:65

​
Password authentication

All API requests include a password parameter defined in your credentials file: 
const String PASSWORD = "your-password-here";
The personal server validates this password before forwarding requests to Spotify. This provides basic authentication without requiring OAuth on the ESP32.
The password is sent over HTTPS, so it’s encrypted in transit. However, make sure to use a strong, unique password that’s different from your Spotify credentials.

​
Next steps

Server setup

Learn how to set up your personal proxy server

API endpoints

Detailed reference for all API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us