# 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      | Host name or IP address of the remote openHAB server.                                                        |
| useHttps              | no       | Use HTTPS for communication. Default: false.                                                                 |
| port                  | yes      | HTTP port for remote server. Default: 8080.                                                                  |
| trustedCertificate    | no       | Accept HTTPS without valid SSL certificate.                                                                  |
| restPath              | yes      | REST API subpath on remote server. Default: "/rest/"                                                         |
| token                 | no       | Authorization token for remote server REST API.                                                              |
| username              | no       | Username for basic authorization to remote server REST API.                                                  |
| password              | no       | Password for basic authorization to remote server REST API.                                                  |
| authenticateAnyway    | no       | Pass authentication over unsecured HTTP (not recommended). Default: false.                                   |
| accessibilityInterval | no       | Minutes between remote server accessibility checks. 0 to disable. Default: 3.                                |
| aliveInterval         | no       | Minutes to monitor event receipts. Server considered alive if event received. 0 to disable. Default: 5.      |
| restartIfNoActivity   | no       | Restart SSE connection if no events received in monitored interval. Useful for long outages. Default: 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:

```java
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:

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

### `demo.items` Example

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