Vorsicht

Dies ist die Dokumentation des aktuellen Entwicklungszweigs der CometVisu. Es besteht daher die Möglichkeit, dass einige der hier beschriebenen Features mit dem aktuellsten Release der CometVisu nicht genutzt werden können.

Grundsätzlicher Aufbau

Auf der obersten Ebene enthält eine Tile-Datei zunächst einen Meta-Bereich (<cv-meta>) in dem nicht sichtbare Einstellungen enthalten sind die für diese Konfigurationsdatei benötigt werden (z.B. Verbindungen zu Backends, das Laden von zusätzliche Dateien usw.). Der sichtbare Bereich gliedert sich in einen <header>- (Kopfzeile) einen <main>- (der eigentliche Inhalt) und einen <footer>-Bereich (Fußzeile). Die Kopf- und Fußzeile sind optional und können weggelassen werden.

<config>
    <cv-meta>
        <!-- Nicht sichtbare Konfigurations-Elemente -->
    </cv-meta>
    <header>
        <!-- Optionaler Inhalt oben -->
    </header>
    <main>
        <!-- Hauptinhalt inkl. optionaler Seitenleisten -->
    </main>
    <footer>
        <!-- Optionaler Inhalt unten -->
    </footer>
</config>

Im <main>-Bereich wird der Inhalt in Kacheln dargestellt (engl. Tile) die in verschiedenen Seiten (<cv-page>) angeordnet sind. Für häufig benötigte Dinge liefert die Tile-Struktur bereits Kacheln mit vor-definiertem Inhalt mit (im folgenden Widgets genannt). So enthält das Switch-Widget z.B. einen Button in der mittleren Zelle und zentrierten Text in der Zeile darunter.

Meta-Bereich

Im Meta-Bereich (<cv-meta>) finden sich alle Einstellungen, die für diese Konfigurationsdatei benötigt werden. Dazu gehören z.B. die Verbindungen zu den Backends, die Mappings, Stylings und Loader.

<cv-meta>
    <cv-backend type="openhab" uri="/rest/" />
    <cv-backend name="si" default="true" type="simulated"/>
    <cv-backend name="mqtt" type="mqtt" uri="ws://mqtt:9001/"/>
    <cv-mapping name="light">
        <entry value="0">ri-lightbulb-line</entry>
        <entry value="1">ri-lightbulb-fill</entry>
    </cv-mapping>
    <cv-mapping name="speaker">
        <entry value="0">ri-speaker-line</entry>
        <entry value="1">ri-speaker-fill</entry>
    </cv-mapping>
    <cv-styling name="WindowOpen">
        <entry range-min="1">red</entry>
    </cv-styling>
    <cv-mapping name="PlayProgress">
        <formula>y = Math.round(100/store.get('duration')*x)</formula>
    </cv-mapping>
    <cv-styling name="button">
        <entry value="0">inactive</entry>
        <entry range-min="1">active</entry>
    </cv-styling>
    <cv-loader type="css" src="resource/config/media/example.css" />
    <cv-loader type="js" src="resource/config/media/example.js" />
    <cv-loader type="templates" src="resource/config/media/my-templates.xml" />
</cv-meta>

Widgets

Ein Widget ist eine Kachel mit einer oder mehreren Komponenten mit der eine bestimmte Funktion erfüllt wird. Damit können übliche Anwendungsfälle innerhalb eines Smart-Homes abgedeckt werden, wie z.B. Lichtschalter (Switch) oder die Bedienung einer Rolllade (Shutter).

../../_images/cv-switch-on.png

Das Switch Widget Einfacher Schalter, Taster oder Trigger
../../_images/cv-dimmer.png

Das Dimmer Widget Schalter mit zusätzlichem Slider zur Einstellung eines Prozentwerts.
../../_images/cv-shutter.png

Das Shutter Widget Taster für hoch/runter/stop zur Bedienung einer Jalousie
../../_images/cv-info.png

Das Info Widget Darstellung eines Werts in verschiedenen Arten.
../../_images/cv-status.png

Das Status Widget Status Anzeige in halber Kachel-Höhe
../../_images/cv-small-status.png

Das kleine Status Widget Status Anzeige in Button-Größe
../../_images/cv-status-chart.png

Das Status-Chart Widget Status-Widget mit Chart im Hintergrund
../../_images/cv-rtc.png

Das RTC Widget Raumtemperatursteuerung mit Einstellungen für HVAC und einer Solltemperatur
../../_images/cv-media-player.png

Das Media-Player Widget Steuerung eines Medien-Abspielers mit Start/Stop vor & zurück und einer Lautstärkeregelung
../../_images/cv-widget-pair.png

Das Widget-Pair Ermöglicht es zwei Kacheln in halber Höhe darzustellen
../../_images/cv-energy-full.png

Das Energy Widget Zeigt Energieflüsse innerhalb eines Hauses an

Eigene Widgets definieren

Sofern die vorhandenen Widgets nicht ausreichen, kann man sich auch eigenen Widgets definieren. Die Definition eines neuen Widgets erfolgt in einem <cv-widget>-Element. Dieses besteht aus dem eigentlichen Inhalts-Element <cv-tile> und jeweils einem optionalen <header>- und <footer>-Element. Die Inhalte in den Kacheln sind in maximal 3 Zeilen mit jeweils 3 Spalten angeordnet, wobei hier ähnlich wie in Tabellen ein Inhaltselement mehrere Zeilen und / oder Spalten belegen kann.

../../_images/tile-grid.png

Innerhalb der Zellen einer Kachel können nun die von der Tile-Struktur bereitgestellten Komponenten frei platziert werden. Beispiele für diese Komponenten sind z.B. einfacher Text, ein Button, Bild oder komplexere Anzeigeelemente wie Listen.

Am einfachsten erstellt man sich erst mal eine Kachel mit allen benötigten Komponenten an den gewünschten Stellen in seiner normalen Konfigurationsdatei. So kann man Aussehen und Funktionalität am besten testen. Das folgende Beispiel zeigt eine Kachel in der ein runder Fortschrittsbalken und ein Text angezeigt wird.

<cv-widget>
    <cv-tile>
        <cv-row colspan="3" row="2">
            <cv-value format="%d%%">
                <cv-address transform="OH:number" mode="read" backend="si">Test_Value</cv-address>
                <cv-round-progress class="value"/>
            </cv-value>
        </cv-row>
        <cv-row colspan="3" row="last">
            <label class="secondary">Circle Progress</label>
        </cv-row>
    </cv-tile>
</cv-widget>

Diese Kachel-Konfiguration muss nun in ein Template übertragen werden. Dazu muss man sich zunächst eine Template-Datei anlegen. Das geht am besten über den Manager indem man im Order „media“ eine Datei mit Namen „my-templates.xml“ erzeugt. Damit diese Templates geladen werden fügt man in der Konfigurationsdatei im Meta-Bereich einen Loader hinzu.

<cv-meta>
    <cv-loader type="templates" src="resource/config/media/my-templates.xml" />
</cv-meta>

In diese Datei kopiert man nun alles was zwischen <cv-widget> und </cv-widget> steht. Sie sollte dann folgenden Inhalt enthalten:

<templates structure="tile">
    <template id="meter">
        <cv-tile>
            <cv-row colspan="3" row="2">
                <cv-value slot-format="%d%%">
                    <slot name="address"/>
                    <cv-round-progress class="value"/>
                </cv-value>
            </cv-row>
            <cv-row colspan="3" row="last">
                <label class="secondary"><slot name="label"/></label>
            </cv-row>
        </cv-tile>
    </template>
</templates>

Man sieht innerhalb der Template-Definition mit der id „meter“ den leicht modifizierten Inhalt der Kachel. Modifiziert werden müssen lediglich Inhalte die man später konfigurierbar haben möchte. In der Regel gehören dazu Adressen, Label und ggf. einige Attribute wie Mappings, Stylings und Formatierungen.

Wenn man nun dieses Template in der Konfigurationsdatei benutzen möchte fügt man dort ein <cv-meter> Element hinzu. Der Name ergibt sich aus der Template ID mit dem Präfix cv-.

Das Prinzip der <slot>-Elemente ist relativ einfach, sie dienen als Platzhalter für Elemente die diesen Slot benutzen. In dem Beispiel gibt es zwei Slot-Elemente: einen für die Adresse des Value-Elements: <slot name="address"/> und einen für das Label: <slot name="label"/>.

Daraus ergibt sich folgender Code mit dem man das neu definierte Template-Widget nun nutzen kann.

<custom>
    <cv-meter>
        <cv-address slot="address" transform="OH:5.001" mode="read">1/4/0</cv-address>
        <span slot="label">Circle Progress</span>
    </cv-meter>
</custom>

Da selbst definierte Template-Widgets dem offiziellen Schema der CometVisu-Konfigurationsdateien nicht bekannt sind, muss man diese in ein <custom>...</custom> Element packen, damit die Konfigurationsdatei nicht als ungültig erkannt wird. Damit verliert man an dieser Stelle aber den Vorteil, dass dieser Teil der Konfigurationsdatei auf Gültigkeit geprüft werden kann. Sofern man darauf werden legt, kann auch eine Erweiterung des Schemas vorgenommen werden, in dem das eigene Widget eingetragen wird. Dazu muss die Datei „custom_visu_config.xsd“ im „config/“ Ordner vorhanden sein. Sofern sie nicht vorhanden ist, muss sie mit folgender Grundstruktur angelegt werden.

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xml="http://www.w3.org/XML/1998/namespace">
    <!-- uncomment the next line if you want to reference types from the main pure schema -->
    <!-- <xsd:include schemaLocation="../visu_config.xsd"/> -->
    <!-- uncomment the next line if you want to reference types from the main tile schema -->
    <!-- <xsd:include schemaLocation="../visu_config_tile.xsd"/> -->
    <xsd:group name="CustomWidgets">
        <xsd:choice>
            <!-- reference new widgets here, e.g.
                <xsd:element name="cv-music-player" type="cv-music-player" />
            -->
        </xsd:choice>
    </xsd:group>
    <!-- add definition for new widgets here -->
    <!-- <xsd:complexType name="cv-music-player">...</xsd:complexType> -->
</xsd:schema>

Das vollständige Beispiel für das <cv-meter>-Widget sieht so aus.

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xml="http://www.w3.org/XML/1998/namespace">
    <xsd:include schemaLocation="../visu_config_tile.xsd"/>
    <xsd:group name="CustomWidgets">
        <xsd:choice>
            <xsd:element name="cv-meter" type="cv-meter" />
        </xsd:choice>
    </xsd:group>
    <xsd:complexType name="cv-meter">
        <xsd:sequence>
            <xsd:element name="span" minOccurs="0">
                <xsd:complexType>
                    <xsd:simpleContent>
                        <xsd:extension base="xsd:string">
                            <xsd:attribute name="slot" use="required">
                                <xsd:simpleType>
                                    <xsd:restriction base="xsd:string">
                                        <xsd:enumeration value="label" />
                                    </xsd:restriction>
                                </xsd:simpleType>
                            </xsd:attribute>
                        </xsd:extension>
                    </xsd:simpleContent>
                </xsd:complexType>
            </xsd:element>
            <xsd:element name="cv-address" maxOccurs="unbounded">
                <xsd:complexType>
                    <xsd:simpleContent>
                        <xsd:extension base="address">
                            <xsd:attribute name="slot" use="required">
                                <xsd:simpleType>
                                    <xsd:restriction base="xsd:string">
                                        <xsd:enumeration value="address" />
                                    </xsd:restriction>
                                </xsd:simpleType>
                            </xsd:attribute>
                        </xsd:extension>
                    </xsd:simpleContent>
                </xsd:complexType>
            </xsd:element>
        </xsd:sequence>
        <xsd:attribute ref="format" />
    </xsd:complexType>
</xsd:schema>

Danach kann das <cv-meter>-Widget ohne <custom>...</custom> benutzt werden und es wird auch auf Gültigkeit geprüft.

Komponenten

Eine Komponente ist ein einzelnes visuelles Element, das entweder bedienbar (z.B. Button) oder zur reinen Darstellung eines Werts benutzt wird (z.B. Value). Die bereits vorgestellten Widgets kombinieren eine oder mehrere Komponenten in einer Kachel.

Sonstiges

Weitere Elemente die keine eigenständige Komponenten sind aber in diesen benutzt werden können.