LeafBus is een open-source project waarmee Nanoleaf Shapes lichtpanelen onafhankelijk van de originele controller, cloud of app kunnen worden aangestuurd. Door een ESP32 te gebruiken die via MicroPython communiceert met de panelbus, kan de hardware direct worden aangestuurd.
Kernpunten van het project:
- Protocol: Het project biedt een uitgebreide specificatie (
PROTOCOL.md) van de fysieke laag, timing en geometrie van de panelen.
- Integratie: De assemblage fungeert als een pixel-sink voor DDP en E1.31/sACN, waardoor het compatibel is met software zoals xLights, LedFx en WLED.
- Functionaliteit: Het systeem ondersteunt automatische enumeratie van panelen, layout-detectie, RGBW-kleurbesturing en touch-events.
- Hardware: De opstelling vereist een ESP32, een weerstand (1–2 kΩ) en een directe verbinding met de DATA- en GND-pads van de panelen (let op: de voeding voert 42 V).
De repository bevat zowel de firmware voor de ESP32 als een Python-tool voor het visualiseren van de layout en het verzenden van kleurcommando's.
LeafBus
De layout wordt berekend op basis van de bus alleen: nummers zijn chunk-indices, stippen markeren de connector waarmee elk paneel wordt bereikt (groen: waar de ESP32 is aangesloten), en de blauwe ring is de voeding.
Een ESP32 vervangt de Shapes-controller op de driepins edge-connector, identificeert de panelen, leest hun layout en verstuurt kleurframes met een snelheid van ongeveer 16 frames per seconde via MicroPython. De assemblage verschijnt vervolgens op het netwerk als een pixel-sink voor DDP en E1.31/sACN. Hierdoor kan elke verlichtingssoftware — zoals xLights, LedFx, Hyperion, WLED sync of een paar regels Python — worden gebruikt. Het protocol zelf is gedocumenteerd in PROTOCOL.md; deze repository is de referentie-implementatie, geschreven voor correctheid en leesbaarheid, niet voor snelheid.
Status
| Functie | Status |
|---|
| Enumeratie, layout-string, boomstructuur, chunk-volgorde | � |
|
| Paneelcoördinaten en oriëntatie vanuit de layout-string alleen | � |
| (Mini Triangle en Triangle; Hexagon niet getest) |
| Kleur per paneel (RGBW + overgangstijd), helderheid | � |
|
| Touch-events, hot-plug detectie en her-enumeratie | � |
|
| DDP en E1.31 receivers, HTTP topologyserver | � |
|
| E1.31 unicast en multicast | � |
|
| Locatie van de voeding | � |
| (gelezen uit de layout-string) |
| Elements, Lines, Canvas, Hexagon op hardware | ❌ (niet getest) |
| Paneel firmware-update | ❌ (buiten scope) |
Het protocol
PROTOCOL.md is het belangrijkste resultaat van dit project. Het is een zelfstandige specificatie — inclusief fysieke laag, framing, timing, enumeratie, de grammatica van de layout-string en de daaruit afgeleide geometrie — met een minimale werkende sequentie die je in een middag kunt reproduceren.
Hardware
- Nanoleaf Shapes panelen met hun eigen voeding (42 V). Geverifieerd met 13 Mini Triangles en één Triangle.
- ESP32 (origineel, bijv. ESP32-D0WD; de S2/S3/C3 vereisen een andere GPIO-registerbasis, zie
firmware/panelbus.py).
- Eén weerstand, 1–2 kΩ.
- Middelen om de DATA- en GND-pads van het paneel te bereiken: een reserve-linker met vastgesolde draden, of pogo-pins.
Waarschuwing: De voedingspad naast DATA voert 42 V; controleer de volgorde van de pads dubbel voordat je aansluitingen maakt en laat die pad ongemoeid.
De TX-pin moet open drain zijn; een push-pull output houdt de lijn hoog, waardoor de panelen nooit kunnen antwoorden. De firmware stelt de pad-modus zelf in.
Snelstart
- Flash MicroPython v1.29 of later op de ESP32.
- Kopieer
firmware/config.example.json naar firmware/config.json en vul je wifi-gegevens in.
- Kopieer
firmware/*.py en config.json naar het board met je gebruikelijke tool, bijvoorbeeld mpremote:
``bash mpremote cp firmware/*.py firmware/config.json : ``
- Reset het board. Het print het IP-adres en begint te luisteren:
``text panels: 14 DDP udp://192.168.1.42:4048 E1.31 udp://192.168.1.42:5568 universe 1 group 239.255.0.1 HTTP http://192.168.1.42/layout ``
Het systeem in werking stellen:
tools/leafbus.py send 192.168.1.42 red
tools/leafbus.py layout 192.168.1.42 --json layout.json --svg layout.svg
tools/leafbus.py rainbow 192.168.1.42 --layout layout.json
De tool heeft niets anders nodig dan de standaardbibliotheek voor DDP; --e131 maakt gebruik van het sacn pakket (pip install -r requirements.txt).
layout print de assemblageboom, welk chunk-index bij welk paneel hoort, waar de voeding zich bevindt, en tekent de afbeelding bovenaan deze pagina.
identify <ip> N verlicht één paneel, zodat je de indices kunt koppelen aan de fysieke wand. Met --layout volgt de tint van de regenboog de hoek rond de assemblage in plaats van de chunk-index.
Vanuit de REPL, zonder netwerk:
import panelbus
import anim
bus = panelbus.PanelBus()
bus.enumerate()
bus.brightness(255)
bus.set_color(255, 0, 0) # elk paneel rood
bus.push_colors([(255, 0, 0), None, (0, 0, 255)]) # per paneel; None = ongewijzigd
anim.rainbow(bus)
Repository structuur
PROTOCOL.md: De protocolspecificatie.firmware/: MicroPython voor de ESP32:panelbus.py: bus driver.geometry.py: layout string → boomstructuur en coördinaten.ddp.py / e131.py / web.py: netwerk-receivers.app.py + main.py: applicatie.anim.py: on-board demo's.config.example.json: voorbeeldconfiguratie.tools/leafbus.py: Host-tool die via IP met het board communiceert: layout, identify, send, rainbow.tests/: Layout-string parser en geometrie, python -m pytest.docs/: Diagrammen.
Licenties
Alles in deze repository — firmware, tools, tests, de specificatie en de diagrammen — is gelicenseerd onder de MIT-licentie (LICENSE). Voor het implementeren van PROTOCOL.md is geen toestemming of bronvermelding in je code nodig.
Dit is een onafhankelijk project en is niet gelieerd aan, onderschreven door of ondersteund door Nanoleaf. Productnamen worden uitsluitend gebruikt om de hardware te identificeren waarmee het project compatibel is.
LeafBus
De layout wordt berekend op basis van de bus alleen: nummers zijn chunk-indices, stippen markeren de connector waarmee elk paneel wordt bereikt (groen: waar de ESP32 is aangesloten), en de blauwe ring is de voeding.
Een ESP32 vervangt de Shapes-controller op de driepins edge-connector, identificeert de panelen, leest hun layout en verstuurt kleurframes met een snelheid van ongeveer 16 frames per seconde via MicroPython. De assemblage verschijnt vervolgens op het netwerk als een pixel-sink voor DDP en E1.31/sACN. Hierdoor kan elke verlichtingssoftware — zoals xLights, LedFx, Hyperion, WLED sync of een paar regels Python — worden gebruikt. Het protocol zelf is gedocumenteerd in PROTOCOL.md; deze repository is de referentie-implementatie, geschreven voor correctheid en leesbaarheid, niet voor snelheid.
Status
| Functie | Status |
|---|
| Enumeratie, layout-string, boomstructuur, chunk-volgorde | � |
|
| Paneelcoördinaten en oriëntatie vanuit de layout-string alleen | � |
| (Mini Triangle en Triangle; Hexagon niet getest) |
| Kleur per paneel (RGBW + overgangstijd), helderheid | � |
|
| Touch-events, hot-plug detectie en her-enumeratie | � |
|
| DDP en E1.31 receivers, HTTP topologyserver | � |
|
| E1.31 unicast en multicast | � |
|
| Locatie van de voeding | � |
| (gelezen uit de layout-string) |
| Elements, Lines, Canvas, Hexagon op hardware | ❌ (niet getest) |
| Paneel firmware-update | ❌ (buiten scope) |
Het protocol
PROTOCOL.md is het belangrijkste resultaat van dit project. Het is een zelfstandige specificatie — inclusief fysieke laag, framing, timing, enumeratie, de grammatica van de layout-string en de daaruit afgeleide geometrie — met een minimale werkende sequentie die je in een middag kunt reproduceren.
Hardware
- Nanoleaf Shapes panelen met hun eigen voeding (42 V). Geverifieerd met 13 Mini Triangles en één Triangle.
- ESP32 (origineel, bijv. ESP32-D0WD; de S2/S3/C3 vereisen een andere GPIO-registerbasis, zie
firmware/panelbus.py).
- Eén weerstand, 1–2 kΩ.
- Middelen om de DATA- en GND-pads van het paneel te bereiken: een reserve-linker met vastgesolde draden, of pogo-pins.
Waarschuwing: De voedingspad naast DATA voert 42 V; controleer de volgorde van de pads dubbel voordat je aansluitingen maakt en laat die pad ongemoeid.
De TX-pin moet open drain zijn; een push-pull output houdt de lijn hoog, waardoor de panelen nooit kunnen antwoorden. De firmware stelt de pad-modus zelf in.
Snelstart
- Flash MicroPython v1.29 of later op de ESP32.
- Kopieer
firmware/config.example.json naar firmware/config.json en vul je wifi-gegevens in.
- Kopieer
firmware/*.py en config.json naar het board met je gebruikelijke tool, bijvoorbeeld mpremote:
``bash mpremote cp firmware/*.py firmware/config.json : ``
- Reset het board. Het print het IP-adres en begint te luisteren:
``text panels: 14 DDP udp://192.168.1.42:4048 E1.31 udp://192.168.1.42:5568 universe 1 group 239.255.0.1 HTTP http://192.168.1.42/layout ``
Het systeem in werking stellen:
tools/leafbus.py send 192.168.1.42 red
tools/leafbus.py layout 192.168.1.42 --json layout.json --svg layout.svg
tools/leafbus.py rainbow 192.168.1.42 --layout layout.json
De tool heeft niets anders nodig dan de standaardbibliotheek voor DDP; --e131 maakt gebruik van het sacn pakket (pip install -r requirements.txt).
layout print de assemblageboom, welk chunk-index bij welk paneel hoort, waar de voeding zich bevindt, en tekent de afbeelding bovenaan deze pagina.
identify <ip> N verlicht één paneel, zodat je de indices kunt koppelen aan de fysieke wand. Met --layout volgt de tint van de regenboog de hoek rond de assemblage in plaats van de chunk-index.
Vanuit de REPL, zonder netwerk:
import panelbus
import anim
bus = panelbus.PanelBus()
bus.enumerate()
bus.brightness(255)
bus.set_color(255, 0, 0) # elk paneel rood
bus.push_colors([(255, 0, 0), None, (0, 0, 255)]) # per paneel; None = ongewijzigd
anim.rainbow(bus)
Repository structuur
PROTOCOL.md: De protocolspecificatie.firmware/: MicroPython voor de ESP32:panelbus.py: bus driver.geometry.py: layout string → boomstructuur en coördinaten.ddp.py / e131.py / web.py: netwerk-receivers.app.py + main.py: applicatie.anim.py: on-board demo's.config.example.json: voorbeeldconfiguratie.tools/leafbus.py: Host-tool die via IP met het board communiceert: layout, identify, send, rainbow.tests/: Layout-string parser en geometrie, python -m pytest.docs/: Diagrammen.
Licenties
Alles in deze repository — firmware, tools, tests, de specificatie en de diagrammen — is gelicenseerd onder de MIT-licentie (LICENSE). Voor het implementeren van PROTOCOL.md is geen toestemming of bronvermelding in je code nodig.
Dit is een onafhankelijk project en is niet gelieerd aan, onderschreven door of ondersteund door Nanoleaf. Productnamen worden uitsluitend gebruikt om de hardware te identificeren waarmee het project compatibel is.
Groetjes,