====== OpenHAB ======

===== Pre-requisites =====

  * Ubuntu 16.04 Long Term Support (LTS) (I used VirtualBox on MacOS)
  * Docker Community Edition (DockerCE) v17.12.0-ce

===== Basic Installation (OpenHAB 2) =====

<code:bash>
sudo useradd --system --shell $(which nologin) openhab
sudo usermod -aG $(whoami) openhab
sudo mkdir -p /opt/openhab/{addons,conf,userdata}
sudo chown -R openhab:openhab /opt/openhab
</code>

Create the following start-up file, I called mine ''/opt/openhab/run.sh'':

<code:bash>#!/bin/bash -x
CMD=(
    docker run
    --name openhab
    --net=host
    --interactive
    --tty
    -v /etc/localtime:/etc/localtime:ro
    -v /etc/timezone:/etc/timezone:ro
    -v /opt/openhab/conf:/openhab/conf
    -v /opt/openhab/userdata/:/openhab/userdata
    -v /opt/openhab/addons/:/openhab/addons
    -e USER_ID=$(id -u openhab)
    -e GROUP_ID=$(id -g openhab)
    #--restart=always
    openhab/openhab:2.3.0-snapshot-amd64-debian
)
"${CMD[@]}" || docker start --attach --interactive openhab
</code>

and then make it executable:

<code:bash>
sudo chmod a+x /opt/openhab/run.sh
</code>

===== Launch openHAB v2 and perform one-time setup =====

Note the IP address of the VM (e.g. ''ifconfig'' and find IP like ''192.168.1.125'')

<code:bash>
/opt/openhab/run.sh
</code>

at the prompt, run ''log:tail'' to follow the log and see the installation occur.

then point web-browser at TCP port 8080, e.g. http://192.168.1.125:8080/ and select STANDARD.

===== Enable legacy addon compatibility layer =====

As per https://docs.openhab.org/developers/development/compatibilitylayer.html#how-to-use-openhab-1x-add-ons-that-are-not-part-of-the-distribution

If you are currently tailing the log, you need to press ^C (CTRL + C) to cancel that and get the prompt back, where you run:

<code>
openhab> feature:install openhab-runtime-compat1x
openhab>
</code>

then follow the logs again by running

<code>
openhab> log:tail
</code>

===== Manually pairing and testing control via LightwaveRF Wi-Fi Link =====

Fear, uncertainty, and doubt (FUD) caused me some issues when I was first installed the LightwaveRF bindings for openHAB, so I ended up using a manual method to pair **and** test my pairing.

Assuming you have not previously paired the device you are running openHAB on (VirtualBox VM in my case) with the LighwaveRF Wi-Fi Link the following command will cause its green LED to blink, inviting you to press the LINK button. (I understand that newer models which have a screen ask you if you want to pair a new app).

<note tip>You may need to ''sudo apt install socat''</note>

<code>
echo -ne '100,!F*p' | socat STDIN UDP-DATAGRAM:255.255.255.255:9760,broadcast,sourceport=9761
</code>

The LightwaveRF Wi-Fi Link will ask you to accept the pairing (blinking LED on my model). Do so. The LightwaveRF Wi-Fi Link will now accept commands originating from your system (identified by its Ethernet MAC address). So in the case of my Virtual Machine, the virtual NIC's MAC is what is important.

I tested control by running the following to send commands to the first light in the first room I ever linked to the LightwaveRF Wi-Fi Link (the LWLink learnt of this device when I added it to the [[https://play.google.com/store/apps/details?id=com.dolphin.lightwaverf.tcg|Android app]])

Room 1, Light 1, Function 0 (OFF):

<code>
echo -ne '100,!R1D1F0' | socat STDIN UDP-DATAGRAM:255.255.255.255:9760,broadcast,sourceport=9761
</code>

Room 1, Light 1, Function 1 (ON):

<code>
echo -ne '100,!R1D1F1' | socat STDIN UDP-DATAGRAM:255.255.255.255:9760,broadcast,sourceport=9761
</code>

<note tip>The LightwaveRF Link protocol is documented at https://api.lightwaverf.com/introduction_basic_comms.html</note>

===== Configuring the (not yet installed) LightwaveRF Bindings =====

Best to create the configuration file *before* installing the bindings to avoid some noisy start-up messages.

The instructions for the legacy (openHAB v1) bindings for LightwaveRF are [[https://github.com/openhab/openhab1-addons/wiki/LightwaveRF-Binding|here]].

Create a new file at ''/opt/openhab/conf/services/lightwaverf.cfg'' (all files in this directory are named, so just ensure it is unique. Most guides call this file ''openhab.cfg''), and enter the following:

<note important>Do **not** copy the sample at [[https://github.com/openhab/openhab1-addons/wiki/LightwaveRF-Binding|GitHub]], it has errors!

''lightwaveRf:ip'' should be ''lightwaverf:ip'' (note the case!) throughout, and the sendport and receiveport numbers are backwards!

</note>

<code:bash>################################### LightwaveRf Binding #####################################
#
# The IP Address of the LightwaveRf Wifi Link you can use the broadcast address (required)
lightwaverf:ip=255.255.255.255
# The port to monitor for messages you shouldn't need to change this
lightwaverf:receiveport=9761
# The port to send messages on, it will also be monitored for incoming messages
# you shouldn't need to change this
lightwaverf:sendport=9760
# For a new computer you will need to register it with the wifi link to be allowed to send messages
# setting this to true we will send a registration message on startup. You will need to confirm
# registration on the wifi link. There is no harm leaving this as true but you can set to false
# once you have registerd for the first time.
lightwaverf:registeronstartup=false
# Delay between sending messages in ms to avoid swapming Wifi Link
lightwaverf:senddelay=2000
# Timeout for OK Messages in ms, we will retry messages we don't receive an ok for in the timeout
lightwaverf:okTimeout=1000
</code>

===== Install legacy OpenHAB v1 add-on for LightwaveRF =====

Find the URL for "openHAB Runtime 1.x Addons" at http://www.openhab.org/downloads.html, when I wrote this it was ''https://bintray.com/openhab/mvn/download_file?file_path=org%2Fopenhab%2Fdistro%2Fopenhab%2F1.11.0%2Fopenhab-1.11.0-addons.zip''

<code:bash>
cd /opt/openhab/addons
wget -O openhab-1.11.0-addons.zip \
    https://bintray.com/openhab/mvn/download_file?file_path=org%2Fopenhab%2Fdistro%2Fopenhab%2F1.11.0%2Fopenhab-1.11.0-addons.zip
</code>

then extract just the addon needed (try ''unzip -l openhab-1.11.0.addons.zip'' to list them):

<code:bash>
unzip openhab-1.11.0-addons.zip org.openhab.binding.lightwaverf-1.11.0.jar
</code>

You should see the following:

<code>
22:48:21.683 [INFO ] [htwaverf.internal.LightwaveRfWifiLink] - LightwaveRfWifiLink Connection Stopped
22:48:21.735 [INFO ] [ghtwaverf.internal.LightwaveRfBinding] - LightwaveBinding: IP[192.168.1.50]
22:48:21.739 [INFO ] [ghtwaverf.internal.LightwaveRfBinding] - LightwaveBinding: ReceivePort[9760]
22:48:21.740 [INFO ] [ghtwaverf.internal.LightwaveRfBinding] - LightwaveBinding: Send Port[9761]
22:48:21.740 [INFO ] [ghtwaverf.internal.LightwaveRfBinding] - LightwaveBinding: Register On Startup[false]
22:48:21.741 [INFO ] [ghtwaverf.internal.LightwaveRfBinding] - LightwaveBinding: Send Delay [2000]
22:48:21.741 [INFO ] [ghtwaverf.internal.LightwaveRfBinding] - LightwaveBinding: Timeout for Ok Messages [1000]
22:48:21.742 [INFO ] [htwaverf.internal.LightwaveRfWifiLink] - Starting LightwaveRfWifiLink Connection
</code>

If you change the configuration file, you can restart (all) legacy openHAB v1 bindings by restarting the compatibility layer bundle from the interactive prompt of OpenHAB (the ''/opt/openhab/run.sh'' script):

<code>
bundle:restart "openHAB 1.x Compatibility Layer"
</code>