# 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.
username	no	The username to use when the remote openHAB server is setup to require basic authorization to run its REST API.
password	no	The password to use when the remote openHAB server is setup to require basic authorization to run its REST API.
authenticateAnyway	no	Set it to true in case you want to pass authentication information even when the communicate with the remote openHAB server is not secured (only HTTP). This is of course not recommended especially if your connection is over the Internet. Default is false.
accessibilityInterval	no	Minutes between checking the remote server accessibility. 0 to disable the check. Default is 3.
aliveInterval	no	Number of last minutes to consider when monitoring the receipt of events from the remote server. If an event is received during this interval, the remote server is considered alive and its accessibility will not be verified. Use 0 to disable this feature. Default is 5.
restartIfNoActivity	no	Set it to true if you want to restart the connection (SSE) to the remote server when no events are received in the monitored interval. It is not necessary if the goal is to properly handle a short network outage (few seconds). This can be useful if you want to deal with a long network outage. Do not enable it if you remote server does not send events during the monitored interval under normal conditions, it will cause frequent restart of the connection and potential loss of events. Default is false.

Please note that even though the default configuration is based on insecure communication over HTTP, it is recommended to adjust the configuration to be based on secure communication over HTTPS. This is of course essential if your connection to the remote openHAB server is over the Internet.

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, in order for all of your things to be properly initialized, you will need to define on your bridge thing a valid API token in the parameter token and also define the parameter authenticateAnyway to true in case you are using an unsecured connection (HTTP). This API token can be created on your remote server using Main UI.

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` Example

Example of connection to a remote server in the local network:

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" ]
}

Example of connection to a remote server outside the local network through a myopenhab cloud instance:

Bridge remoteopenhab:server:oh3 "OH3 server" [ host="myopenhab.org", useHttps=true, port=443, username="myUsername", password="myPassword" ]

# `demo.items` Example

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)

← RegoHeatPump Renault →