NeoPixel troubleshooting guide for WS2812B RGB LEDs

Dépannage des problèmes courants avec les NeoPixels (et comment les résoudre)

Mis à jour le

Mis à jour en octobre 2026 avec une nouvelle section ESP32 et du code de test CMozGlow.

Les « NeoPixels » sont des LED RVB WS2812B dotées d'un minuscule contrôleur intégré dans chaque LED. Chacune contient une LED rouge, une verte et une bleue ainsi qu'une puce pilote, le tout dans un boîtier de 5 mm, ce qui permet d'en contrôler des centaines avec un seul fil de données. Chaque pixel prend sa couleur, puis transmet le reste des données au pixel suivant.

Ruban étroit de LED adressables WS2812B

On les trouve en rubans flexibles, en anneaux, en modules individuels et en pixels cousables, et elles fonctionnent avec Arduino, l'ESP32 et la plupart des autres microcontrôleurs. Quand elles font des caprices, la cause est presque toujours l'une d'une poignée de problèmes. Les voici, avec leurs solutions, ainsi qu'une section sur les cartes ESP32 que j'utilise pour presque tout.

Liste de vérification rapide

  • Le ruban est-il alimenté, et toutes les masses sont-elles reliées entre elles ?
  • Le fil de données est-il sur l'extrémité DIN (entrée) ? Suivez les flèches imprimées sur le ruban.
  • La broche indiquée dans votre code correspond-elle à celle que vous avez câblée ?
  • Le type de LED et l'ordre des couleurs sont-ils corrects dans votre code ? (Le WS2812B est généralement en GRB.)
  • La luminosité est-elle raisonnable pour votre source d'alimentation ?

Aucune lumière

Vérifiez d'abord l'alimentation, puis les données. Assurez-vous que le ruban reçoit l'alimentation et la masse, que le fil de données arrive sur l'extrémité d'entrée et que votre code utilise la même broche que votre câblage. Lancez ensuite l'un des programmes de test en bas de cet article. Si un programme qui fonctionne à coup sûr ne donne rien, le problème vient du câblage et non du code.

La première LED fonctionne, mais pas les autres

Soit la connexion de données après le premier pixel est rompue (souvent une soudure froide), soit le premier pixel est endommagé et bloque le signal. Refaites les soudures près du début du ruban. Si cela ne suffit pas, coupez le premier pixel et branchez votre fil de données sur le deuxième. Si le reste du ruban s'allume, c'était bien le premier pixel.

Scintillement, bugs ou couleurs aléatoires au démarrage

C'est généralement un problème d'alimentation ou de bruit électrique :

  • L'alimentation ne suit pas la demande des LED.
  • Le microcontrôleur et l'alimentation des LED ne partagent pas la même masse. Toutes les masses doivent être reliées.
  • Un long fil de données capte du bruit, ou le ruban est près de moteurs ou de relais.
  • Un fil desserré ou une soudure fissurée.

Solution : reliez toutes les masses et gardez le fil de données court. Pour les montages plus importants, ajoutez un condensateur de 470 à 1000 µF entre + et − près de la première LED, et une résistance de 220 à 470 Ω sur la ligne de données. Ils lissent l'alimentation et protègent le premier pixel.

Mauvaises couleurs, ou blanc qui tire sur le rose

Les pixels WS2812B attendent les données de couleur dans l'ordre GRB, et non RGB. Si le rouge et le vert semblent inversés, changez l'ordre des couleurs dans votre code. Si les blancs paraissent roses ou étranges, vérifiez si vous avez des pixels RGB ou RGBW (ils demandent des réglages de bibliothèque différents) et que vous avez choisi le bon type de puce (WS2812B, WS2811 et SK6812 diffèrent).

LED faibles, ou couleurs qui faiblissent le long du ruban

C'est une chute de tension. Chaque LED peut consommer jusqu'à environ 60 mA en blanc à pleine puissance, et le cuivre fin d'un ruban ne peut pas transporter ce courant très loin. Les LED au bout deviennent faibles ou orangées. Utilisez du fil plus épais jusqu'au ruban, alimentez-le par les deux extrémités (ou tous les 100 à 150 LED sur les grandes longueurs) et baissez la luminosité. La plupart des projets sont superbes bien en dessous de la luminosité maximale.

Les animations saccadent ou sont lentes

Trop de LED pour le taux de rafraîchissement, trop de calculs dans chaque boucle, ou des appels à delay() qui bloquent tout. Mettez à jour moins de LED par image, précalculez les valeurs et évitez les longs délais. Un ESP32 a largement assez de puissance si vous passez d'un ancien Arduino.

Problèmes propres à l'ESP32

Puis-je alimenter des NeoPixels depuis la broche 3V3 ?

Pour les petits montages, oui, et c'est ce que je fais habituellement. J'ai déjà alimenté 60 LED à la suite depuis la broche 3V3 sans aucun problème. Avantage en prime : les LED et le signal de données de l'ESP32 sont alors à la même tension, ce qui évite le problème de niveau décrit plus bas.

Deux choses à garder en tête. La broche 3V3 est alimentée par le petit régulateur de la carte, qui alimente aussi l'ESP32 lui-même : gardez donc une luminosité modérée. 60 LED en blanc à pleine puissance demanderaient environ 3,6 A, bien plus que ce que cette broche peut fournir. Les couleurs sont aussi un peu moins lumineuses à 3,3 V qu'à 5 V. Pour les grands montages ou très lumineux, alimentez le ruban en 5 V (la broche 5V/VIN sur USB, ou une alimentation séparée) et reliez les masses entre elles.

Ruban en 5 V, données en 3,3 V

Les broches de l'ESP32 délivrent 3,3 V. Quand le ruban est alimenté en 5 V, ce signal de données est tout juste à la limite de ce que les LED lisent de façon fiable. Cela fonctionne souvent, mais si vous voyez du scintillement ou des pixels aléatoires, alimentez le ruban en 3V3 pour les petits montages, gardez le fil de données court, ou ajoutez un convertisseur de niveau comme le 74AHCT125.

Choisir une broche de données sûre

  • ESP32 classique (30 et 38 broches) : utilisez les GPIO 13, 14, 16 à 19, 21 à 23, 25 à 27, 32 ou 33. Évitez les GPIO 6 à 11 (mémoire flash), 34 à 39 (entrée uniquement) et les broches de démarrage 0, 2, 5, 12 et 15.
  • ESP32-C3 SuperMini : évitez les GPIO 2, 8 et 9, qui sont des broches de démarrage (le GPIO 8 est aussi la LED intégrée).
  • ESP32-S3 SuperMini : la LED RVB intégrée est sur le GPIO 48. Évitez les broches de démarrage 0, 3, 45 et 46.

Pour toutes les cartes que nous vendons, consultez le guide des broches et broches tactiles ESP32.

Un flash blanc pendant le téléversement

Pendant le démarrage ou le téléversement, la broche de données est flottante et les LED peuvent clignoter en blanc. C'est normal, et cela s'arrête dès que votre code s'exécute.

Bugs quand le WiFi est actif

Si vos LED ne bugguent que lorsque le WiFi ou le Bluetooth est actif, commencez par mettre à jour votre bibliothèque de LED vers sa dernière version. La prise en charge de l'ESP32 dans ces bibliothèques s'améliore sans cesse.

Code de test : FastLED

Un test simple pour n'importe quel ESP32. Modifiez DATA_PIN et NUM_LEDS selon votre câblage.

#include <FastLED.h>

#define NUM_LEDS 10
#define DATA_PIN 13   // un GPIO sûr sur l'ESP32 classique

CRGB leds[NUM_LEDS];

void setup() {
  FastLED.addLeds<WS2812B, DATA_PIN, GRB>(leds, NUM_LEDS);
  FastLED.setBrightness(40);   // gardez-la basse si alimenté en 3V3
}

void loop() {
  fill_solid(leds, NUM_LEDS, CRGB::Red);
  FastLED.show();
  delay(1000);

  fill_solid(leds, NUM_LEDS, CRGB::Green);
  FastLED.show();
  delay(1000);

  fill_solid(leds, NUM_LEDS, CRGB::Blue);
  FastLED.show();
  delay(1000);
}

Si vous voyez du vert quand le code demande du rouge, l'ordre des couleurs est incorrect.

Code de test : CMozGlow

Nous avons écrit notre propre bibliothèque gratuite, CMozGlow, pour simplifier tout cela. Choisissez un effet, changez un chiffre et téléversez. Elle vous indique aussi en clair ce qui ne va pas au lieu d'échouer en silence, et elle peut limiter la puissance consommée par vos LED, ce qui est idéal quand vous alimentez depuis la broche 3V3 ou une petite batterie.

Dans l'IDE Arduino, ouvrez Fichier > Exemples > CMozGlow > CMozGlow_Basics, ou collez ceci :

#include <CMozGlow.h>

// ========== À MODIFIER ==========
const uint8_t  EFFECT   = 8;    // 0-13, voir le tableau des effets dans le README
const uint16_t NUM_LEDS = 1;    // LED intégrée seule = 1
const uint8_t  SPEED    = 5;    // 1 rêveur ... 10 festif
const uint32_t COLOR    = CMozGlow::Color(255, 42, 120);
const uint8_t  LED_PIN  = 3;    // GPIO 3 = pixel intégré ; à changer pour d'autres cartes
// ================================

CMozGlow glow(NUM_LEDS, LED_PIN);

void setup() {
  Serial.begin(115200);
  if (!glow.begin()) {
    Serial.println(glow.errorText());   // elle vous dit quoi corriger
    while (true) delay(1000);
  }
  glow.setPowerBudgetmA(450);           // sûr sur USB ou une petite LiPo
  glow.setEffect(EFFECT);
  glow.setEffectColor(COLOR);
  glow.setEffectSpeed(SPEED);
}

void loop() {
  glow.update();                        // c'est tout
}

LED_PIN est votre broche de données. Le GPIO 3 est le pixel intégré de notre CMoz ESP32-S3 Mini, encore en phase de test. Sur toute autre carte, indiquez la broche que vous avez câblée (par exemple 13 sur un ESP32 classique) et réglez NUM_LEDS sur le nombre de LED de votre ruban. En cas de problème, errorText() affiche la raison dans le moniteur série. Le tableau complet des effets et les notes sur les broches se trouvent dans le README sur GitHub.

PlatformIO : ajoutez la bibliothèque à votre platformio.ini :

[env:cmoz_s3_mini]
platform  = espressif32
board     = esp32-s3-devkitc-1
framework = arduino
lib_deps  = cmoz/CMozGlow @ ^1.2.2

IDE Arduino : ouvrez Outils > Gérer les bibliothèques, recherchez CMozGlow et installez-la. Pour une carte ESP32-S3, réglez USB CDC On Boot sur Enabled afin que les messages d'erreur de CMozGlow s'affichent dans le moniteur série.

Envie de concevoir votre effet d'abord ? Le simulateur et générateur de code CMozGlow fonctionne dans votre navigateur et écrit le programme pour vous.

Simulateur et générateur de code CMozGlow

Toujours bloqué ?

Partez d'un ruban qui fonctionne et d'un programme de test, changez une seule chose à la fois, et la plupart des problèmes se révèlent vite. Besoin de LED pour vous exercer ? Le ruban de démarrage NeoPixel est un premier pas facile, et vous en trouverez bien d'autres dans notre collection de LED adressables. Vous pouvez aussi poser votre question pendant mon direct sur CMozMaker. Bonne création !

Retour au blog

Laisser un commentaire