CCU.IO ist eine auf Node.js basierende Applikation die die Möglichkeiten einer HomeMatic CCU erweitert. CCU.IO kommuniziert über das "BIN-RPC"-Protokoll mit rfd (HomeMatic Funk-Komponenten), hs485d (HomeMatic Wired-Komponenten) und CUxD (FS20, EnOcean, ...), außerdem wird auch die Logikschicht ("ReGaHSS") der HomeMatic CCU eingebunden.
CCU.IO kann mit seinem integrierten Webserver als Basis für Web-basierte Visualisierungen dienen und ermöglicht durch die Nutzung der Socket.IO Bibliothek Web-Oberflächen Events von der CCU nach dem Push-Prinzip zu empfangen. Ein Ressourcenintensives Polling entfällt somit und die Visualisierung stellt geänderte Status mit geringerer Latenz dar. Darüberhinaus fungiert CCU.IO hier als Proxy - egal wieviele Visualisierungs-Instanzen geöffnet sind - die Belastung für die HomeMatic CCU bleibt gleich gering.
CCU.IO ist in der Lage Fremd-Systeme über sogenannte Adapter anzubinden. Bisher existieren Adapter für Philips Hue, Sonos, IRTrans, die Anbindung an eine MySQL-Datenbank und diverse WebServices (Wettervorhersage, Pushover, ...). Weitere Adapter sind in Planung und Entwicklung.
Die in CCU.IO integrierte Script-Engine ermöglicht es Automatisierungs-Aufgaben via JavaScript zu implementieren, es stehen hier alle Möglichkeiten von Node.js zur Verfügung, z.B. Zugriffe auf das Dateisystem, Netzwerkkommunikation u.v.m. Darüberhinaus können beliebige Node.js Module eingebunden werden.
CCU.IO ist freie Software, nicht-kommerzielle Nutzung ist für jedermann kostenlos möglich. Weitere Informationen zu den Lizenz-Bedingungen
CCU.IO benötigt Node.js (Version >= 0.8). Links zu Node.js Downloads sind im Download-Bereich zu finden.
node ccu.io-server.js start (unter Windows: node.exe ccu.io-server.js start)Auf dem Raspberry Pi einloggen und folgende Befehle ausführen um Node.js und CCU.IO zu installieren:
wget http://ccu.io.mainskater.de/nodejs_0.10.22-1_armhf.deb
wget http://ccu.io.mainskater.de/ccu.io_1.0.29.deb
sudo dpkg -i nodejs_0.10.22-1_armhf.deb
sudo dpkg -i ccu.io_1.0.29.debSGiersch hat in seinem Wiki die Erstellung eines Start-Scripts dokumentiert.
Die automatische Installation über .pkg ist in Vorbereitung/Entwicklung.
Die automatische Installation über .msi ist in Vorbereitung/Entwicklung.
Hinweis: die Installation auf einer CCU2 ist machbar - wird aber wegen mangelhafter Performance nicht empfohlen.
Die automatische Installation über ein .tar.gz ist in Vorbereitung/Entwicklung
Wird eine bestehende CCU.IO Installation Version 0.9.x aktualisiert müssen alle Settings neu vorgenommen werden, es findet keine Übernahme der alten Settings statt.
Wenn Port 8080 bereits belegt ist kann CCU.IO nicht starten. Dann bitte vorübergehend den Dienst der Port 8080 belegt beenden, CCU.IO starten, Port in Settings ändern.
CCU.IO wurde bisher erfolgreich auf folgenden Plattformen installiert:
Die Konfiguration von CCU.IO wird über die Weboberfläche (Reiter "CCU.IO"->"Settings") vorgenommen. Die Konfiguration der Adapter ist im Reiter "Adapter" zu finden. (Button Configure in der Adapter-Tabelle). Eine Änderung der Konfiguration (sowohl von CCU.IO selbst als auch die der Adapter) erfordert immer einen Neustart.
Die IP-Adresse der HomeMatic CCU. Bitte beachten dass Zugriffe nicht von der CCU-Firewall geblockt werden (sowohl für "HomeMatic XML-RPC API" als auch für "Remote HomeMatic-Script API").
Die IP-Adresse des Hosts auf dem CCU.IO selbst läuft. Wird der CCU mitgeteilt damit diese Kenntnis davon hat unter welcher Adresse sie CCU.IO erreichen kann
Wenn aktiviert werden im angegebenen Intervall Informationen zur Anzahl der von der CCU empfangen Events sowie die Anzahl verbundener Clients ins Logfile geschrieben.
Wenn aktiviert werden alle Events und Variablenänderungen geloggt. Notwendig für die Nutzung der Addons Highcharts und Eventlist. Write Interval gibt an wie oft die Daten vom RAM auf den Datenträger geschrieben werden sollen.
Aktiviert die Script-Engine. Longitude und Lattitude (Längen- und Breitengrad) sind notwendig für die Astro-Funktion (Berechnung Sonnenaufgang/untergang) der Script-Engine.
Hier können die Webserver für http und https getrennt aktiviert werden und die zu verwendenden Ports konfiguriert werden. Außerdem ist es möglich ein Username und ein Passwort für "HTTP Basic Auth" anzugeben und die Authentifizierung getrennt für HTTP und HTTPS zu aktivieren.
Hier müssen je nach vorhandener Hardware die Inits für Funk-Komponenten (rfd), Wired-Komponenten (hs485d) und CUxD Geräte aktiviert werden
Wird "Check RPC Events" aktiviert prüft CCU.IO alle 3 Minuten ob ein Event von rfd und ggf. hs485d empfangen wurde, falls nicht wird versucht über den Druck auf einen Virtuellen Taster ein Event zu "provozieren". Sollte nach weiteren 2 Minuten immer noch kein Event eingetroffen sein wird der RPC Init erneut durchgeführt. Dient dazu eventuell nicht mehr funktionierende RPC Inits zu erkennen und zu verhindern.
Ist Polling aktiviert fragt CCU.IO im angegebenen Intervall den Status von Systemvariablen von der CCU ab.
Bei aktivierten Polling-Trigger wird immer wenn ein PRESS_SHORT Event auf dem angegeben virtuellen Taster empfangen wird der Zustand der Systemvariablen von der CCU abgefragt. Somit kann quasi ein "pseudo-Push" Mechanismus für Systemvariablen geschaffen werden. Hierzu ist es dann notwendig auf der CCU ein Programm anzulegen das bei Änderung von relevanten Systemvariablen den kurzen Tastendruck auf dem angegebenen virtuellen Taster durchführt.
Einstellungen und Dateien in den Verzeichnissen datastore, log, scripts und www sollten Updates unbeschadet überstehen, es empfiehlt sich natürlich dennoch vor jedem Update ein Backup der gesamten CCU.IO Installation durchzuführen.
CCU.IO kann (ab v1.0.4) "sich selbst" updaten. Einfach in der CCU.IO Oberfläche im Reiter CCU.IO-Info bei "available Version" nachsehen ob ein Update verfügbar ist (check-Button) und ggf. den Update-Button betätigen
Dieser Vorgang kann abhängig von der Internetanbindung und der Rechenleistung die CCU.IO zur Verfügung steht relativ lange dauern. Am besten ist es das CCU.IO-Logfile (log/ccu.io.log) während dieses Vorgangs im Auge zu behalten.
Das Changelog und die Roadmap werden im Readme auf GitHub gepflegt.
CCU.IO bietet neben der Möglichkeit via Socket.IO zu kommunizieren auch die "Simple API", eine auf HTTP-GET-Requests basierende Schnittstelle die Daten im JSON- oder Plain-Text-Format zurückliefert. Folgende Kommandos stehen zur Verfügung:
Ein Objekt abfragen. Liefert Daten im JSON-Format. Lässt sich auf alle Objekte im CCU.IO-regaObjects-Objekt anwenden.
Ein Objekt über die ID abfragen
http://ccu-io-host:ccu.io-port/api/get/950
Ein Objekt über den Namen abfragen
http://ccu-io-host:ccu.io-port/api/get/Anwesenheit
Ein Datenpunkt über den Kanal-Namen und den Datenpunktbezeichner abfragen
http://ccu-io-host:ccu.io-port/api/get/Licht-Küche/LEVEL
Ein Datenpunkt über die Kanal-Adresse und den Datenpunktbezeichner abfragen
http://ccu-io-host:ccu.io-port/api/get/FEQ1234567:1/LEVEL
Ein Datenpunkt über die BidCos-Adresse abfragen
http://ccu-io-host:ccu.io-port/api/get/BidCos-RF.FEQ1234567:1.LEVEL
Diese Methode liefert direkt den Wert eines Datenpunkts mit Content-Type text/plain. Bietet die gleichen Möglichkeiten einen Datenpunkt zu adressieren wie die Methode get. Diese Methode lässt sich im Gegensatz zur Methode get nur auf Variablen und Datenpunkte anwenden.
http://ccu-io-host:ccu.io-port/api/getPlainValue/950
Eine Variable oder einen Datenpunkt setzen. Bietet die gleichen Möglichkeiten einen Datenpunkt zu adressieren wie die Methode get, lässt sich aber nur auf Datenpunkte und Variablen anwenden.
http://ccu-io-host:ccu.io-port/api/set/BidCos-RF.FEQ1234567:1.LEVEL/?value=0.7
http://ccu-io-host:ccu.io-port/api/set/Licht-Küche/LEVEL/?value=0.7
http://ccu-io-host:ccu.io-port/api/set/Anwesenheit/?value=0
http://ccu-io-host:ccu.io-port/api/set/950/?value=1
Mehrere Datenpunkte auf einmal setzen
Diese Methode kann auch per POST aufgerufen werden, je nach Content-Type Header können die Daten als JSON oder form-encoded geliefert werden
Dieses Beispiel vereint alle 4 Beispiele aus der Methode set in einem Aufruf:
http://ccu-io-host:ccu.io-port/api/setBulk/?BidCos-RF.FEQ1234567:1.LEVEL=0.7&Licht-Küche/LEVEL=0.7&Anwesenheit=0&950=1
Ein Programm ausführen. Kann über ID oder Name angesprochen werden
http://ccu-io-host:ccu.io-port/api/programExecute/1205
http://ccu-io-host:ccu.io-port/api/programExecute/Alle-Lichter-an
http://ccu-io-host:ccu.io-port/api/getObjects
http://ccu-io-host:ccu.io-port/api/getIndex
http://ccu-io-host:ccu.io-port/api/getDatapoints
Eigene Scripte können einfach im Verzeichnis scripts abgelegt werden. Bitte beachten - wenn Änderungen an den Scripten erfolgen muss die Script-Engine neu gestartet werden (über Button in CCU.IO Oberfläche unter CCU.IO->Control machbar)
Folgende Node-Module werden von der Script-Engine bereits eingebunden und können in eigenen Script verwendet werden:
Zur verwendung in eigenen Scripten stehen folgende Funktionen zur Verfügung:
Etwas in ccu.io/log/ccu.io.log schreiben
git den Wert eines Datenpunktes zurück
Beispiele:
var val = getState(950);
var val = getState("Anwesenheit");
var val = getState("Licht Küche", "LEVEL")
var val = getState("BidCos-RF.FEQ12345678.LEVEL");Den Wert eines Datenpunktes ändern. ID kann eine ID, ein Name oder eine Adresse sein.
Ein Homematic Programm ausführen
Ein Objekt in die regaObjects einfügen
Weckt einen Rechner per Wake on Lan auf
Beispiele:
wol.wake("20:DE:20:DE:20:DE");
wol.wake("20-DE-20-DE-20-DE");
wol.wake("20DE20DE20DE");
Führt einen HTTP GET Request durch.
Beispiele:
request("http://user:pass@webservice.example.com/api/set/1");
var url = "http://user:pass@webservice.example.com/api/get";
request(url, function (error, response, body) {
log("webservice-abfrage "+url+" liefert zurück: "+body);
});
basiert auf dem Node-Package request, siehe auch.
Versendet eine Email
Beispiel:
email({
to: "ernie@sesamestreet.com",
subject: "ccu.io",
text: "alarm!!!"
});Diese Funktion erfordert dass der Email-Adapter konfiguriert und aktiviert wurde.
Versendet eine Pushover Benachrichtigung
Beispiel:
pushover({
message:"Das Fenster im Bad sollte geschlossen werden."
});Diese Funktion erfordert dass der Pushover-Adapter konfiguriert und aktiviert wurde.
Einen Event abbonieren. Das pattern-Objekt bietet folgende Attribute:
logic string "and" oder "or" Logik zum Verknüpfen der Bedingungen nutzen (default: "and")
id integer ID ist gleich
name string name ist gleich
RegExp name matched Regulären Ausdruck
change string "eq", "ne", "gt", "ge", "lt", "le"
"eq" Wert muss gleich geblieben sein (val == oldval)
"ne" Wert muss sich geändert haben (val != oldval)
"gt" Wert muss großer geworden sein (val > oldval)
"ge" Wert muss größer geworden oder gleich geblieben sein (val >= oldval)
"lt" Wert muss kleiner geworden sein (val < oldval)
"le" Wert muss kleiner geworden oder gleich geblieben sein (val <= oldval)
val mixed Wert ist gleich
valNe mixed Wert ist ungleich
valGt mixed Wert ist größer
valGe mixed Wert ist größer oder gleich
valLt mixed Wert ist kleiner
valLe mixed Wert ist kleiner oder gleich
ack bool Wert ist bestätigt
oldVal mixed vorheriger Wert ist gleich
oldValNe mixed vorheriger Wert ist ungleich
oldValGt mixed vorheriger Wert ist größer
oldValGe mixed vorheriger Wert ist größer oder gleich
oldValLt mixed vorheriger Wert ist kleiner
oldValLe mixed vorheriger Wert ist kleiner oder gleich
oldAck bool vorheriger Wert ist bestätigt
ts string Timestamp ist gleich
tsGt string Timestamp ist größer
tsGe string Timestamp ist größer oder gleich
tsLt string Timestamp ist kleiner
tsLe string Timestamp ist kleiner oder gleich
oldTs string vorheriger Timestamp ist gleich
oldTsGt string vorheriger Timestamp ist größer
oldTsGe string vorheriger Timestamp ist größer oder gleich
oldTsLt string vorheriger Timestamp ist kleiner
oldTsLe string vorheriger Timestamp ist kleiner oder gleich
lc string Lastchange ist gleich
lcGt string Lastchange ist größer
lcGe string Lastchange ist größer oder gleich
lcLt string Lastchange ist kleiner
lcLe string Lastchange ist kleiner oder gleich
oldLc string vorheriger Lastchange ist gleich
oldLcGt string vorheriger Lastchange ist größer
oldLcGe string vorheriger Lastchange ist größer oder gleich
oldLcLt string vorheriger Lastchange ist kleiner
oldLcLe string vorheriger Lastchange ist kleiner oder gleich
room integer Raum ID ist gleich
string Raum ist gleich
RegExp Raum matched Regulären Ausdruck
func integer Gewerk ID ist gleich
string Gewerk ist gleich
RegExp Gewerk matched Regulären Ausdruck
channel integer Kanal ID ist gleich
string Kanal-Name ist gleich
RegExp Kanal-Name matched Regulären Ausdruck
device integer Geräte ID ist gleich
string Geräte-Name ist gleich
RegExp Geräte-Name matched Regulären Ausdruck
channelType string Kanal HssType ist gleich
RegExp Kanal HssType matched Regulären Ausdruck
deviceType string Geräte HssType ist gleich
RegExp Geräte HssType matched Regulären Ausdruck
Der Callback-Funktion wird ein Objekt mit folgendem Inhalt als Parameter übergeben:
{
id,
name,
newState: {
value,
timestamp,
ack,
lastchange
},
oldState: {
value,
timestamp,
ack,
lastchange
},
channel: {
id,
name,
type,
funcIds,
roomIds,
funcNames,
roomNames
},
device: {
id,
name,
type
}
}
funcIds, roomIds, funcNames und roomNames sind Arrays (func = Gewerke)
Beispiel Briefkastenscript
Dieses Script zählt die Einwürfe in einen Briefkasten. id:11928 und change:"ne" gibt an dass sich der Wert des
Datenpunktes mit der ID 11928 geändert haben muss. Der Beispielhafte Datenpunkt 11928 ist hier der STATE Datenpunkt eines Eingangs
eines "HomeMatic-Funk-3fach-Schließerkontakt" Sensors an dem ein an der Briefkastenklappe angbrachter Microschalter
angeschlossen ist. Über eine setTimeout-Anweisung werden Einwürfe maximal alle 30 Sekunden gezählt. Die Anzahl der Einwürfe
wird hier Beispielhaft in die Variable mit der Id 100015 geschrieben. Die SetObject Anweisung legt die Variable mit der Id 100015 an und initialisiert sie mit dem Wert 0.
var einwurfTimer;
subscribe({id:11928, change:"ne"}, function (obj) {
if (!einwurfTimer) {
einwurfTimer = true;
setTimeout(function () {
einwurfTimer = undefined;
}, 30000);
setState(100015, 1 + getState(100015));
}
});
setObject(100015, {
Name: "Briefkasten",
TypeName: "VARDP"
}, function () {
setState(100015, 0);
});Zeitmodul mit Astrofunktion.
Pattern kann ein String in Cron-Syntax sein, z.B.:
schedule("*/2 * * * *", function () {
log("wird alle 2 Minuten ausgeführt!");
});
Pattern kann aber auch ein Objekt sein, insbesondere dann notwendig wenn man Sekundengenaue Ausführung benötigt:
schedule({second: [20, 25]}, function () {
log("Wird um xx:xx:20 und xx:xx:25 ausgeführt!");
});
schedule({hour: 12, minute: 30}, function () {
log("Wird um 12:30Uhr ausgeführt!");
});
Pattern kann auch ein Javascript-Date-Objekt (also ein bestimmter Zeitpunkt sein) - dann findet nur eine einmalige Ausführung statt.
Über das Attribut "astro" kann die Astrofunktion genutzt werden:
schedule({astro:"sunrise"}, function () {
log("Sonnenaufgang!");
});
schedule({astro:"sunset", shift:10}, function () {
log("10 Minuten nach Sonnenuntergang!");
});
Das Attribut shift ist eine Verschiebung in Minuten, kann auch negativ sein um die Events vorzuziehen.
Folgende Werte sind für das Attribut astro verwendbar:
Socket.IO ist nicht nur für die Kommunikation mit Web-Browsern der beste Weg mit CCU.IO zu kommunizieren. Es gibt Socket.IO Implementierungen für viele Sprachen, siehe https://github.com/learnboost/socket.io/wiki#in-other-languages
CCU.IO ruft bei jedem Event (Änderung oder Aktualisierung eines Datenpunkts oder einer Variable) die Methode "event" auf allen verbundenen Clients auf. Als Parameter wird ein Array mit folgender Struktur übergeben [id, val, timestamp, ack, lastchange]
Das Datenpunkt-Objekt von CCU.IO abfragen
Die Meta-Daten (regaObjects) von CCU.IO abfragen
Den Objekt-Index von CCU.IO abfragen
Einen Datenpunkt setzen.
Als Parameter wird ein Array mit folgender Struktur erwartet [id, val, timestamp, ack, lastchange]
Ein Homematic-Programm ausführen
Ein Homematic-Script ausführen
Lädt die Script-Engine neu. Notwendig wenn Änderungen an einem Script vorgenommen wurden.
Führt ein Shell-Commando aus. Callback wird mit 3 Parametern aufgerufen: error, stdout, stderr
Gibt den Inhalt eines bestimmten Verzeichnisses zurück. Die Methode callback wird mit einem Array des Verzeichnisinhalts zurückgerufen
Wandelt object in JSON um und schreibt es in die Datei name im datastore-Verzeichnis
List eine JSON Datei im datastore-Verzeichnis und gibt das geparste Objekt als Parameter an die callback Funktion zurück
Liest eine beliebige Datei (name kann auch einen Pfad beinhalten) und gibt das Ergebnis als String an die callback Funktion zurück. Der Pfad ist relativ zum ccu.io-Verzeichnis
List eine JSON Datei und gibt das geparste Objekt als Parameter an die callback Funktion zurück. Der Pfad ist relativ zum ccu.io-Verzeichnis
Eine URL via HTTP-GET aufrufen. Callback erhält den Body den Antwort. Geschickter Weg um die Same-Origin-Policy in Webanwendungen zu umgehen.
Liefert das CCU.IO Settings Objekt zurück
Liefert eine Objekt mit dem Inhalt der stringtable_de.txt von der CCU
Fügt eine Stringvariable auf der CCU hinzu. Liefert die neue ID an den Callback.
Ein Objekt zu regaObjects und regaIndex hinzufügen