OpenHAB Reporter
Discontinued. At some time in the future I might re-write it as an OpenHAB extension.
OHR is a TLA and stands for "OpenHAB Reporter". OpenHAB is "a vendor and technology agnostic open source automation software for your home". OHR is an aid to documenting an OpenHAB installation or writing a user manual for a smart home. OHR was born of my realisation that I should provide adequate documentation for my own smart home for the future when someone else takes it over.
OHR reads OpenHAB's JSON Database (currently only the file org.eclipse.smarthome.core.thing.Thing.json) and – currently – produces a report on the bindings therein, ordered by thing, bridge, model and binding. It also creates SVG diagrams with the same information for those who prefer pictures.
OHR stores all this information in a file tree that fits perfectly into a Dokuwiki installation. The generated text and diagrams contain hyperlinks that also work nicely with Dokuwiki.
OHR reports are generated by Freemarker using customisable templates. The SVG diagrams are generated using nidi3/graphviz-java and GraphViz and can also be customised to a certain extent.
OHR creates Dokuwiki text files, some of which also contain SVG data, in a hierarchical file tree that has the following structure:
<link prefix>/
bindings/
<binding name 1>/
auto-svg.txt
auto.txt
start.txt
models/
<model name>/
start.txt
auto.txt
bridges/
<bridge name>/
start.txt
auto.txt
things/
<bridge name>/
start.txt
auto.txt
<binding name 2>/
...
<binding name N>/
The "auto" files (those whose names start with "auto", i.e. auto-svg.txt, auto.txt) are (re)generated each time OHR is run, so previous versions are overwritten. OHR only creates "start" files (start.txt) if there is not already one there, so users can modify start files to their heart's content, knowing that the content will not be overwritten (unless something goes dreadfully wrong, of course, but you've made a backup anyway, haven't you?). Users are also free to add any further files to the file tree that are needed in their environment. Thus the documentation of the smart home system can be documented in the normal wiki fashion but with a snapshot of the actual OpenHAB system included and linkable.
OHR can now be started from the command line as well as from the packaged application.
To start OHR from the command line, use the file oh-report.sh that is in the distribution, or write an improved version yourself. If you issue the command oh-report.sh help, you should see the following:
usage: ohr <command> [ <args> ]
Commands are:
help Display help information
things create Thing report
ui run OHR with JavaFX UI
See 'ohr help <command>' for more information on a specific command.
To create a report, use the command oh-report.sh things, whose help is as follows:
NAME
ohr things - create Thing report
SYNOPSIS
ohr things [ {-o | --output} <output folder> ]
[ {-p | --prefix | --link-prefix} <link prefix> ]
[ {-z | --zip | --zipped-output} ] [--] [ <JSON DB folder> ]
OPTIONS
-o <output folder>, --output <output folder>
report output folder
-p <link prefix>, --prefix <link prefix>, --link-prefix <link prefix>
prefix for links in generated documents
-z, --zip, --zipped-output
make a .zip of the output folder
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<JSON DB folder>
folder containing the OpenHAB JSON DB Things or Items
Either of the commands oh-report.sh or oh-report.ch ui or running the packaged application will start the GUI version of OHR, as described below.
When OHR is started, the following window is displayed:
The "Run" tab is the only one that currently shows any content. The other form elements are used as follows:
| Label | Content | What | Usage |
|---|---|---|---|
| JSON Database | folder name | folder containing JSONDB | drag folder, click on field for a folder chooser, or type a folder name |
| Output | folder name | folder to create output in | drag folder, click on field for a folder chooser, or type a folder name |
| Link Prefix | Dokuwiki path | path in Dokuwiki format under Dokuwiki home where file tree will be installed | openhab:localhost, my:smart:home:report |
| Zipped Output | check box | whether to create a ZIP file instead of a file tree | currently unimplemented |
| Cancel button | terminate the application without running | ||
| Run button | run the application and terminate |
The following are some sample outputs generated by OHR.
This is not a page generated directly by OHR, but a hand-crafted Dokuwiki home page that points at reports generated for three different OpenHAB installations, s-oh-00, b-mq-00 and b-mq-02.
The following is the Dokuwiki page source that results in the above home page:
Home Page
==== s-oh-00 Bindings ====
{{page>openhab:s-oh-00:bindings:auto}}
==== b-mq-00 Bindings ====
{{page>openhab:b-mq-00:bindings:auto}}
==== b-mq-02 Bindings ====
{{page>openhab:b-mq-02:bindings:auto}}
openhab:s-oh-00, openhab:b-mq-00 and openhab:b-mq-02 are three link prefixes (see above) or Dokuwiki paths, each of which contains an OHR-generated subtree for each of three OpenHAB installations.
OHR is designed to work on MacOS, Linux, Unix, Windows and iOS. However, each of these platforms has slightly different conventions, for which a platform-specific class in OHR has to be modified. This is trivial for people with knowledge of the platforms. A little love for the platform is also necessary to ensure that all the application is well-behaved on that platform (i.e. it observes all the platform's conventions: look, feel and general good manners).
The only currently implemented platform is MacOS. Volunteers with a love for the other platforms will be supported as far as possible. More details can be found in the wiki.
OHR was implemented using Apache Netbeans 12.0 and Maven. Details of the various software versions used can be viewed in the file pom.xml. I'm aware that this is not very user-friendly, but it is currently the only way I know of pointing you in the right direction even after something changes...
To build your own version, clone the repository to somewhere in your file system, go there and execute the following command:
mvn clean install
This will create a MacOS application in target/OpenHAB Reporter.app and a JAR file in target/ohr-1.0.0-SNAPSHOT.jar. The JAR file can be run in situ using the rudimentary shell script oh-report.sh, which lives in the root folder of the OHR installation.
At an early stage of OHR development, OHR could be run from the command line. The code to do that is still in there, but I must confess that I have not tried it recently.
Please see the OHR wiki on Github for further information, background and plans for further development.