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.

LED error indicators

The MacroBoard uses LED colors to indicate different error states during operation.
When LEDs display an error color, the device has encountered a problem that requires attention.

OrangeRed LEDs (solid)

Problem: OLED display initialization failed Location: src.ino:63-71 Cause:
  • Display not connected to I2C pins
  • Wrong I2C address (should be 0x3C)
  • Faulty display module
  • I2C pins (GPIO 19/21) not properly connected
Solutions:
  1. Verify SDA is connected to GPIO 21
  2. Verify SCL is connected to GPIO 19
  3. Ensure display VCC is connected to 3.3V or 5V
  4. Ensure display GND shares common ground with ESP32
  5. Check for loose wires or poor solder joints
Use an I2C scanner sketch to detect the display’s actual address:
Wire.begin(21, 19);
Wire.beginTransmission(0x3C);
byte error = Wire.endTransmission();
If the address differs from 0x3C, update the code in src.ino:63.
  1. Try the display with a simple Adafruit_SSD1306 example sketch
  2. If it doesn’t work, the module may be defective
  3. Replace with a known working SSD1306 display

Red LEDs (solid)

Problem: Cannot connect to server Location: src.ino:196, src.ino:211 Cause:
  • Server benzhou.tech is unreachable
  • Port 443 (HTTPS) is blocked by firewall
  • WiFi connection lost
  • SSL certificate mismatch
Solutions:
  1. Verify ESP32 is connected to WiFi (green LEDs during setup)
  2. Check router firewall settings
  3. Ensure WiFi network has internet access
  4. Try pinging benzhou.tech from another device on the same network
Open a web browser and try accessing:
https://benzhou.tech/api/getCurrent/YOUR_PASSWORD
If this fails, the server may be down or the API endpoint has changed.
The server’s SSL certificate may have been renewed. Generate a new certificate:
  1. Visit https://benzhou.tech in Chrome
  2. Click the lock icon → Certificate → Details
  3. Export the certificate in PEM format
  4. Update benzServerCert in SampleCredentials.h

Yellow LEDs (solid)

Problem: Server response timeout Location: src.ino:224-228 Cause:
  • Server is responding slowly (>5 seconds)
  • Network congestion
  • Server is processing the request but not responding
Solutions:
  1. Ping benzhou.tech from your computer
  2. Check ping time - should be less than 1000ms
  3. If latency is high, try a different WiFi network
  4. Restart your router
If your network is consistently slow, increase the timeout in src.ino:224:
if (millis() - timeout > 10000) { // Increased from 5000 to 10000
Occasional yellow LED flashes are normal if the server is busy. If it persists, investigate network issues.

Orange LEDs (solid)

Problem: HTTP headers not found in response Location: src.ino:233-236 Cause:
  • Server returned malformed HTTP response
  • Connection closed before headers were sent
  • API endpoint format changed
Solutions:
Add debug output to see the raw server response:
while (wifiClient.available()) {
    char c = wifiClient.read();
    Serial.print(c); // Debug output
    response += c;
}
Check if the response contains valid HTTP headers.
Ensure the API endpoint is correct:
GET /api/getCurrent/PASSWORD HTTP/1.1
Host: benzhou.tech
The server should respond with:
HTTP/1.1 200 OK
Content-Type: application/json

{"title":"...", ...}

WiFi connection issues

Pulsing white LEDs (continuous)

Problem: Cannot connect to WiFi network Location: src.ino:78-88 Cause:
  • Wrong SSID or password in SampleCredentials.h
  • WiFi network is out of range
  • ESP32 WiFi antenna issue
  • Network uses unsupported authentication (e.g., WPA3-only)
Solutions:
  1. Open SampleCredentials.h
  2. Check SSID matches your WiFi network name exactly (case-sensitive)
  3. Check SSID_PASS is correct
  4. Re-upload the sketch after making changes
  1. Move ESP32 closer to the WiFi router
  2. Ensure no metal objects are blocking the signal
  3. Try connecting to a 2.4GHz network (ESP32 doesn’t support 5GHz)
Upload a basic WiFi scan sketch:
#include <WiFi.h>

void setup() {
    Serial.begin(115200);
    WiFi.mode(WIFI_STA);
    WiFi.disconnect();
}

void loop() {
    int n = WiFi.scanNetworks();
    for (int i = 0; i < n; i++) {
        Serial.println(WiFi.SSID(i));
    }
    delay(5000);
}
If no networks are found, the ESP32 WiFi module may be faulty.

Display issues

Blank display

Problem: OLED shows no output Solutions:
  • If LEDs are OrangeRed, see OrangeRed LEDs section
  • If LEDs are another color, the display initialized but isn’t updating
Add debug output after updateCurrent():
display.clearDisplay();
display.setCursor(0, 0);
display.setTextSize(1);
display.setTextColor(WHITE);
display.println("Test message");
display.display();
If text appears, the display is working and the issue is with data fetching.

Corrupted display output

Problem: Display shows garbled text or random pixels Solutions:
Lower the I2C clock speed in src.ino:62:
I2C.begin(SDA, SCL, 100000); // Reduced from 400000 to 100000
While internal pull-ups are usually sufficient, try adding external 4.7kΩ resistors:
  • One between SDA and 3.3V
  • One between SCL and 3.3V
  • Keep I2C wires under 6 inches (15cm)
  • Use twisted pair or shielded cable
  • Avoid running I2C wires parallel to power wires

Button issues

Buttons not responding

Problem: Pressing buttons has no effect Solutions:
Each button should:
  1. Connect the GPIO pin to GND when pressed
  2. Leave the pin floating (pulled high internally) when released
  3. Have no external resistors
Use a multimeter in continuity mode:
  1. Touch probes to button terminals
  2. Press button - should beep/show 0Ω
  3. Release button - should show open circuit
Add debug output in loop():
for (int i = 0; i < 7; i++) {
    if (digitalRead(keys[i]) == LOW) {
        Serial.print("Button ");
        Serial.print(i);
        Serial.println(" pressed");
    }
}
Check serial monitor while pressing buttons.

Multiple button presses registered

Problem: One button press triggers multiple actions Cause: Button bounce - mechanical contacts make/break multiple times Solutions:
Modify the loop to ignore rapid button presses:
unsigned long lastPress[7] = {0};
const unsigned long debounceDelay = 50; // 50ms

void loop() {
    for (int i = 0; i < 7; i++) {
        keyState[i] = digitalRead(keys[i]);
        if (keyState[i] == LOW && keyPrevState[i] == HIGH) {
            if (millis() - lastPress[i] > debounceDelay) {
                funcs[i]();
                lastPress[i] = millis();
            }
        }
        keyPrevState[i] = keyState[i];
    }
}
Add a 0.1µF capacitor across each button:
  • One leg to GPIO pin
  • Other leg to GND
  • Capacitor should be as close to the button as possible

LED issues

LEDs not lighting up

Problem: RGB LED strip shows no output Solutions:
  1. Verify LED strip VCC is connected to 5V
  2. Ensure power supply can provide at least 500mA
  3. Check LED strip GND is connected to ESP32 GND
  1. Confirm data line is connected to GPIO 18
  2. Check for continuity between ESP32 pin 18 and LED data input
  3. Ensure data signal is clean (no long wires or interference)
Add this to the end of setup():
for (int i = 0; i < RGB_LED_NUM; i++) {
    LEDs[i] = CRGB::Red;
}
FastLED.show();
delay(1000);
If LEDs turn red, the hardware is working.

Wrong LED colors

Problem: LEDs display incorrect colors Solutions:
Different WS2812B variants use different color orders. Try changing in SampleCredentials.h:
#define COLOR_CODE RGB  // Instead of GRB
Common orders: GRB, RGB, BGR
Ensure your LED strip matches:
  • Chip: WS2812B (not WS2811, SK6812, or APA102)
  • Voltage: 5V (not 12V)
  • Type: Addressable RGB (not analog RGB)

API and authentication issues

Commands not affecting Spotify

Problem: Buttons trigger API calls but Spotify doesn’t respond Solutions:
  1. Check PASSWORD in SampleCredentials.h matches the server’s expected value
  2. Password is case-sensitive
  3. Re-upload sketch after changing
Add debug output in updateState():
Serial.print("Sending: ");
Serial.println(actionString);
Verify the correct action string is being sent.
  1. Ensure your Spotify account is linked to the benzhou.tech server
  2. Check that Spotify is actively playing on a device
  3. Try controlling playback from the Spotify app to confirm the account works
Most issues can be diagnosed by observing the LED error colors. Always check LED status first when troubleshooting.

Build docs developers (and LLMs) love