Remote openHAB Binding

The Remote openHAB binding allows to communicate with remote openHAB servers. The communication is bidirectional. The binding on the local server listens to any item state updates on the remote server and updates accordingly the linked channel on the local server. It transfers any item command from the local server to the remote server. It can map any remote thing to a local thing. Through this mapping, in your rules (local server), you can take actions based upon status updates or status changes generated by remote things and you can take actions based upon trigger events generated by the trigger channels defined in the remote thing.

One use of this binding is to distribute your home automation system on multiple openHAB servers.

Another use is for users to interact with older versions of openHAB that may support old openHAB v1 bindings that were not migrated to openHAB v2 or openHAB v3. They can keep an openHAB v2 server to run their old openHAB v1 bindings and setup a new openHAB v3 server for everything else. The Remote openHAB binding installed on the openHAB v3 server will then allow to use the openHAB v1 bindings through communication with the openHAB v2 server.

A third usage is for users that would like to keep unchanged an existing openHAB v2 server but would like to use the new UI from openHAB v3; they can simply setup a new openHAB v3 server with the Remote openHAB binding linked to their openHAB v2 server.

Supported Things

There is two supported things : the server bridge thing representing a remote openHAB server and the thing thing representing a thing from the remote openHAB server.

Discovery

All openHAB servers in the local network are automatically discovered (through mDNS) by the binding. You will find in the inbox one discovery thing per remote server interface. So if your remote server has one IPv4 address and one IPv6 address, you will discover two things in the inbox. Just choose one of the two things.

Once a bridge thing representing a remote openHAB server is created, all things from this remote server will be discovered when you scan for new things.

Binding Configuration

The binding has no configuration options, all configuration is done at Thing level.

Thing Configuration

The server thing has the following configuration parameters:

Parameter	Required	Description
host	yes	The host name or IP address of the remote openHAB server.
useHttps	no	Set to true if you want to use HTTPS to communicate with the remote openHAB server. Default is false.
port	yes	The HTTP port to use to communicate with the remote openHAB server. Default is 8080.
trustedCertificate	no	Set to true if you want to use HTTPS even without a valid SSL certificate provided by your remote server.
restPath	yes	The subpath of the REST API on the remote openHAB server. Default is /rest
token	no	The token to use when the remote openHAB server is setup to require authorization to run its REST API.
accessibilityInterval	no	Minutes between checking the remote server accessibility. 0 to disable the check. Default is 3.
aliveInterval	no	Number of last minutes to take into account to determine whether the remote server is alive. 0 to disable this feature. Default is 5.

The thing thing has the following configuration parameters:

Parameter	Required	Description
thingUID	yes	The thing UID in the remote openHAB server.
buildTriggerChannels	no	If set to true, a trigger channel will be automatically created and linked to each trigger channel from the remote thing. Default is true.

Please note that if your remote server is an openHAB v3 server, you will need to define a valid token on your bridge thing to have your things correctly initialized.

Setting the buildTriggerChannels parameter to false is for the main following advanced usages :

• you don't care about the trigger channels of this remote thing and you don't want the binding to create them locally,
• you want to define the trigger channels in your configuration file, and only the channels that you will finally need,
• you want to set a specific channel ID rather than using the channel ID created by the binding.

Thing Status

The status of any thing thing is a mapping of the remote thing status. A mapping is done only when the server bridge is ONLINE (meaning the local server is connected to the remote server). Please note that every remote status other than UNKNOWN, ONLINE and OFFLINE will then be considered as OFFLINE on the local server.

Channels

Channels are built dynamically and automatically by the binding.

On the server thing, a channel is created automatically for each item defined in the remote server. Only basic groups (with no state) from the remote server are ignored. The channel ID of the created channel corresponds to the name of the item on the remote server. For example, if your remote item is named MyDate, the channel UID of the channel created by the binding will be remoteopenhab:server:xxx:MyDate.

On the thing thing, you will not find all channels from your remote thing. Only trigger channels from your remote thing will be created. All state channels from your remote thing will be ignored (use the server thing to link a local item to a remote (item). if the buildTriggerChannels parameter is set to true, a channel is created automatically for each trigger channel defined in the remote thing. For example, if your remote thing provides a trigger channel with this UID astro:sun:local:night#event, the channel UID of the channel created by the binding will be remoteopenhab:thing:xxx:astro_sun_local_night_event.

Limitations

• The binding will not try to communicate with an openHAB v1 server.

Example

demo.things:

Bridge remoteopenhab:server:oh2 "OH2 server" [ host="192.168.0.100", port=8443, useHttps=true, trustedCertificate=true ] {
    Thing thing tv "TV living room" [ thingUID="lgwebos:WebOSTV:tv" ]
    Thing thing astroSun "Astro sun" [ thingUID="astro:sun:local", buildTriggerChannels=false ] {
        Channels:
            Type trigger : nightEvent "Night Event" [ channelUID="astro:sun:local:night#event" ]
    }
    Thing thing astroMoon "Astro moon" [ thingUID="astro:moon:local" ]
}

demo.items:

DateTime MyDate "Date [%1$tA %1$td %1$tR]" <calendar> { channel="remoteopenhab:server:oh2:MyDate" }

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)