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

# Troubleshooting

> Common issues and solutions for Spotify MacroBoard

## LED error indicators

The MacroBoard uses LED colors to indicate different error states during operation.

<Warning>
  When LEDs display an error color, the device has encountered a problem that requires attention.
</Warning>

### 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:**

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

<Accordion title="Verify I2C address">
  Use an I2C scanner sketch to detect the display's actual address:

  ```cpp theme={null}
  Wire.begin(21, 19);
  Wire.beginTransmission(0x3C);
  byte error = Wire.endTransmission();
  ```

  If the address differs from 0x3C, update the code in `src.ino:63`.
</Accordion>

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

### 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:**

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

<Accordion title="Verify server availability">
  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.
</Accordion>

<Accordion title="Update SSL certificate">
  The server's SSL certificate may have been renewed. Generate a new certificate:

  1. Visit [https://benzhou.tech](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
</Accordion>

### 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:**

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

<Accordion title="Increase timeout duration">
  If your network is consistently slow, increase the timeout in `src.ino:224`:

  ```cpp theme={null}
  if (millis() - timeout > 10000) { // Increased from 5000 to 10000
  ```
</Accordion>

<Info>
  Occasional yellow LED flashes are normal if the server is busy. If it persists, investigate network issues.
</Info>

### 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:**

<Accordion title="Monitor serial output">
  Add debug output to see the raw server response:

  ```cpp theme={null}
  while (wifiClient.available()) {
      char c = wifiClient.read();
      Serial.print(c); // Debug output
      response += c;
  }
  ```

  Check if the response contains valid HTTP headers.
</Accordion>

<Accordion title="Verify API endpoint">
  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":"...", ...}
  ```
</Accordion>

## 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:**

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

<Accordion title="Check WiFi signal strength">
  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)
</Accordion>

<Accordion title="Test WiFi module">
  Upload a basic WiFi scan sketch:

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

## Display issues

### Blank display

**Problem:** OLED shows no output

**Solutions:**

<Accordion title="Check display initialization">
  * If LEDs are OrangeRed, see [OrangeRed LEDs](#orangered-leds-solid) section
  * If LEDs are another color, the display initialized but isn't updating
</Accordion>

<Accordion title="Verify I2C communication">
  Add debug output after `updateCurrent()`:

  ```cpp theme={null}
  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.
</Accordion>

### Corrupted display output

**Problem:** Display shows garbled text or random pixels

**Solutions:**

<Accordion title="Reduce I2C speed">
  Lower the I2C clock speed in `src.ino:62`:

  ```cpp theme={null}
  I2C.begin(SDA, SCL, 100000); // Reduced from 400000 to 100000
  ```
</Accordion>

<Accordion title="Add pull-up resistors">
  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
</Accordion>

<Accordion title="Shorten I2C wires">
  * Keep I2C wires under 6 inches (15cm)
  * Use twisted pair or shielded cable
  * Avoid running I2C wires parallel to power wires
</Accordion>

## Button issues

### Buttons not responding

**Problem:** Pressing buttons has no effect

**Solutions:**

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

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

<Accordion title="Verify GPIO pins">
  Add debug output in `loop()`:

  ```cpp theme={null}
  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.
</Accordion>

### Multiple button presses registered

**Problem:** One button press triggers multiple actions

**Cause:** Button bounce - mechanical contacts make/break multiple times

**Solutions:**

<Accordion title="Add software debouncing">
  Modify the loop to ignore rapid button presses:

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

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

## LED issues

### LEDs not lighting up

**Problem:** RGB LED strip shows no output

**Solutions:**

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

<Accordion title="Verify data pin connection">
  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)
</Accordion>

<Accordion title="Test with simple pattern">
  Add this to the end of `setup()`:

  ```cpp theme={null}
  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.
</Accordion>

### Wrong LED colors

**Problem:** LEDs display incorrect colors

**Solutions:**

<Accordion title="Verify color order">
  Different WS2812B variants use different color orders. Try changing in SampleCredentials.h:

  ```cpp theme={null}
  #define COLOR_CODE RGB  // Instead of GRB
  ```

  Common orders: GRB, RGB, BGR
</Accordion>

<Accordion title="Check LED strip specifications">
  Ensure your LED strip matches:

  * Chip: WS2812B (not WS2811, SK6812, or APA102)
  * Voltage: 5V (not 12V)
  * Type: Addressable RGB (not analog RGB)
</Accordion>

## API and authentication issues

### Commands not affecting Spotify

**Problem:** Buttons trigger API calls but Spotify doesn't respond

**Solutions:**

<Accordion title="Verify PASSWORD constant">
  1. Check `PASSWORD` in SampleCredentials.h matches the server's expected value
  2. Password is case-sensitive
  3. Re-upload sketch after changing
</Accordion>

<Accordion title="Check server API response">
  Add debug output in `updateState()`:

  ```cpp theme={null}
  Serial.print("Sending: ");
  Serial.println(actionString);
  ```

  Verify the correct action string is being sent.
</Accordion>

<Accordion title="Verify Spotify account connection">
  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
</Accordion>

<Tip>
  Most issues can be diagnosed by observing the LED error colors. Always check LED status first when troubleshooting.
</Tip>