# CometVisu Backend for openHAB

This adds a backend for the web based visualization CometVisu <https://www.cometvisu.org>.
The CometVisu is a highly customizable visualization, that runs in any browser.
Unlike the browser based UI´s in openHAB, the CometVisu does not rely on sitemaps.
The layout is defined with an XML-based configuration file, which allows a multi column layout.

**Using newer versions of CometVisu (>=0.12)**

Newer versions of the CometVisu use openHABs native REST-API to communicate. So this backend is no requirement
to use the CometVisu with openHAB as backend. If you use an extra webserver to serve the CometVisu (or use the official and recommended
docker container of the CometVisu <https://hub.docker.com/r/cometvisu/cometvisu>) this binding is obsolete.
You only need this binding if you want to use openHABs internal webserver to serve the CometVisu.

**"PHP support for CometVisu"-binding is not needed anymore and has been deleted**

The additional "PHP support for CometVisu" binding is not needed anymore. It has been removed in openHAB 4.0. 
This binding provides everything that is needed to run CometVisu's own file-manager and editors. 
The only things that are not supported are plugins, that use PHP-Code.


## Requirements

*   openHAB 2.0 or greater
*   CometVisu 0.12.0 or greater <https://github.com/CometVisu/CometVisu/releases>

## Installation

*   Install the CometVisu addon
*   Enable the auto-download feature via configuration setting *OR*
*   Download the CometVisu release <https://github.com/CometVisu/CometVisu/releases> and extract the "release" folder (the one which contains the index.html file) of the downloaded archive somewhere on your openHAB server (make sure that openHAB can access that folder).

Note: You have to set the path to this folder in your configuration (webFolder).

## Configuration

### Server configuration via main UI

You can customize some settings of the CometVisu backend on the settings page in the "Other Services" section.
You can find the CometVisu configuration in the "ui" category.

### Via Config file

You can customize some settings of the CometVisu backend in a configuration file named 'cometvisu.cfg' which has to be created in the 'conf/services/' folder of your openHAB instance, if it does not exist.

The following settings are available:

Relative path to the folder the CometVisu client can be found (must point to the directory that contains the CometVisu's index.html file, which is usually the release-folder):

```
webFolder=\<absolute-path-to-your-local-cometvisu-copy\>
```

The alias where you can access the client e.g http://\<openhab-server\>:8080/\<webAlias\>/

```
webAlias=/cometvisu
```

Activate the automatic download if the CometVisu client.

```
autoDownload=true (default is false)
```

Please note that, when you activate this feature, the latest release of the CometVisu client is downloaded to your openHAb server.
The CometVisu is licensed under the GNU General Public License v3.0.
If you do not agree to this license, you must not activate this feature.

Enable icon mapping from openHAB-items to CometVisu-items (Note this is only needed if you use the automatic sitemap->config generation feature).

```
icons>enableMapping=true
```

List of mappings of structure: icons.mapping\>\<openhab-icon\>=\<cometvisu-icon\>

```
icons.mapping>firstfloor=control_building_int_og
cons.mapping>groundfloor=control_building_int_eg

```

The list of icons in the CometVisu is available at:

```
http://<openhab-server>:8080/<webAlias>/icon/knx-uf-iconset/showicons.php
```

You can also customize the mounted folders in the CometVisu manager. The CometVisu manager can only access
files/folders in the resource/config folder. In order to make other files of the CometVisu available mount points
are used and this feature is used in order to make the demo config folder accessible.
You can add further mount points if you need to access other resources in the cometvisu. Please keep in mind that
only subfolders of the CometVisu installation can be mounted, you cannot access paths outside this folder.

Default setting is: 

```
mount>demo=resource/demo
```

This mounts the `resource/demo` subfolder as `demo`-folder in the manager. By default these mounted folders
are not writeable, which means that you cannot create/edit files and folders in there. You can add some flags to
the mount entry to customize some settings, the available flags are:

```
w: mounted content is writeable
s: show subfolders in the mounted folder
```

A complete mount entry with these flags looks like this:

```
mount>designs=resource/designs:ws
```

### Override CometVisu files

You can create a folder called 'cometvisu' in openHAB's 'conf/' folder and create files there which should be used instead of CometVisu's own. For example, you can put all your customizations there (e.g. you config, custom.css, etc.).
So the CometVisu itself stays untouched and can easily be replaced with a new release.

Please use the same folder structure and file names as they are used in the CometVisu package.
For example if you want to replace the original config with your own copy the file to the following path:

```
'conf/cometvisu/config/visu_config.xml'
```

Or for design customizations use:

```
'conf/cometvisu/designs/metal/custom.css'
```

### Client configuration

If you don´t use the given example below, please make sure that you correctly configure openHAB as backend in the CometVisu-Config by adding `backend="openhab"` to the root pages-element (e.g. `<pages...backend="openhab"...>`)

It is a good start to use the new sitemap support, to get a working example config, which you can store an customize for your needs.
Open a sitemap in the CometVisu client like this:

```
http://<openhab-server>:8080/<webAlias>/?config=<sitemap-name>
```

You can use the editor to change and store this config.
You can start with the demo-sitemap to get a quick overview about how the CometVisu looks like.


## Examples

### Show how many lights are switched on

*   Items: uses the demo.items provided by openHAB
*   Config (please add the infoaction-plugin in pages->meta->plugins in your config in order to use this):

```
<infoaction>
	<label>Lights</label>
	<widgetinfo>
		<info format="%d">
			<address transform="OH:number" mode="read" variant="">number:Lights</address>
		</info>
	</widgetinfo>
	<widgetaction>
		<switch mapping="OnOff" styling="Red_Green">
			<address transform="OH:switch" variant="">Lights</address>
		</switch>
	</widgetaction>
</infoaction>
```

*   use it in navbar:

```
<pagejump target="Lights">
	<layout colspan="0" />
	<label>
		<icon name="control_building_empty" />Übersicht
	</label>
	<widgetinfo>
		<info format="%d">
			<layout colspan="0" />
			<address transform="OH:number" mode="read" variant="">number:Lights</address>
		</info>
	</widgetinfo>
</pagejump>
```

### Charts:

*   Items: see demo.items
*   Config:

```
<diagram height="300px" series="day" refresh="600">
    <rrd consolidationFunction="AVERAGE">Weather_Temperature</rrd>
    <rrd consolidationFunction="AVERAGE">Weather_Temp_Max</rrd>
    <rrd consolidationFunction="AVERAGE">Weather_Temp_Min</rrd>
</diagram>
```

some notes:

*   `consolidationFunction` is only obeyed, when the item is persisted by the rrd4j persistence service
*   Altough you have to define <rrd...>Item_name</rrd> for every line in the config, the used items do not have to be persisted by the rrd4j persistence service, any other service will work too, but you have to specify the service name as prefix to the item name, e.g.
`<rrd>mysql:Weather_Temp_Min</rrd>` to get the date from the mysql persistence service.
*   Currently the CometVisu-Chart-Backend can only generate charts from persisted Number-Items. Other item types are not supported.

### RSS-Log:

*   Items: no special item needed
*   Config:

```
<rsslog src="plugins/rsslog/rsslog.php" refresh="60" mode="last">
	<label>Events</label>
	<layout colspan="12" rowspan="9"/>
</rsslog>
```

*   Fill the log from a rule:

```
var content = "Call recevied from 123456",encode("UTF-8")
var tag = "Call".encode("UTF-8")
sendHttpGetRequest("http://<openhab-server>:8080/<webAlias>/plugins/rsslog.php?c="+content+"&t="+tag)
```

### RSS-Log from persisted item:

*   Items:

```
String Logger
```

*   Config:

```
<rsslog src="plugins/rsslog/rsslog_oh.php" refresh="60" filter="Logger">
	<label>Events</label>
	<layout colspan="12" rowspan="9"/>
</rsslog>
```

*   Fill the log from a rule:

```
# Message structure is <title>|<content>|<state>|<tags>
sendCommand(Logger,"Call received|Received call from 123456789|0|Call,Incoming")
# but you can also just use any string like
sendCommand(Logger,"Received call from 123456789")
```

### ColorItem (supported since CometVisu-Release 0.8.2) =>

```
<colorchooser>
  <label>Color</label>
  <address transform="OH:color" variant="rgb">ITEM_NAME</address>
</colorchooser>
```

## Known problems

Plugins that use custom PHP code, do not work when you use this binding to serve the CometVisu, currently these are:

* Direct influxdb support in diagrams
* TR064 plugin (use openHABs TR064 binding instead)
* upnpcontroller plugin

The sitemap support can only be used as a starting point for own customizations, e.g. you open an automatic generated config and store it in by CometVisu by using the editor. Then you start to customize it to your own needs. New items must by added by hand from the moment you stored and changed the generated config.

### 404 error

Please make sure that openHAB has the rights to read the configured \<webFolder\> folder.

### 403 error

If you get an 403 - Access Denied error, when you try to open the CometVisu in your browser you have not copied the correct release folder into the \<webFolder\> folder. Please check if there is a subfolder with the exact name "release/", which contains an index.html file and copy the content to the folder defined in the \<webFolder\>-property.

## Screenshots

some screenshots can be found here:

-   <https://knx-user-forum.de/forum/supportforen/cometvisu/26809-allgemeine-frage-wie-sieht-eure-cv-startseite-aus>

## Links

*   German CometVisu Support Forum: <https://knx-user-forum.de/forum/supportforen/cometvisu>
*   English User documentation for the CometVisu: <https://www.cometvisu.org/CometVisu/en/latest/manual/>
*   German user documentation for the CometVisu: <https://www.cometvisu.org/CometVisu/de/latest/manual/>
*   GitHub project page of the CometVisu: <https://github.com/CometVisu/CometVisu>
