Programmierhandbuch

Mehrere Protokolle

Wir möchten es Programmierern so einfach wie möglich machen, mit unseren Lampen und LED Computern zu kommunizieren. Deshalb sind unsere Protokolle vollständig offen. Unsere LED Computer sprechen verschiedene, von uns selbst entwickelte Protokolle. Ihnen stehen drei Protokolle zur Verfügung: ArtiAPI, ArtiNET und ArtiTCP.

ArtiNET ist das Protokoll, über das unsere Geräte untereinander kommunizieren. Es basiert auf TCP und eignet sich für Echtzeitkommunikation. Die Kommunikation erfolgt per effizienter Socket-Programmierung mit einfachen Byte-Streams. Damit ist alles möglich, Sie müssen allerdings vieles selbst regeln.

ArtiTCP ist das Protokoll, über das unser Hub mit unseren Geräten kommuniziert. Es basiert ebenfalls auf TCP, ist jedoch textbasiert und nicht für Echtzeitkommunikation geeignet. Mit ArtiTCP lässt sich zudem die gesamte Lampe bzw. der gesamte LED-Controller steuern, zum Beispiel für ein Software-Update.

ArtiAPI basiert auf HTTP/HTTPS REST und arbeitet mit JSON. Dieses Protokoll bringt deutlich mehr Intelligenz mit und nimmt Ihnen viel Arbeit ab, ist jedoch nicht für Echtzeitanwendungen geeignet.

Multi-Client-Kommunikation

Unsere LED Computer und Lampen sprechen sowohl ArtiNET als auch ArtiTCP. Beide Protokolle sind multiclientfähig. Das heißt, dass mehrere Geräte gleichzeitig mit einer Lampe oder einem LED-Controller kommunizieren können. Mit dem ArtiNET Protokoll geschieht dies zudem mit hoher Geschwindigkeit von bis zu 50 Änderungen pro Sekunde. Sie können sogar mit einem Controller einen Teil eines LED-Streifens oder einer Lampe bedienen, während ein ganz anderer Controller einen anderen Teil des LED-Streifens steuert.

Unser ArtiHUB spricht das ArtiAPI Protokoll. Über den Smart ArtiHUB und ArtiAPI lassen sich mehrere Lampen gleichzeitig ansteuern und zum Beispiel Szenen aufrufen. Über ArtiNET kommunizieren Sie dagegen immer direkt mit einem einzelnen Gerät.

Darüber hinaus können wir unseren Smart ArtiHUB auch mit anderen Geräten kommunizieren lassen, um sie in Szenen zu kombinieren. Denken Sie etwa an vorhandene Philips Hue Leuchten oder an Z-Wave-Leuchten über einen Fibaro Controller. So steuern Sie alles zentral über eine einzige API.

Zahlreiche Befehle

Unsere Protokolle umfassen zahlreiche Befehle. So gibt es Befehle zur Ansteuerung ganzer LED-Streifen oder einzelner Segmente davon, einzelner Pixel sowie mehrerer Segmente oder Pixel gleichzeitig. Sie können mit selbst definierten Farbpaletten arbeiten, und verschiedene Effekte sind bereits integriert. Mit Farben lässt sich rechnen, Muster lassen sich verschieben, Segmente tauschen und vieles mehr. Alle Befehle finden Sie in der Protokolldefinition – es sind schlicht zu viele, um sie hier aufzuzählen.

Auch lassen sich sehr viele Informationen aus einer Lampe oder einem LED-Controller abfragen: Wie viel Leistung wird verbraucht? Wie hoch war der maximale Verbrauch? Welche Temperaturen herrschen im Controller oder in der Lampe? Wie viele Befehle pro Sekunde wurden empfangen? Welche LEDs sind eingeschaltet? Wie viele LEDs sind eingeschaltet? Welche Farben sind aktiv? Die Möglichkeiten sind nahezu grenzenlos.

Und wenn etwas noch nicht möglich ist, überlegen wir gern gemeinsam mit Ihnen, wie wir es dennoch realisieren können. Bei Bedarf entwickeln wir sogar maßgeschneiderte Firmware und Produkte.

ArtiNET Protokoll

Das ArtiNET Protokoll haben wir entwickelt, um unsere Lampen und LED Computer so effizient wie möglich anzusteuern. Das Protokoll basiert auf einem TCP-Byte-Stream und ist vollständig offen. Das bedeutet, dass Sie alle Befehle einsehen können und wir erklären, was jeder einzelne bewirkt. Die Abbildung zeigt die Einordnung des Protokolls im OSI-Modell.

Das Protokoll beginnt immer mit einem Start-Byte, gefolgt von einem Command-Byte, das den auszuführenden Befehl enthält. Danach folgt stets ein Realtime-Byte, das angibt, ob es sich um einen Echtzeitbefehl ohne Antwort handelt oder ob eine Antwort erwartet wird. Das nächste Byte enthält den Kanal, für den der Befehl bestimmt ist. Kanal 0 bedeutet alle Kanäle. Anschließend folgt ein Amount-Byte, bestehend aus einem LSB/MSB-Byte, das die Anzahl der folgenden Daten-Bytes angibt. Danach folgen die eigentlichen Daten-Bytes wie angegeben und zum Schluss ein Stop-Byte.

Die vollständige ArtiNET Protokolldefinition können Sie über die Schaltfläche unten einsehen. Bei Fragen nehmen Sie gern Kontakt mit uns auf – wir unterstützen Sie gern. Lesen Sie aber auch weiter, um mehr über die Standardbibliotheken zu erfahren, die wir bereits anbieten.

ArtiNET Bibliotheken

Um Ihnen den Einstieg in das ArtiNET Protokoll zu erleichtern, haben wir eine Python- und eine PHP-Bibliothek geschrieben, inklusive einer Datei mit Beispielbefehlen. Die Python-Bibliothek eignet sich für Echtzeitkommunikation. PHP ist dafür leider weniger gut geeignet.

Es steht Ihnen natürlich frei, selbst mit TCP-Sockets zu programmieren. Sehen Sie sich dazu die Protokolldefinition oben an; unsere Bibliotheken können Ihnen dabei als Beispiel dienen. Und falls Sie selbst eine Bibliothek in einer anderen Programmiersprache entwickeln, würden wir uns freuen, wenn Sie diese im Interesse unserer anderen Kunden mit uns teilen.

Bitte beachten Sie, dass wir das ArtiNET Protokoll laufend weiterentwickeln. Prüfen Sie daher stets online, ob neuere Versionen der Bibliotheken verfügbar sind. Unsere Lampen und LED Computer aktualisieren ihre Bibliotheken bei einem Software-Update automatisch.

Klicken Sie auf die Schaltflächen unten, um unsere aktuellen Bibliotheken herunterzuladen.

ArtiTCP Protokoll

Das ArtiTCP Protokoll haben wir entwickelt, um unsere Lampen und LED Computer so einfach wie möglich anzusteuern. Das Protokoll basiert auf einem TCP-Stream mit lesbaren Textbefehlen und ist vollständig offen. Das bedeutet, dass Sie alle Befehle einsehen können und wir erklären, was jeder einzelne bewirkt. Die Abbildung zeigt die Einordnung des Protokolls im OSI-Modell.

Sie können eine einfache Telnet-Sitzung zum LED-Controller oder zur Lampe öffnen und direkt Befehle eingeben oder dies aus Ihrer Software heraus tun. Zuvor ist allerdings eine Authentifizierung mit einem Token erforderlich, das für jeden Controller bzw. jede Lampe eindeutig ist.

ArtiAPI Protokoll

Das ArtiAPI Protokoll haben wir entwickelt, um unsere Lampen und LED Computer zentral über den Smart Hub anzusteuern. Das Protokoll basiert auf einer HTTP(S)-REST-API und ist vollständig offen. Das bedeutet, dass Sie alle Befehle einsehen können und wir erklären, was jeder einzelne bewirkt. Die Abbildung zeigt die Einordnung des Protokolls im OSI-Modell.

Dazu gehört auch ein Discovery-Protokoll namens ArtiDISCOVERY, mit dem Sie den Smart Hub im Netzwerk finden. Über ArtiAPI erhalten Sie nach einer ersten Authentifizierung mit Benutzername und Passwort ein Token, mit dem Sie verschiedene Befehle an den Hub senden können, zum Beispiel zum Starten einer Szene. Der Smart Hub übernimmt anschließend die Kommunikation mit den Lampen und LED Computern.

Die vollständige ArtiAPI Protokolldefinition können Sie über die Schaltfläche unten einsehen. Bei Fragen nehmen Sie gern Kontakt mit uns auf – wir unterstützen Sie gern.