openhab-addons/bundles/org.openhab.binding.remoteopenhab/README.md

# 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 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:

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