cookbook/troubleshooting/hardware.md
Difficulty Level: ⭐⭐ Beginner to Intermediate Time to Complete: 45-60 minutes Prerequisites:
You'll Learn:
In-depth troubleshooting guide for hardware-related LED issues including wiring, power, and platform-specific problems.
Problem: Last LEDs are dim or wrong color
Cause: Voltage drop across long strips due to wire resistance
Solutions:
Use thicker power wires (18-22 AWG for short runs)
Inject power every 60-100 LEDs on long strips
Connect 5V and GND at both ends of strip
Use separate power supply (don't power from microcontroller)
Power Supply (+5V) ----+---> LED Strip VCC
|
+---> Microcontroller VIN/5V (if needed)
Power Supply (GND) ----+---> LED Strip GND
|
+---> Microcontroller GND (MUST share ground!)
Microcontroller GPIO --[220Ω resistor]---> LED Strip DATA
Power Supply (+) --[1000µF capacitor]-- Power Supply (-)
Critical points:
Cause: Signal integrity issue - voltage levels or timing
Solutions:
Add 220-470Ω resistor on data line (close to microcontroller)
Keep data wire short (< 6 inches if possible)
Use level shifter for 3.3V to 5V conversion
Try lower data pin impedance
Causes & Solutions:
Problem: Supply can't provide enough current
Solution:
- Use power supply rated 20% higher than calculated need
- Example: 100 LEDs × 60mA = 6A needed, use 8A supply
- Cheap supplies often don't meet rated specs
Problem: Unstable ground reference
Solution:
- Ensure microcontroller GND connects to LED strip GND
- Use star grounding (all GNDs meet at one point)
- Use thick wire for ground (same gauge as 5V wire)
Solutions:
- Keep data wire away from power wires (at least 1 inch separation)
- Add 0.1µF ceramic capacitor near each LED strip section
- Use shielded cable for data line in noisy environments
- Avoid running LED wires parallel to AC power lines
Solutions:
// Disable interrupts during FastLED.show()
// (FastLED does this automatically on most platforms)
// Avoid WiFi/Bluetooth during LED updates on ESP32
#ifdef ESP32
esp_wifi_stop(); // Before FastLED.show()
FastLED.show();
esp_wifi_start(); // After
#endif
Comprehensive checklist:
Hardware:
[ ] Power supply voltage correct (5V for most strips)
[ ] Power supply capacity sufficient (60mA per LED at full white)
[ ] Power supply plugged in and turned on
[ ] Positive and negative not reversed
[ ] Data pin correct in code (matches wiring)
[ ] LED type correct (WS2812B, APA102, etc.)
[ ] COLOR_ORDER correct (try GRB if RGB doesn't work)
[ ] Strip not damaged (test with known-good controller)
[ ] Wires making solid contact (no loose connections)
[ ] Ground shared between microcontroller and LED strip
Software:
[ ] FastLED.show() being called
[ ] Brightness not set to 0
[ ] LED array actually being set to colors (not all black)
[ ] Correct pin definitions for your board
Systematic testing:
Scenario: First N LEDs work, rest don't
Causes:
Solutions:
Process:
1. Identify last working LED
2. Suspect the LED immediately after (or the last working one)
3. Test by:
- Setting NUM_LEDS to last working position
- See if strip works reliably
4. Cut out failed LED and reconnect data line
5. Consider that last working LED might be damaged (weak output)
Hardware solutions:
- Add 220Ω resistor on data line (if not already present)
- Use level shifter for 3.3V systems
- Reduce strip length or split into sections
- Inject data signal midway through strip with buffer IC
Even if data signal is good, insufficient power causes issues:
- Add power injection every 50-100 LEDs
- Connect 5V and GND directly to strip at injection points
- Don't connect multiple power supplies in parallel (unless same model)
Cause: WiFi interrupts interfere with LED timing
Solution 1 - Disable WiFi During Updates:
void loop() {
// Pause WiFi
#ifdef ESP32
esp_wifi_stop();
#endif
updateLEDs();
FastLED.show();
#ifdef ESP32
esp_wifi_start();
#endif
// Do WiFi tasks
delay(10);
}
Solution 2 - Use RMT Peripheral (Better):
// FastLED automatically uses RMT on ESP32 if pin supports it
// RMT is immune to WiFi interference
// Use pins: 2, 4, 5, 12-19, 21-23, 25-27, 32-33
#define LED_PIN 16 // RMT-capable pin
Solution 3 - Run LEDs on Second Core:
// Use separate task on second CPU core
void ledTask(void* parameter) {
while (true) {
updateLEDs();
FastLED.show();
delay(20);
}
}
void setup() {
// Start LED task on core 0 (Arduino uses core 1)
xTaskCreatePinnedToCore(
ledTask, // Function
"LEDs", // Name
10000, // Stack size
NULL, // Parameters
1, // Priority
NULL, // Task handle
0 // Core (0 or 1)
);
}
Good pins for LEDs (RMT support):
- GPIO 2, 4, 5
- GPIO 12-19
- GPIO 21-23
- GPIO 25-27
- GPIO 32-33
Avoid:
- GPIO 0, 2 (boot pins - can cause issues)
- GPIO 6-11 (connected to flash)
- GPIO 34-39 (input only)
Calculate required power and select appropriate supply:
LED Count | Max Current (Full White) | Recommended Supply | Typical Cost
----------|---------------------------|-------------------|-------------
30 | 1.8A | 2.5A | $10-15
60 | 3.6A | 5A | $15-20
100 | 6.0A | 8A | $20-30
150 | 9.0A | 12A | $30-40
200 | 12.0A | 15A | $40-60
Note: Full white is worst case. Most patterns use 30-50% of max.
Important: Use setMaxPowerInVoltsAndMilliamps() to limit current draw:
void setup() {
// Limit to 2A at 5V
FastLED.setMaxPowerInVoltsAndMilliamps(5, 2000);
}
Power supply requirements:
Comprehensive test code for hardware validation:
// Comprehensive hardware test
void hardwareTest() {
Serial.begin(115200);
delay(1000);
Serial.println("=== FastLED Hardware Test ===");
// Test 1: Single LED
Serial.println("Test 1: First LED RED");
FastLED.clear();
leds[0] = CRGB::Red;
FastLED.show();
delay(2000);
// Test 2: All RED
Serial.println("Test 2: All LEDs RED");
fill_solid(leds, NUM_LEDS, CRGB::Red);
FastLED.show();
delay(2000);
// Test 3: Color test
Serial.println("Test 3: Color sequence");
CRGB colors[] = {CRGB::Red, CRGB::Green, CRGB::Blue, CRGB::White};
for (int c = 0; c < 4; c++) {
fill_solid(leds, NUM_LEDS, colors[c]);
FastLED.show();
delay(1000);
}
// Test 4: Individual LEDs
Serial.println("Test 4: Individual LED scan");
FastLED.clear();
for (int i = 0; i < NUM_LEDS; i++) {
leds[i] = CRGB::White;
FastLED.show();
delay(50);
leds[i] = CRGB::Black;
}
Serial.println("=== Test Complete ===");
}
How to use:
setup())For strips longer than 100 LEDs:
Power Supply (+5V) ---+---> Strip Start VCC
|
+---> Strip Middle VCC (at LED 100)
|
+---> Strip End VCC (at LED 200)
Power Supply (GND) ---+---> Strip Start GND
|
+---> Strip Middle GND
|
+---> Strip End GND
Microcontroller ------[resistor]---> Strip Start DATA
Code consideration:
// No code changes needed for power injection
// It's purely a wiring modification
// LEDs will be brighter and more consistent
Use a multimeter to verify hardware:
Test 1: Power Supply Voltage
1. Set multimeter to DC voltage (20V range)
2. Measure power supply output (no load)
3. Should read 4.5-5.5V (ideally 5.0-5.2V)
4. Measure again with LEDs connected (under load)
5. Should not drop below 4.5V
Test 2: Voltage at Strip
1. Measure voltage at strip start (at VCC and GND pads)
2. Should be same as power supply (minimal drop)
3. Measure at strip end
4. With LEDs on, should not drop more than 0.5V
5. Large drop indicates insufficient wire gauge
Test 3: Continuity
1. Set multimeter to continuity mode
2. Test ground connection: microcontroller GND to strip GND
3. Should beep (indicating connection)
4. Test data connection: microcontroller pin to strip DATA
5. Should beep
Avoid these frequent errors:
Not sharing ground
Powering LEDs from microcontroller
Reversed polarity
No capacitor on power supply
Thin wire for power
Long data wire without resistor
Data wire too close to power wire