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.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
Check I2C connections
Check I2C connections
- Verify SDA is connected to GPIO 21
- Verify SCL is connected to GPIO 19
- Ensure display VCC is connected to 3.3V or 5V
- Ensure display GND shares common ground with ESP32
- Check for loose wires or poor solder joints
Verify I2C address
Verify I2C address
src.ino:63.Test display module
Test display module
- Try the display with a simple Adafruit_SSD1306 example sketch
- If it doesn’t work, the module may be defective
- 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
Check WiFi connection
Check WiFi connection
- Verify ESP32 is connected to WiFi (green LEDs during setup)
- Check router firewall settings
- Ensure WiFi network has internet access
- Try pinging benzhou.tech from another device on the same network
Verify server availability
Verify server availability
Update SSL certificate
Update SSL certificate
- Visit https://benzhou.tech in Chrome
- Click the lock icon → Certificate → Details
- Export the certificate in PEM format
- Update
benzServerCertin 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
Check network latency
Check network latency
- Ping benzhou.tech from your computer
- Check ping time - should be less than 1000ms
- If latency is high, try a different WiFi network
- Restart your router
Increase timeout duration
Increase timeout duration
src.ino:224: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
Monitor serial output
Monitor serial output
Verify API endpoint
Verify API endpoint
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)
Verify credentials
Verify credentials
- Open SampleCredentials.h
- Check
SSIDmatches your WiFi network name exactly (case-sensitive) - Check
SSID_PASSis correct - Re-upload the sketch after making changes
Check WiFi signal strength
Check WiFi signal strength
- Move ESP32 closer to the WiFi router
- Ensure no metal objects are blocking the signal
- Try connecting to a 2.4GHz network (ESP32 doesn’t support 5GHz)
Test WiFi module
Test WiFi module
Display issues
Blank display
Problem: OLED shows no output Solutions:Check display initialization
Check display initialization
- If LEDs are OrangeRed, see OrangeRed LEDs section
- If LEDs are another color, the display initialized but isn’t updating
Verify I2C communication
Verify I2C communication
updateCurrent():Corrupted display output
Problem: Display shows garbled text or random pixels Solutions:Reduce I2C speed
Reduce I2C speed
src.ino:62:Add pull-up resistors
Add pull-up resistors
- One between SDA and 3.3V
- One between SCL and 3.3V
Shorten I2C wires
Shorten I2C wires
- 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:Check button wiring
Check button wiring
Test button continuity
Test button continuity
Verify GPIO pins
Verify GPIO pins
loop():Multiple button presses registered
Problem: One button press triggers multiple actions Cause: Button bounce - mechanical contacts make/break multiple times Solutions:Add software debouncing
Add software debouncing
Add hardware debouncing
Add hardware debouncing
- 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:Check power supply
Check power supply
- Verify LED strip VCC is connected to 5V
- Ensure power supply can provide at least 500mA
- Check LED strip GND is connected to ESP32 GND
Verify data pin connection
Verify data pin connection
- Confirm data line is connected to GPIO 18
- Check for continuity between ESP32 pin 18 and LED data input
- Ensure data signal is clean (no long wires or interference)
Test with simple pattern
Test with simple pattern
setup():Wrong LED colors
Problem: LEDs display incorrect colors Solutions:Verify color order
Verify color order
Check LED strip specifications
Check LED strip specifications
- 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:Verify PASSWORD constant
Verify PASSWORD constant
- Check
PASSWORDin SampleCredentials.h matches the server’s expected value - Password is case-sensitive
- Re-upload sketch after changing
Check server API response
Check server API response
updateState():Verify Spotify account connection
Verify Spotify account connection
- Ensure your Spotify account is linked to the benzhou.tech server
- Check that Spotify is actively playing on a device
- Try controlling playback from the Spotify app to confirm the account works