LED-Fackel ("Torch") mit SmartLEDs bauen

Hintergrundgeschichte

Die Feuer/Fackelanimation die heute in den P44-xx zur Verfügung steht, ist aus dem allerersten plan44 SmartLED-Projekt, der messagetorch, Anfang 2013 entstanden. Damals war es ein Nachbau-Versuch eines Exponats auf dem 30C3 in Hamburg, dessen Funktionsweise der Entwickler mündlich erklärt hatte. Aus diesem Hörensagen (Code war damals noch keiner veröffentlicht) entstand dann die erste Version (für den Spark/Particle core).

Erst später fand ich heraus, dass dieser Entwickler Simon Budig ist (der am freien Bildverarbeitungsprogramm GIMP arbeitet). 2016 hat er den Code seiner "flame" für Arduino auf github veröffentlicht.

Material

Diese Anleitung setzt ein betriebsbereites P44-DSB-X (für Betrieb mit Digital Strom) oder P44-LC-X (Standalone) auf einem RaspberryPi voraus. Wer noch keins hat: Die Anleitung hier erklärt, wie sich das selber mit den kostenlosen SD-Card-Images von plan44 und einem handelsüblichen RaspberryPi aufbauen lässt.

Die P44-xx kann mit den SmartLEDs aus der WS281x-Serie umgehen. Die ältesten und inzwischen günstigsten LED-Streifen sind die mit dem WS2812(B)-Chip. Für 5V-Streifen aktuell ist der WS2813(B)-Chip, der eine Backup-Datenleitung hat, womit Ausfälle von einzelnen LEDs in der Kette nicht den ganzen Rest der Kette lahmlegen. Zudem ist die Farbwiedergabe besser und das Timing für die Daten weniger heikel. Damit eignen sich WS2813(B) für zuverlässige und langlebige Installationen (etwa mit P44-LC-LED) besser.

SmartLED-Streifen mit WS2812/13 sind bei diversen Online-IoT/DIY-Händlern erhältlich, auf Plattformen wie ricardo oder ebay und natürlich bei internationalen Grosshändlern wie amazon und direkt in China (wo das Material sowieso herkommt) bei aliexpress. Die Preise variieren enorm - deselben 5m-Streifen WS2813 mit 60 LED/m findet man von CHF 25 bis CH 150 angeboten. Es kommt aufs Budget gegenüber der vorhandenen Geduld an, welche Quelle die beste ist ;-)

Aufbau

An sich ist es einfach - eine WS281x-LED-Schlange auf einen Zylinder aufwickeln, fertig.

Das folgende Video zeigt das in der simplesten Variante mit einem Kartonrohr und 5m WS2813 LED-Streifen (mit 60 LED/m). Das ergibt eine Fackel von 30-50cm Höhe, je nach dem, wie dicht der Streifen gewickelt wird:

Das Video zeigt am Schluss das Abzählen der LEDs - wir brauchen später die Anzahl LEDs rundherum sowie die Anzahl Windungen für die Konfiguration! Im Beispiel sind es 17 LEDs rundherum in 19 Windungen.

Je nach Dicke der Röhre geht das LED-Raster nicht auf mit dem Röhrenumfang - das führt zwar zu einer leicht schrägen "Projektionsfläche", was aber gerade für die Fackelanimation fast besser aussieht als 100% senkrecht übereinander liegende LEDs.

Eine elegantere Fackel (wie die in der Animation ganz oben) gibt es, wenn eine Plexiglasröhre verwendet wird, und ein LED-Streifen in die Röhre hineingewickelt wird. Das geht relativ gut mit LED-Schlangen, die ein einem eckigen Silikonschlauch versorgt sind (die "wasserdichten" oder zumindest wassergeschützten Varianten). Evtl. zuerst um eine dünnere Hilfsröhre wickeln, dann in die Plexiröhre stecken und dann durch Drehen der Hilfsröhre an die Innenfläche der Plexiröhre abwickeln.

Anschliessen der LED-Schlange an den Raspberry Pi

Für Effekte wie die "Torch", bei denen nur wenige der LEDs gleichzeitig leuchten, kann die LED-Schlange direkt an den RPi angeschlossen werden, und aus dem normalen RPi-Netzteil (das je nach Modell 5-15W liefern kann).

Das folgende Video zeigt, an welche Pins des RPi das Anschlusstück für die LED-Kette (davon sollte in jeder Packung WS281x-LEDs eins beiliegen) angeschlossen werden muss.

• Weiss ist der Minus-Pol der Stromversorgung, und muss mit "Ground" (oft auch als "GND" abgekürzt) angeschlossen werden.
• Rot ist der Plus-Pol der Stromversorgung, und muss mit "5V Power" verbunden werden.
• Grün ist die Datenleitung, diese muss mit GPIO18 verbunden werden.

Hier nun das Video:

Jetzt ist die Fackel von der Hardware her betriebbereit!

Konfiguration des LED-Layouts

Für eine komfortable "Bespielung" der Fackelfläche wollen wir diese auch in der Software als "Zeichenfläche" in einem X-/Y-Koordinatensystem ansteuern können.

Dazu muss jetzt der Software "erklärt" werden, wie die LEDs auf der Fläche angeordnet sind. Standardmässig geht die P44-xx nämlich davon aus, dass die LEDs alle in einer Linie sind, also eine "Fläche" mit nur 1 Pixel Höhe und der Breite entsprechend der Anzahl LEDs in der Kette.

Bei der im Video oben gezeigten Fackel haben wir aber eine Fläche von 17 Pixel horizontal (X-Richtung = Zylinderumfang) und 19 Pixel vertikal (Y-Richtung, Zylinderhöhe). Der Streifen ist links herum gewickelt, d.h. die Laufrichtung des Streifens ist entgegen der üblichen links-nach-rechts X-Richtung.

Mit diesen Infos im Kopf öffnen wir nun die interaktive Eingabeseite für Scriptbefehle, den sogenannten REPL (Mehr Details dazu s. hier). Dazu muss das index.html in der Adresszeile des Browsers durch repl.html ersetzt werden:

In diesem Fenster können wir nun interaktiv das Layout abfragen, ändern und testen:

ledchaincover()

(eingeben und dann den "Execute"-Knopf drücken)

Resultat:

/* json */
{
  "x": 0,
  "y": 0,
  "dx": 256,
  "dy": 1
}

ledchaincover() gibt die Fläche zurück, die aktuell von LEDs abgedeckt ist. Wie oben erwähnt, ist das standardmässig für einen linear ausgerollten Streifen mit allen LEDs auf einer Linie gedacht. Als muss das jetzt geändert werden (Details dazu s. hier):

// die aktuelle Konfiguration entfernen
removeledchains()

// Im Beispiel sind es 300 WS2813-LEDs (GRB-Reihenfolge der Farbkanäle),
// und die "Torch" hat 17 LEDs pro Windung und insgesamt 19 Windungen.
// Die LEDs sind von rechts nach links gewickelt (X rückwärts) -> X Option
addledchain("WS2813.GRB:rpi:300:0:17:0:19:X")

Jetzt sieht die von LEDs abgedeckte Fläche anders aus:

ledchaincover()

Resultat:

/* json */
{
  "x": 0,
  "y": 0,
  "dx": 17,
  "dy": 19
}

Das allein reicht noch nicht; nun muss die "Zeichenfläche" des Graphiksystems auch noch an die neue Grösse angepasst werden. Das heisst, der sogenannte root view des low resolution graphic-Systems (lrg) muss umkonfiguriert werden:

lrg.configure(ledchaincover()).set("fullframe",true)

Resultat:

/* lrgView */
{}

Damit ist die Konfiguration der "Zeichenfläche" (des rootview) für eine 17*19-Pixel-Darstellung auf der Fackel abgeschlossen.

Wer den (jetzt noch) leeren rootview inspizieren möchte, gibt ein:

lrg.status()

Resultat:

{
  "type": "stack",
  "label": "rootview",
  "x": 0,
  "y": 0,
  "dx": 17,
  "dy": 19,
  "content_x": 0,
  "content_y": 0,
  "content_dx": 17,
  "content_dy": 19,
  "rotation": 0,
  "color": "FFFFFF",
  "bgcolor": "000000",
  "alpha": 255,
  "z_order": 0,
  "orientation": "right",
  "wrapmode": "clipXY",
  "mask": false,
  "invertalpha": false,
  "timingpriority": true,
  "animations": 0,
  "layers": [],
  "positioningmode": "noAdjust"
}

Was jedes einzelne der Attribute bedeutet, ist an anderer Stelle beschrieben. Aber es ist gut zu sehen, dass der rootview nun die Grösse 17*19 hat, und sein content ebenso.

Erster LED-Test

Um jetzt zu testen, ob das Ganze überhaupt funktioniert, möchten wir die LEDs zumindest mal leuchten sehen! Das Einfachste ist, die Hintergrundfarbe des rootview (im Moment noch: schwarz, siehe Eigenschaft bgcolor im Resulat von lrg.status() oben) zu setzen:

lrg.set('bgcolor', '#331100')

Jetzt sollte die ganze Fackel sanft orange leuchten!

Das #331100 ist als Web-Farbe zu verstehen, wie bei HTML/CSS, also #RRGGBB, mit RR=Rotanteil als Hexadezimalzahl von 0..FF, GG=Grün, BB=Blau. Das '#' kann auch weggelassen werden.

Stromverbrauchs- bzw. Leistungsbegrenzung

Um zu verhindern, dass die Helligkeit einer Animation die Möglichkeiten des Netzteils überschreitet und Abstürze verursacht, oder gar dem Netzteil schadet, gibt es eine in der Software eingebauten Mechanismus zur Leistungsbegrenzung.

Wieviel elektrische Leistung braucht dieses sanfte Orange denn?

currentledpower()

Resultat:

2045 // numeric

Dieser Wert ist als mW (Milliwatt, 1/1000 Watt) zu verstehen, also braucht das Orange ca. 2W. Das ist keine Messung sondern ein berechneter Wert aufgrund der gerade eingestellten LED-Farben.

Bei den allermeisten Rpi-Netzteilen sollte es möglich sein, im Bereich 4W für die LEDs zu verbrauchen (zusätzlich zu dem, was der Rpi selber braucht). Also wollen wir den LED-Verbrauch sicherheitshalber mal auf 4W begrenzen:

setmaxledpower(4000)

Das bewirkt nun, dass die Gesamthelligkeit aller LEDs immer soweit heruntergeregelt wird, dass sie nie mehr als 4000mW = 4W verbrauchen. Das heisst, egal wie hoch die gewünschte Helligkeit gesetzt wird, es bleibt immer unter den 4W. Deshalb darf jetzt auch volle Helligkeit verlangt werden:

lrg.set('bgcolor', '#FFFFFF')

Jetzt ist die Fackel weiss, aber sehr moderat hell.

currentledpower()

...ergibt jetzt etwas in der Nähe des eingestellten Limits von 4000 (aber nicht exakt, weil die Helligkeit nicht beliebig genau geregelt werden kann).

Wieviel Leistung würde aber benötigt, um die LEDs so leuchten zu lassen wie von der aktuellen Farbeinstellung eigentlich verlangt? Dafür gibts neededledpower():

neededledpower()

Resultat:

83657 // numeric

Das wären also satte 84W! Nicht ganz die weiter oben überschlagsmässig berechneten 100W, aber in der selben Grössenordung. Die Strombegrenzung hilft also, dass unbeschwert Effekte ausprobiert werden können, ohne dass der Raspberry dauernd abstürzt. Mit dem Vergleich der Ausgaben von currentledpower() und neededledpower() lässt sich feststellen, ob und wie weit die Strombegrenzung gerade eingreift und die Helligkeit reduziert.

Test des LED-Layouts

Mit dem Ändern der Hintergrundfarbe allein ist nicht zu sehen, ob die LED-Anordnung nun wirklich in beiden Richtungen auf die Fackel (ca.) passt, also ob die abgezählten 17*19 (in meinem Beispiel) stimmen. Aber wenn der beleuchtete Ausschnitt verschoben wird, dann schon:

// Zurueck zum Orange
lrg.set('bgcolor', '#331100')
// Verschieben nach oben
lrg.set('y', 5)

...und schwupp, sollten die untersten 5 Windungen der Fackel dunkel sein. Weil der rootview, also das orange 17*19-Viereck um 5 Pixel nach oben verschoben wurde. Analog dazu nach unten:

lrg.set('y', -5)

Dasselbe geht auch horizontal:

// Y wieder auf 0 zurück
lrg.set('y', 0)
// jetzt X um zwei Pixel verschieben
lrg.set('x', 2)

Das bewirkt nun einen dunklen vertikalen Streifen von 2 Pixel Breite entlang der "Naht", also dort wo der 17. Pixel der Windung auf den 1. Pixel der nächsten Windung trifft.

Je nach Aufwicklung ist der Streifen einigermassen senkrecht, aber da die Anzahl LEDs einmal rund um die Röhre gezählt selten genau aufgehen, und darum die LEDs der einzelnen Windungen nicht genau übereinander stehen, ist der Streifen meistens schräg auf die eine oder andere Seite. In meinem Beispiel habe ich so gemerkt, dass 17 zu grosszügig gezählt war, und 16 eigentlich besser stimmen würden.

Was tun?

Ganz einfach, das Layout kann jederzeit neu eingestellt werden:

removeledchains()
addledchain("WS2813.GRB:rpi:300:0:16:0:19:X")
lrg.configure(ledchaincover()).set("fullframe",true)

Das sind dieselben Befehle wie oben im Detail beschrieben, diesmal einfach mit 16 für die Anzahl LEDs rundherum statt 17.

Nun nochmals den X-Verschiebetest machen:

lrg.set('x', 2)

Und schon erscheint der schwarze Streifen ganz gut senkrecht.

Dauerhaftes Abspeichern des LED-Layouts

Hat bisher alles geklappt, ist die richtige LED-Layout-Konfiguration gefunden. Allerdings, wenn jetzt der Raspberry neustartet, sind diese interaktiv gegebenen Befehle vergessen und der Zustand ist wie am Anfang - passend für eine Linie, aber nicht für die Fackel.

Da wir für das Weitere nicht jedesmal das Layout neu eintippen wollen, verfrachten wir die Konfigurationsbefehle ins sogenannte mainscript. Das ist ein Script (Programm), das beim Aufstarten des P44-Raspberrys automatisch gestartet wird.

Die Oberfläche zum Eingeben und Verändern des Mainscripts ist auf der Seite "p44script.html" zu finden:

In der leeren Fläche die getestete LED-Konfiguration, inkl. sinnvoller Strombegrenzung eingeben - in unserem Beispiel, mit einigen Kommentaren als Gedankenstütze:

// die aktuelle Konfiguration entfernen
removeledchains()

// Im Beispiel sind es 300 WS2813-LEDs (GRB-Reihenfolge der Farbkanäle),
// und die "Torch" hat 16 (wie sich gezeigt hat, nicht 17) LEDs pro Windung
// und insgesamt 19 Windungen.
// Die LEDs sind von rechts nach links gewickelt (X rückwärts) -> X Option
addledchain("WS2813.GRB:rpi:300:0:16:0:19:X")

// den rootview auf die neue 16*19-Fläche einstellen
lrg.configure(ledchaincover()).set("fullframe",true)

// Strombegrenzung auf 4W = 4000mW
setmaxledpower(4000)

Nun "Save & restart" drücken, und von jetzt an startet der RPi jedesmal gleich mit der richtigen LED-Konfiguration.

Die Fackel!

Nach all diesen Vorbereitungen und Tests (die natürlich auch für andere LED-Layouts und Anwendungen genauso funktionieren), kann nun die eigentliche Fackel-Animation als "Lampe" eingerichtet werden.

Zuerst sollte der Rpi neu gestartet werden, damit die Fackel erstmal dunkel ist.

Es reicht aber auch, im REPL den Befehl restartapp() einzugeben - das startet nicht den ganzen RPi neu, aber die darauf laufende P44-app (namens vdcd), was für die folgende Konfiguration einem Neustart gleichkommt (aber schneller geht, ca. 10sek gegenüber ca. 1min für einen kompletten Neustart)

Neue Leuchten werden im Abschnitt "Hardware" der Weboberfläche definiert:

In dem erscheinenden Dialog sind die Felder wie gezeigt (natürlich mit angepassten Werten für size in X direction und size in Y direction, je nach Fackelgrösse).

Die einzelnen Felder:

Device Name

Name für diese "Leuchte" in der Weboberfläche - bei P44-DSB erscheint sie auch mit diesem Namen im Digital Strom-System.

Unique ID

Hier kann irgendetwas stehen, es muss aber eine eindeutige Zeichenkette für diese Leuchte sein, keine andere Leuchte darf denselben String verwenden.

Device x position in LED matrix

X-Position relativ zum Ursprung des rootview für die Leuchte. In diesem Beispiel wollen wir, dass die "Fackel"-Leuchte den gesamten rootview, also die gesamte Fackelfläche abdeckt, deshalb setzen wir den view der Leuchte in den Ursprung des rootview (x=0, y=0).

Size in x position in LED matrix

Grösse in X-Richtung. In diesem Beispiel soll die Leuchte den gesamten rootview abdecken, also nehmen wir hier die ganze Breite (16 im Beispiel).

Device x position in LED matrix

Y-Position

Size in y position in LED matrix

Grösse in Y-Richtung.

Z-Order

bei mehreren übereinandergelegten Leuchten-Ebenen bestimmt Z-Order die Reihenfolge. Die Leuchte mit der höchsten Z-Order ist die oberste Ebene. Hier verwenden wir die Fackel-Animation als Hintergrund, darum kann der Z-Order-Wert 0 bleiben.

Feature config

Hiermit wird bestimmt, welche Art von view für diese Leuchte verwendet werden soll. Wenn das Feld leer ist, wird lightspot angenommen. Wir schreiben torch, um die Fackel-Animation zu bekommen. An dieser Stelle kann auch ein JSON-Filename stehen, etwa "repeatingticker.json", doch mehr dazu später.

Nach dem Druck auf "Create Device" passiert noch nichts auf den LEDs, aber es erscheint eine Leuchte in der Liste:

Ein Click auf den Zahnrädchen-Knopf öffnet den Dialog zur Einstellung der output channels. Hier kann jetzt ausprobiert werden:

• Helligkeit (brightness) mit dem ersten Regler. Mal auf 50% aufdrehen, und die Fackelanimation erscheint in Weiss. Noch nicht so hübsch...
• Wenns nach Feuer aussehen soll, ist rot-orange eine gute Basis-Farbe. Also den Farbwinkel (hue) z.B. mal 42 einstellen... Nur: wo bleibt die Farbe?
• Die Saturierung (saturation) ist noch auf 0, deshalb keine Farbe: Also voll aufdrehen auf 100! So sieht's langsam ok aus.
• Jetzt kommen die Feinheiten: Mit brightness gradient wird die Ausstrahlung der einzelnen Funken beeinflusst, mit hue gradient die Farbänderung.
• Bei den gradient features lässt sich einstellen, wie die Gradienten verlaufen (linear, sin/cos, exponentiell, logarithmisch).

Je nach Einstellungen sieht es ganz anders aus als nach einer Fackel...

Mit folgenden Einstellungen gibts aber eine Animation, die besonders im Dunkeln sehr nach Feuer aussieht:

Als Szene speichern

Um diese Einstellungen zu speichern bzw. wieder aufrufbar zu machen, können sie in einer Szene gespeichert werden. Das geht genau gleich wie auch mit ganz normalen Leuchten - bei P44-DSB in Digital Strom über den Konfigurator oder die App, bei P44-LC gemäss Anleitung.

Laufschrift

Die ursprüngliche MessageTorch (s. ganz oben) konnte eine Laufschrift über der Fackelanimation anzeigen. Was damals hart in den C-Code einprogrammiert war, können wir hier ganz einfach als "Textlampe" zusammenclicken: Im "Hardware"-Tab nochmals "Create Device..." drücken, diesmal aber mit folgenden Parametern:

Die Unterschiede zur Einrichtung der Fackel (s. oben) sind:

• die Laufschrift wird mit Y=6 etwa in die Mitte der Fackel gelegt, und ist nur 7 Pixel hoch
• die Laufschrift soll über der Fackelanimation erscheinen, nicht darunter, deshalb setzen wir eine höhere Z-Order
• mit Feature Config plan44text.json verwenden wir eine vordefinierte Konfiguration von views, die eine einfache Laufschrift bilden. (Wer wissen will, wie der Aufbau ist, gibt json(readfile('+/plan44text.json')) im REPL ein...)

"Create Device" drücken, Zahnrädchen-Knopf drücken und Helligkeit ein bisschen aufdrehen, Farbe einstellen. Jetzt sollte "plan44.ch feature light +++" über die Mitte der Fackel laufen.

Wie den Text ändern?

Im REPL eingeben:

device('Laufschrift').view.findview('LIGHT').set('text', 'Frohe Festtage! *** ')

Scrollgeschwindigkeit langsamer einstellen?

// bis Firmware 2.7.0.33:
device('Laufschrift').view.set('stepx',0.5)
// ab Firmware 2.7.0.33
device('Laufschrift').view.set('step_x', 0.5)
// ..oder, eleganter:
device('Laufschrift').view.step_x = 0.5

Oder schneller?

device('Laufschrift').view.set('stepx',1.5)
// ab Firmware 2.7.0.33
device('Laufschrift').view.set('step_x', 1.5)
// ..oder, eleganter:
device('Laufschrift').view.step_x = 1.5

Wer weiterforschen und experimentieren will: Die Gesamtheit aller Views lässt sich immer mit

lrg.status()

...anschauen. Oder nur die zu einer bestimmten Leuchte gehörenden Views (die auch im lrg.status() zu sehen sind):

device('Laufschrift').view.status()

Damit sind wir am Ende dieses Tutorials - aber erst am Anfang dessen, was mit P44-DSB und P44-XX und WS281x-SmartLEDs alles gemacht werden kann ;-)

Viel Spass beim Experimentieren!

Feedback und Vorschläge zu diesem Tutorial nehme ich gerne entgegen!

Und hier noch wie versprochen...

Die ganze Konfiguration als Video

Das (stille) Video zeigt dieselben Schritte, die oben beschrieben sind, als Ablauf mit gleichzeitigem Blick auf den Bildschirm und die Fackel.