WLED et Home Assistant : problèmes fréquents et solutions
Intégration WLED de Home Assistant : appareil non détecté, « Unknown error occurred », entités indisponibles, IP modifiée, préréglages absents, segments et mises à jour du firmware.
Home Assistant inclut une intégration WLED, et en général elle fonctionne sans histoire : elle trouve la lumière, crée une entité lumière et quelques commandes, et reste synchronisée. Quand ce n’est pas le cas, la cause fait généralement partie d’une courte liste, et plusieurs de ces problèmes ont été corrigés dans des versions récentes de Home Assistant. La première question est donc toujours : quelle version de Home Assistant utilisez-vous ? Cette page indique la version qui a changé chaque comportement.
La mise en place de l’intégration depuis zéro est bien expliquée dans la documentation officielle. Cette page parle de ce qui tourne mal.
Ce que crée l’intégration
Savoir à quoi s’attendre aide à repérer les entités « manquantes ». Pour chaque lumière WLED, vous obtenez :
| Entité | Ce que c’est |
|---|---|
| Light | La lumière elle-même, avec couleur, luminosité et une liste d’effets. Avec plus d’un segment, une lumière par segment |
| Main light | Seulement avec plus d’un segment (ou avec Keep Main Light activé) : marche/arrêt et luminosité globale pour tout l’appareil |
| Sélecteurs Preset et Playlist | Charger un préréglage ou lancer une liste de lecture |
| Sélecteur Color palette | Par segment, sous configuration |
| Sélecteur Live override | Off, On ou Until device restarts (comme la priorité sur les données en direct de WLED) |
| Nombres Speed et Intensity | Par segment, les curseurs de l’effet |
| Interrupteurs | Nightlight, Sync send, Sync receive, et par segment Reverse et Freeze |
| Capteurs | Courant estimé, courant maximal, nombre de LED, IP. Uptime, mémoire libre et capteurs Wi-Fi existent mais sont désactivés par défaut |
| Bouton Restart et mise à jour du firmware | Sous configuration et diagnostic |
L’intégration demande WLED 0.14.0 ou plus récent. Avec un firmware plus ancien, la configuration échoue. Depuis Home Assistant 2025.12, elle le dit clairement ; avant, elle affichait une erreur générique.
WLED non détecté par Home Assistant
Home Assistant trouve WLED via mDNS (zeroconf, le service _wled._tcp). Rien n’apparaît dans les appareils détectés quand :
- La lumière et Home Assistant sont sur des VLAN ou sous-réseaux différents. mDNS ne traverse pas les sous-réseaux, sauf si votre routeur ou un réflecteur le transmet. C’est la raison la plus fréquente sur les réseaux avec un VLAN IoT séparé.
- Le nom mDNS de WLED est vide. Dans Config›WiFi & Network (WiFi Setup avant WLED 16), le champ mDNS address doit contenir un nom (par défaut, quelque chose comme
wled-abcdef). Vide, cela veut dire pas de mDNS du tout. - Votre point d’accès isole les clients Wi-Fi (souvent appelé isolation des clients ou AP isolation, fréquent sur les réseaux invités).
- Les réglages réseau de Home Assistant lui-même excluent l’interface sur laquelle se trouve la lumière.
La détection n’est pas indispensable. Ajoutez l’intégration à la main : Settings›Devices & services›Add integration›WLED et tapez l’adresse IP de la lumière. Les versions récentes acceptent aussi une URL collée et n’en gardent que l’hôte.
Si vous ne connaissez pas l’IP : l’interface web WLED l’affiche dans Info, votre routeur la liste, et dans WLED Max elle se trouve dans la section Infos sur l’appareil des réglages d’une lumière, sous Adresse IP.
« Unknown error occurred » à l’ajout de WLED
Jusqu’à Home Assistant 2026.9, la configuration ne reconnaissait que deux problèmes : « impossible de se connecter » et (depuis 2025.12) « firmware trop ancien ». Tout le reste aboutissait à Unknown error occurred. En pratique, ce « reste » était :
- Un fichier de préréglages endommagé sur la lumière. L’intégration lit les préréglages de la lumière pendant la configuration, et un JSON invalide dans
presets.jsonla faisait échouer. C’est la cause dans la plupart des signalements. Sauvegardez ce que vous pouvez et réparez les préréglages ; voir préréglages WLED qui ne s’enregistrent pas ou erreur 12 et sauvegarder WLED. Ceux qui ont fait une réinitialisation d’usine ont réglé le problème pour la même raison : la réinitialisation efface le fichier défectueux. - Quelque chose à cette adresse qui n’est pas WLED, ou un WLED qui répond par une page d’erreur, par exemple pendant un redémarrage.
- Un firmware antérieur à 0.14 avec les versions de Home Assistant antérieures à 2025.12.
Home Assistant 2026.10 remplace ce message vague par « The device didn’t respond like a WLED device », qui renvoie aux mêmes causes.
Ouvrez http://<light-ip>/json et http://<light-ip>/presets.json dans un navigateur. Si l'une des deux pages ne se charge pas ou ne ressemble pas à du JSON propre, Home Assistant aura aussi du mal.
Entités WLED indisponibles
« Indisponible » ne veut pas dire la même chose selon l’entité :
- Tout est indisponible. Home Assistant ne joint pas la lumière. Vérifiez qu’elle est en ligne (ouvrez son interface web) et que son IP n’a pas changé (section suivante).
- Seulement la Main light. La lumière n’a plus qu’un segment. La Main light n’existe que tant qu’il y a deux segments ou plus, et elle reste dans la liste des entités comme indisponible quand vous revenez à un seul. Activez Keep Main Light si vous ajoutez et retirez souvent des segments (plus bas).
- Lumières de segment, vitesse, palette, reverse ou freeze de segment. Ce segment n’existe plus. Home Assistant ne supprime jamais de lui-même les entités de segment ; retirez à la main celles qui restent.
- Sélecteur Preset ou Playlist. La lumière n’a aucun préréglage, ou aucune liste de lecture. Enregistrez-en un et il apparaît.
Sur les lumières ESP8266 avec beaucoup d’effets et de palettes, tout l’appareil passait parfois en indisponible parce que la grosse réponse /json de la lumière était tronquée. Home Assistant 2026.10 lit les effets et les palettes séparément et a corrigé cela, ainsi que le cas où « un fichier de préréglages défectueux rend tout l’appareil indisponible ».
WLED a changé d’adresse IP
Le DHCP peut donner une nouvelle adresse à la lumière après un redémarrage du routeur ou une longue coupure de courant. La suite dépend de votre version :
- Si la détection fonctionne, Home Assistant remarque la nouvelle adresse et la met à jour tout seul. Depuis 2026.10, il vérifie d’abord que l’appareil à la nouvelle adresse a la même adresse MAC, ce qui a aussi supprimé un bug où une adresse corrigée à la main était annulée une demi-heure plus tard.
- Si la détection ne voit pas la lumière (autre VLAN), utilisez Reconfigure sur l’entrée de l’intégration WLED et tapez la nouvelle IP. Home Assistant refuse si la MAC ne correspond pas (« MAC address does not match ») : c’est une vérification de sécurité, pas une panne.
La solution durable est une réservation DHCP pour chaque lumière WLED dans votre routeur. Les IP fixes dans les réglages WiFi de WLED fonctionnent aussi, mais une réservation est plus facile à suivre.
Home Assistant 2025.12.0 à 2025.12.4 pouvait signaler une MAC différente alors que c'était la même, écrite avec une autre casse. 2025.12.5 l'a corrigé. Si vous êtes bloqué sur cette erreur, faites d'abord la mise à jour.
Préréglages ou listes de lecture absents
- Les nouveaux préréglages n’apparaissent pas dans le sélecteur. Avant Home Assistant 2025.11, la liste des préréglages n’était lue qu’une fois, les nouveaux préréglages demandaient donc un rechargement de l’intégration. Les versions plus récentes la mettent à jour quand la lumière signale que ses préréglages ont changé.
- Le sélecteur Playlist est indisponible. Il n’y a aucune liste de lecture sur la lumière. Créez-en une dans WLED (voir listes de lecture WLED).
- Le sélecteur affiche « unknown » après une modification de la lumière. Cela vient de WLED, pas de Home Assistant. Dès que vous changez la couleur, l’effet ou la luminosité, la lumière n’est plus « sur le préréglage 3 », WLED n’indique donc aucun préréglage actif et Home Assistant affiche unknown. C’est normal.
Pour utiliser un préréglage dans une automatisation, appelez select.select_option sur le sélecteur de préréglages avec le nom du préréglage.
Les segments comme entités
Chaque segment WLED au-delà du premier devient sa propre lumière dans Home Assistant, nommée « Segment 1 », « Segment 2 », etc. L’intégration n’utilise pas les noms de segments que vous avez donnés dans WLED.
- Trop d’entités ? Désactivez les lumières de segment dont vous ne vous servez pas.
- Des entités rattachées au mauvais segment après la suppression d’un segment au milieu. Corrigé dans Home Assistant 2026.10. Sur les versions plus anciennes, rechargez l’intégration après avoir modifié les segments.
- Keep Main Light. Dans les options de l’intégration, « Add ‘Main’ control even with single LED segment » garde la Main light en permanence. Avec cette option, les lumières de segment ne pilotent que leur propre segment, et la marche/arrêt et la luminosité globale passent par la Main light. Activez-la si des automatisations ajoutent et retirent des segments.
Les segments WLED expliqués décrit ce que sont les segments côté WLED.
Couleurs ou blanc incorrects depuis Home Assistant
L’intégration ne règle que la couleur principale du segment. Avant 2026.10, elle ne pouvait pas régler indépendamment la couleur et la température de couleur sur les rubans avec blanc chaud et blanc froid (RGB plus CCT). La documentation de WLED indique aussi que Home Assistant ne fonctionne pas avec une configuration CCT réglée ni avec une correction de la balance des blancs, et conseille d’activer Calculate CCT from RGB dans les réglages LED. Home Assistant 2026.10 a corrigé les sauts de la roue chromatique et les mauvais modes de couleur sur les rubans RGB plus CCT, faites donc la mise à jour avant de changer des réglages.
Mises à jour du firmware depuis Home Assistant
L’entité de mise à jour propose les versions stables de WLED (et les bêtas si vous utilisez déjà une bêta), et vérifie régulièrement, à quelques heures d’intervalle, s’il y en a de nouvelles. Ce qui peut mal tourner :
- La mise à jour échoue sous WLED 16. WLED 16 a une option de sécurité « Only allow update from same network/WiFi » (Config > Security & Updates). Si Home Assistant est sur un autre sous-réseau, la lumière refuse. Depuis 2026.10, Home Assistant affiche une erreur au lieu d’échouer en silence. Désactivez l’option ou faites la mise à jour depuis le même réseau.
- Pas d’entité de mise à jour. Depuis 2026.10, une lumière dont Home Assistant ne peut pas identifier la source du firmware (un build compilé soi-même, par exemple) n’a pas d’entité de mise à jour, et une mise à jour n’est proposée que si la version contient un fichier pour votre carte.
- Le mauvais fichier a été installé (par exemple une carte Ethernet qui perd l’Ethernet). Corrigé dans 2026.5, qui choisit le build correspondant à votre carte.
Pour une mise à jour à la main, voir mises à jour OTA de WLED.
Home Assistant et d’autres apps en même temps
L’intégration garde une connexion WebSocket ouverte vers la lumière et reçoit les changements en direct. Depuis Home Assistant 2026.6, elle arrête d’interroger la lumière tant que cette connexion est active ; avant, elle l’interrogeait aussi toutes les 10 secondes, ce qui pouvait faire saccader les effets sur les petites cartes.
WLED limite le nombre de clients WebSocket (la documentation de WLED pour la version 16 indique 3 sur ESP8266 et 8 sur ESP32 ; quand un client de plus se connecte, le plus ancien est déconnecté). Home Assistant, chaque onglet ouvert de l’interface web et certaines apps de téléphone en prennent chacun un. Si les mises à jour en direct s’arrêtent dans l’un d’eux, fermez les onglets de l’interface web dont vous n’avez pas besoin. Un ESP32 a plus de marge.
Si vous utilisez Home Assistant pour envoyer des effets en continu à WLED (LedFx ou des apps similaires), la lumière passe en mode temps réel et ignore tout le reste. Voir WLED bloqué en mode temps réel.
Et MQTT ?
WLED parle aussi MQTT, mais la documentation de WLED recommande l’intégration native, et la détection automatique MQTT pour Home Assistant n’est pas prise en charge (WLED l’a retirée il y a des années). N’utilisez MQTT que si vous avez une bonne raison, et configurez alors la lumière à la main en YAML.
FAQ
Pourquoi Home Assistant affiche-t-il « Unknown error occurred » pour WLED ? Le plus souvent, un fichier de préréglages endommagé sur la lumière, parfois un firmware antérieur à 0.14 ou un appareil qui ne répond pas comme WLED. Home Assistant 2026.10 affiche un message plus clair.
Comment changer l’adresse IP de WLED dans Home Assistant ? Ouvrez l’entrée de l’intégration WLED, choisissez Reconfigure et tapez la nouvelle adresse. Définissez ensuite une réservation DHCP pour que cela ne se reproduise pas.
Pourquoi ma Main light WLED est-elle indisponible ? La lumière n’a qu’un segment. Activez Keep Main Light dans les options de l’intégration si vous voulez qu’elle soit toujours là.
Home Assistant peut-il afficher les noms des segments WLED ? Non, les segments apparaissent comme Segment 1, Segment 2, etc. Renommez les entités dans Home Assistant.
Est-ce que cela fonctionne avec WLED 16 ? Oui. Home Assistant 2026.10 a corrigé les problèmes WLED 16 signalés jusqu’ici, comme les échecs silencieux de mise à jour avec le verrou « même réseau ». Il a aussi corrigé le mélange des entités de segment après la suppression d’un segment au milieu.