# Lutron Binding

This binding integrates with [Lutron](https://www.lutron.com) lighting control and home automation systems.
It contains support for four different types of Lutron systems via different bridge things:

- RadioRA 2, HomeWorks QS, Caseta, RA2 Select, and other current systems that can be controlled via Lutron Integration Protocol (LIP) or LEAP
- The original RadioRA system, referred to here as RadioRA Classic
- Legacy HomeWorks RS232 Processors
- Grafik Eye 3x/4x systems with GRX-PRG or GRX-CI-PRG control interfaces

Each is described in a separate section below.

## Lutron RadioRA 3/ RadioRA 2/HomeWorks QS/RA2 Select/Caseta Binding

**Note:** While the Lutron Integration Protocol used by ipbridge in this binding should largely be compatible with other current Lutron systems, it has only been fully tested with RadioRA 2, HomeWorks QS, and Caseta with Smart Bridge Pro.
Homeworks QS support is still a work in progress, since not all features/devices are supported yet.
RA2 Select systems work with the binding, but full support for all devices still needs to be confirmed.
Caseta Smart Bridge (non-Pro model) support and support for Caseta occupancy sensors is available only through the experimental leapbridge Thing.
The binding has not been tested with Quantum, QS Standalone, myRoom Plus, or Athena systems.

## Supported Things

This binding currently supports the following Thing types:

- **ipbridge** - The Lutron main repeater/processor/hub
- **leapbridge** - Experimental bridge that uses LEAP protocol (Caseta, Radio RA3 & RA2 Select only)
- **dimmer** - Light dimmer
- **switch** - Switch or relay module
- **fan** - Fan controller
- **occupancysensor** - Occupancy/vacancy sensor
- **ogroup** - Occupancy group
- **keypad** - Lutron seeTouch or Hybrid seeTouch Keypad
- **ttkeypad** - Tabletop seeTouch Keypad
- **intlkeypad** - International seeTouch Keypad (HomeWorks QS only)
- **palladiomkeypad** - Palladiom Keypad (HomeWorks QS only)
- **pico** - Pico Keypad
- **grafikeyekeypad** - GRAFIK Eye QS Keypad (RadioRA 2/HomeWorks QS only)
- **virtualkeypad** - Repeater/processor integration buttons or Caseta Smart Bridge scene buttons
- **vcrx** - Visor control receiver module (VCRX)
- **qsio** - QS IO Interface (HomeWorks QS only)
- **wci** - QS Wallbox Closure Interface (WCI) (HomeWorks QS only)
- **cco** - Contact closure output module or VCRX CCO
- **shade** - Lutron shade, motorized drape, or motor controller
- **blind** - Lutron venetian blind or horizontal sheer blind [**Experimental**]
- **greenmode** - Green Mode subsystem
- **timeclock** - Scheduling subsystem
- **sysvar** - System state variable (HomeWorks QS only) [**Experimental**]

## Discovery

Full discovery is supported for RadioRA 2 and HomeWorks QS systems.
Both the main repeaters/processors themselves and the devices connected to them will be automatically discovered.
Discovered repeaters/processors will be accessed using the default integration credentials.
These can be changed in the bridge Thing configuration.
Discovered keypad devices should have their model parameters automatically set to the correct value.

Caseta Smart Bridge hubs, Smart Bridge Pro 2 hubs, and RA2 Select main repeaters should be discovered automatically via mDNS.
Devices attached to them need to be configured manually when using ipbridge.
The experimental leapbridge supports full automated discovery of these systems, but authentication information must be manually entered.

Other supported Lutron systems must be configured manually.

**Note:** Discovery selects ipbridge for HomeWorks QS, RadioRA 2, RA2 Select, and Caseta Smart Bridge Pro.
It select leapbridge for Caseta Smart Bridge and Radio RA 3, since only LEAP protocol is supported by these systems.

## Binding Configuration

This binding does not require any special configuration.

## Thing Configuration and Usage

Each Lutron Thing requires the integration ID of the corresponding item in the Lutron system.
The integration IDs can be retrieved from the integration report generated by the Lutron software.
If a Thing will not come online, but instead has the status "UNKNOWN: Awaiting initial response", it is likely that you have configured the wrong integration ID for it.

### Bridges

Two different bridges are now supported by the binding for current Lutron systems, ipbridge and leapbridge.
The LIP protocol is supported by ipbridge while the LEAP protocol is supported by leapbridge.
Current systems support one or both protocols as shown below.

| Bridge Device            | LIP | LEAP |
|--------------------------|-----|------|
| HomeWorks QS Processor   |  X  |      |
| RadioRA 2 Main Repeater  |  X  |      |
| RA2 Select Main Repeater |  X  |  X   |
| Caseta Smart Bridge Pro  |  X  |  X   |
| Caseta Smart Bridge      |     |  X   |
| RadioRA 3 Processor      |     |  X   |

If your system supports only one protocol, then the choice of bridge is easy.
If you have a system that supports both protocols, you must decide which you wish to use.

You should be aware of the following functional differences between the protocols:

- Using LIP on Caseta you can’t receive notifications of occupancy group status changes (occupied/unoccupied/unknown), but using LEAP you can.
- Both protocols provide notifications of keypad button presses and releases, so you can trigger rules on button events using either bridge.
On RadioRA 3 processors, LEAP also reports hold and multi-tap events, which fire the `LONG_PRESSED` and `DOUBLE_PRESSED` channel events.
- Caseta and RA2 Select device discovery is supported via LEAP, but not via LIP.
- The leapbridge is a bit more complicated to configure because LEAP uses an SSL connections and authenticates using certificates.
- LIP is a publicly documented protocol, while LEAP is not. This means that Lutron could make a change that breaks LEAP support at any time.

It is possible to run leapbridge and ipbridge at the same time, for the same bridge device, but each managed device (e.g. keypad or dimmer) should only be configured through _one_ bridge.
Remember that LEAP device IDs and LIP integration IDs are not necessarily equal!

#### ipbridge

This is the standard bridge which should be used with most Lutron systems.
It relies on Lutron Integration Protocol (LIP) over TCP/IP to communicate with the target device.
It can currently be used with a RadioRA 2 main repeater, a HomeWorks QS Processor, a Caseta Smart Bridge Pro, or a RA2 Select main repeater.

The ipbridge configuration requires the IP address of the bridge as well as the telnet username and password to log in to the bridge.
It is recommended that main repeaters/processors be configured with static IP addresses.
However if automatic discovery is used, the bridge Thing will work with DHCP-configured addresses.

The optional advanced parameter `heartbeat` can be used to set the interval between connection keepalive heartbeat messages, in minutes.
It defaults to 5.
Note that the handler will wait up to 30 seconds for a heartbeat response before attempting to reconnect.
The optional advanced parameter `reconnect` can be used to set the connection retry interval, in minutes.
It also defaults to 5.

The optional advanced parameter `delay` can be used to set a delay (in milliseconds) between transmission of integration commands to the bridge device.
This may be used for command send rate throttling.
It can be set to an integer value between 0 and 250 ms, and defaults to 0 (no delay).
It is recommended that this parameter be left at the default unless you experience problems with sent commands being dropped/ignored.
This has been reported in some rare cases when large numbers of commands were sent in short periods to Caseta hubs.
If you experience this problem, try setting a delay value of around 100 ms as a starting point.

The optional advanced parameter `discoveryFile` can be set to force the device discovery service to read the Lutron configuration XML from a local file rather than retrieving it via HTTP from the RadioRA 2 or HomeWorks QS bridge device.
This is useful in the case of some older Lutron software versions, where the discovery service may have problems retrieving the file from the bridge device.
Note that the user which openHAB runs under must have permission to read the file.

Thing configuration file example:

```java
Bridge lutron:ipbridge:radiora2 [ ipAddress="192.168.1.2", user="lutron", password="integration" ] {
    Thing ...
    Thing ...
}
```

#### leapbridge [**experimental**]

The leapbridge is an experimental bridge which allows the binding to work with the Caseta Smart Hub (non-Pro version) and the RadioRA 3 Processor.
It can also be used to provide additional features, such as support for occupancy groups and device discovery, when used with Caseta Smart Hub Pro or RA2 Select.
It uses the LEAP protocol over SSL, which is an undocumented protocol supported by some of Lutron's newer systems.
If you need this useful feature, you should use ipbridge instead.
You can use both ipbridge and leapbridge at the same time, but each device should only be configured through one bridge.
You should also be aware that LEAP and LIP integration IDs for the same device can be different.

For instructions on configuring authentication for leapbridge, see the [Leap Notes](doc/leapnotes.md) document.

The `ipAddress`, `keystore` and `keystorePassword` parameters must be set.
The optional `port` parameter defaults to 8081 and should not normally need to be changed.

The optional parameter `certValidate` defaults to true. It should be set to false only if validation of the hub's server certificate is failing, possibly because the hostname you are using for it does not match its internal hostname.
If this happens, the leapbridge status will be: "OFFLINE - COMMUNICATION_ERROR - Error opening SSL connection", and a message like the following may be logged:
```Error opening SSL connection: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target```.

The optional advanced parameter `heartbeat` can be used to set the interval between connection keepalive heartbeat messages, in minutes.
It defaults to 5.
Note that the handler will wait up to 30 seconds for a heartbeat response before attempting to reconnect.
The optional advanced parameter `reconnect` can be used to set the connection retry interval, in minutes.
It also defaults to 5.
The optional advanced parameter `delay` can be used to set a delay (in milliseconds) between transmission of LEAP commands to the bridge device.
It should not normally need to be changed.

Thing configuration file example:

```java
Bridge lutron:leapbridge:caseta [ ipAddress="192.168.1.3", keystore="/home/openhab/lutron.keystore", keystorePassword="secret" ] {
    Thing ...
    Thing ...
}
```

### Devices

#### Dimmers

Dimmers can optionally be configured to specify a default fade in and fade out time in seconds using the `fadeInTime` and `fadeOutTime` parameters.
These are used for ON and OFF commands, respectively, and default to 1 second if not set.
Commands using a specific percent value will use a default fade time of 0.25 seconds.

Dimmers also support the optional advanced parameters `onLevel` and `onToLast`.
The `onLevel` parameter specifies the level to which the dimmer will go when sent an ON command.
It defaults to 100.
The `onToLast` parameter is a boolean that defaults to false.
If set to "true", the dimmer will go to its last non-zero level when sent an ON command.
If the last non-zero level cannot be determined, the value of `onLevel` will be used instead.

A **dimmer** Thing has a single channel _lightlevel_ with type Dimmer and category DimmableLight.
The **dimmer** Thing was previously also used to control fan speed controllers, but now you should use the **fan** Thing instead.

Thing configuration file example:

```java
Thing dimmer livingroom [ integrationId=8, fadeInTime=0.5, fadeOutTime=5 ]
```

The **dimmer** Thing supports the Thing action `setLevel(Double level, Double fadeTime, Double delayTime)` for automation rules.

The parameters are:

- `level` The new light level to set (0-100)
- `fadeTime` The time in seconds over which the dimmer should fade to the new level
- `delayTime` The time in seconds to delay before starting to fade to the new level

The fadeTime and delayTime parameters are significant to 2 digits after the decimal point (i.e. to hundredths of a second), but some Lutron systems may round the time to the nearest 0.25 seconds when processing the command.
Times of 100 seconds or more will be rounded to the nearest integer value.

See below for an example rule using Thing actions.

#### Switches

Switches take no additional parameters besides `integrationId`.
A **switch** Thing has a single channel _switchstatus_ with type Switch and category Switch.

Thing configuration file example:

```java
Thing switch porch [ integrationId=8 ]
```

#### Fans

Fan speed controllers are interfaced with using the **fan** Thing.
It accepts no additional parameters besides `integrationId`.
A **fan** Thing has two channels, _fanspeed_ and _fanlevel_.

Thing configuration file example:

```java
Thing fan porchfan [ integrationId=12 ]
```

#### Occupancy Sensors

An **occupancysensor** Thing interfaces to Lutron Radio Powr Savr wireless occupancy/vacancy sensors on RadioRA 2 and HomeWorks QS systems.
On these systems, you should generally choose to interface to either an occupancy group or individual occupancy sensors for a given area.
For Caseta Smart Motion Sensors, you must use the **group** Thing instead.

It accepts no configuration parameters other than `integrationId`.

The binding creates one _occupancystatus_ channel, Item type Switch, category Motion.
It is read-only, and ignores all commands.
The channel state can be monitored for occupied (ON) or unoccupied (OFF) events coming from the sensor.
The sensors cannot be queried for their state, so initial channel state at startup will be undefined (NULL).

Thing configuration file example:

```java
Thing occupancysensor shopsensor [ integrationId=7 ]
```

#### Occupancy Groups

A **ogroup** Thing interfaces to an occupancy group, which shows occcupancy/vacancy status for an area or room with one or more occupancy sensors.
On RadioRA2 and HomeWorks QS systems, you should generally choose to interface to either an occupancy group or individual occupancy sensors for a given area.
On Caseta systems, you cannot interface to individual sensors and must use the _ogroup_ Thing.
The `integrationId` parameter must be set to the occupancy group ID.

The binding creates one read-only _groupstate_ channel, item type String, category Motion.
The value can be "OCCUPIED", "UNOCCUPIED", or "UNKNOWN".

Thing configuration file example:

```java
Thing ogroup lrgroup [ integrationId=7 ]
```

#### seeTouch and Hybrid seeTouch Keypads

seeTouch and Hybrid seeTouch keypads are interfaced with using the **keypad** Thing.
In addition to the usual `integrationId` parameter, it accepts a `model` parameter.
The `model` parameter should be set to the Lutron keypad model number.
This will cause the handler to create only the appropriate channels for that particular keypad model.
The default is "Generic", which will cause the handler to create all possible channels, some of which will likely not be appropriate for your model.

A trigger channel _button[nn]_ is created for each button, and a state channel _led[nn]_ with item type Switch and category Light is created for each button indicator LED.
Each button channel fires the `PRESSED` and `RELEASED` events as the physical button is pressed and released.
Buttons programmed for hold or double-tap in the Lutron software additionally fire `LONG_PRESSED` and `DOUBLE_PRESSED` events.
Because a hold-programmed button reports a hold instead of a release, a `RELEASED` event is fired immediately after `LONG_PRESSED` so that trigger profiles do not get stuck in the pressed state.
This lets you trigger rules directly on button events without needing an intermediate Item (see the example below).

If you prefer to drive an Item from a button, link the button channel to an Item using one of the built-in trigger [profiles](https://www.openhab.org/docs/configuration/items.html#profiles), for example `system:rawbutton-toggle-switch` to toggle a Switch on each press, or `system:rawbutton-on-off-switch` to follow the button's pressed/released state.

For the LED channels you can monitor ON and OFF state changes and send ON and OFF commands to drive the indicator LEDs.
Note, however, that version 11.6 or higher of the RadioRA 2 software may be required in order to drive keypad LED states, and then this may only be done on unbound buttons.

Button channels are trigger channels and do not accept commands.
To invoke keypad programming from openHAB where the Lutron system provides integration (phantom) buttons, use the **virtualkeypad** Thing; this requires assigning the programming to an integration button in the Lutron software.

Component numbering: For button and LED layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.104 (<https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf>).
If you are having problems determining which channels have been created for a given keypad model, select the appropriate keypad Thing under Settings/Things in the Administration UI and click on the Channels tab.
You can also run the command `things show <thingUID>` (e.g. `things show lutron:keypad:radiora2:entrykeypad`) from the openHAB CLI to list the channels.

Supported settings for `model` parameter: H1RLD, H2RLD, H3BSRL, H3S, H4S, H5BRL, H6BRL, HN1RLD, HN2RLD, HN3S, HN3BSRL, HN4S, HN5BRL, HN6BRL, W1RLD, W2RLD, W3BD, W3BRL, W3BSRL, W3S, W4S, W5BRL, W5BRLIR, W6BRL, W7B, Generic (default)

Thing configuration file example:

```java
Thing keypad entrykeypad [ integrationId=10, model="W7B" ]
```

Example rule triggered by a keypad button press:

```java
rule ExampleScene
when
  Channel "lutron:keypad:radiora2:entrykeypad:button4" triggered PRESSED
then
  Library1_Brightness.sendCommand(OFF)
end
```

#### Tabletop seeTouch Keypads

Tabletop seeTouch keypads use the **ttkeypad** Thing.
It accepts the same `integrationId` and `model` parameters and creates the same channel types as the **keypad** Thing.
See the **keypad** section above for a full discussion of configuration and use.

Component numbering: For button and LED layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.110 (<https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf>).
If you are having problems determining which channels have been created for a given keypad model, select the appropriate ttkeypad Thing under Settings/Things in the Administration UI and click on the Channels tab.
You can also run the command `things show <thingUID>` (e.g. `things show lutron:ttkeypad:radiora2:bedroomkeypad`) from the openHAB CLI to list the channels.

Supported settings for `model` parameter: T5RL, T10RL, T15RL, T5CRL, T10CRL, T15CRL, Generic (default)

Thing configuration file example:

```java
Thing ttkeypad bedroomkeypad [ integrationId=11, model="T10RL" ]
```

#### International seeTouch Keypads (HomeWorks QS)

International seeTouch keypads used in the HomeWorks QS system use the **intlkeypad** Thing.
It accepts the same `integrationId` and `model` parameters and creates the same button and LED channel types as the **keypad** Thing.
See the **keypad** section above for a full discussion of configuration and use.

To support this keypad's contact closure inputs, CCI channels named _cci1_ and _cci2_ are created with item type Contact and category Switch.
They are marked as Advanced, so you will need to check "Show advanced" in order to see them listed in the Administration UI.
They present OPEN/CLOSED states but do not accept commands since Contact items are read-only in openHAB.

Component numbering: For button and LED layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.107 (<https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf>).
If you are having problems determining which channels have been created for a given keypad model, select the appropriate intlkeypad Thing under Settings/Things in the Administration UI and click on the Channels tab.
You can also run the command `things show <thingUID>` (e.g. `things show lutron:intlkeypad:hwprocessor:kitchenkeypad`) from the openHAB CLI to list the channels.

Supported settings for `model` parameter: 2B, 3B, 4B, 5BRL, 6BRL, 7BRL, 8BRL, 10BRL / Generic (default)

Thing configuration file example:

```java
Thing intlkeypad kitchenkeypad [ integrationId=15, model="10BRL" ]
```

#### Palladiom Keypads (HomeWorks QS)

Palladiom keypads used in the HomeWorks QS system use the **palladiomkeypad** Thing.
It accepts the same `integrationId` and `model` parameters and creates the same button and LED channel types as the **keypad** Thing.
See the **keypad** section above for a full discussion of configuration and use.

Component numbering: For button and LED layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.95 (<https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf>).
If you are having problems determining which channels have been created for a given keypad model, select the appropriate palladiomkeypad Thing under Settings/Things in the Administration UI and click on the Channels tab.
You can also run the command `things show <thingUID>` (e.g. `things show lutron:palladiomkeypad:hwprocessor:kitchenkeypad`) from the openHAB CLI to list the channels.

Supported settings for `model` parameter: 2W, 3W, 4W, RW, 22W, 24W, 42W, 44W, 2RW, 4RW, RRW

Thing configuration file example:

```java
Thing palladiomkeypad kitchenkeypad [ integrationId=16, model="4W" ]
```

#### Pico Keypads

Pico keypads use the **pico** Thing.
It accepts the same `integrationId` and `model` parameters and creates the same channel types as the **keypad** and **ttkeypad** things.
The only difference is that no LED channels will be created, since Pico keypads have no indicator LEDs.
Note that Pico keypads only report `PRESSED` and `RELEASED` events; they do not support hold or double-tap reporting.
See the discussion above for a full discussion of configuration and use.

Component numbering: For button layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.113 (<https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf>).
If you are having problems determining which channels have been created for a given keypad model, select the appropriate pico Thing under Settings/Things in the Administration UI and click on the Channels tab.
You can also run the command `things show <thingUID>` (e.g. `things show lutron:pico:radiora2:hallpico`) from the openHAB CLI to list the channels.

Supported settings for `model` parameter: 2B, 2BRL, 3B, 3BRL, 4B, Generic (default)

Thing configuration file example:

```java
Thing pico hallpico [ integrationId=12, model="3BRL" ]
```

#### GRAFIK Eye QS Keypads (in RadioRA 2/HomeWorks QS systems)

GRAFIK Eye devices can contain up to 6 lighting dimmers, a scene controller, a time clock, and a front panel with a column of 5 programmable scene buttons and 0 to 3 columns of programmable shade or lighting control buttons.
They can be used as peripheral devices in a RadioRA 2 or HomeWorks QS system, or can be used as stand-alone controllers that themselves can control other Lutron devices.
The **grafikeyekeypad** Thing is used to interface to the GRAFIK Eye QS front panel keypad when it is used in a RadioRA 2 or HomeWorks QS system.
In this configuration, the integrated dimmers will appear to openHAB as separate output devices.

If your GRAFIK Eye is being used as a stand-alone device and is not integrated in to a RadioRA 2 or HomeWorks QS system, then _this is not the Thing you are looking for_.
You should instead be using the **grafikeye** Thing (see below).

The **grafikeyekeypad** Thing accepts the same `integrationId` and `model` parameters and creates the same button, LED, and CCI, channel types as the other keypad things (see above).
The model parameter should be set to indicate whether there are zero, one, two, or three columns of buttons on the left side of the panel.
Note that this count does not include the column of 5 scene buttons always found on the right side of the panel.

To support the GRAFIK Eye's contact closure input, a CCI channel named _cci1_ will be created with item type Contact and category Switch.
It is marked as Advanced, so you will need to check "Show advanced" in order to see it listed in the Administration UI.
It presents OPEN/CLOSED states but does not accept commands since Contact items are read-only in openHAB.

Component numbering: The buttons and LEDs on the GRAFIK Eye are numbered top to bottom, starting with the 5 scene buttons in a column on the right side of the panel, and then proceeding with the columns of buttons (if any) on the left side of the panel, working left to right.
If you are having problems determining which channels have been created for a given model setting, select the appropriate grafikeyekeypad Thing under Settings/Things in the Administration UI and click on the Channels tab.
You can also run the command `things show <thingUID>` (e.g. `things show lutron:grafikeyekeypad:radiora2:theaterkeypad`) from the openHAB CLI to list the channels.

Supported settings for `model` parameter: 0COL, 1COL, 2COL, 3COL (default)

Thing configuration file example:

```java
Thing lutron:grafikeyekeypad:theaterkeypad (lutron:ipbridge:radiora2) [ integrationId=12, model="3COL" ]
```

#### Virtual Keypads

The **virtualkeypad** Thing is used to interface to the virtual buttons on the RadioRA 2 main repeater or HomeWorks processor.
These are sometimes referred to in the Lutron documentation as phantom buttons or integration buttons, and are used only for integration.
There are 100 of these virtual buttons, and 100 corresponding virtual indicator LEDs.

The **virtualkeypad** Thing can also be used to interface to the Smart Bridge scene buttons on Caseta systems.
This allows you to trigger your defined scenes via the virtual keypad buttons.
For this to work, the optional `model` parameter must be set to `Caseta`.
When used with Caseta, no virtual indicator LED channels are created.

Unlike the physical keypad Things, the button channels of the **virtualkeypad** Thing are Switch state channels rather than trigger channels, because their primary use is sending ON/OFF commands from openHAB to activate the programming assigned to the integration buttons.

The `autorelease` parameter is a boolean that defaults to true.
When an ON command is sent to a button channel, the handler sends a "press" action to the device, immediately followed by a "release" action if `autorelease` is set, and the channel state then transitions back to OFF.
This prevents the button channel from becoming stuck in the ON state, since some integration applications only generate a "pressed" event and never send a "release".
If you wish to control press and release separately, set `autorelease` to false and send an ON command for press and an OFF command for release.

The button and LED channels created have the Advanced flag set.
This means, among other things, that you will need to check "Show advanced" in order to see them listed in the Administration UI.

In most cases the integrationId parameter should be set to 1.

Supported settings for `model` parameter: Caseta, Other (default)

Thing configuration file example:

```java
Thing virtualkeypad repeaterbuttons [ integrationId=1, autorelease=true ]
```

#### VCRX Modules

The Lutron VCRX appears to openHAB as multiple devices.
The 6 buttons (which can be activated remotely by HomeLink remote controls), 6 corresponding LEDs, and 4 contact closure inputs (CCIs) are handled by the **vcrx** Thing, which behaves like a keypad.
The contact closure outputs (CCOs) have their own integration IDs and are handled by the **cco** Thing (see below).

The only supported option is `integrationId`.
Supplying a model is not required, as there is only one model.
The 6 buttons are exposed as trigger channels, the same as the **keypad** Thing (see above).

To support the contact closure inputs, CCI channels named _cci[n]_ are created with item type Contact and category Switch.
The VCRX security (Full/Flash) input controls both the cci1 and cci2 channels, while input connections 1 and 2 map to the cci3 and cci4 channels respectively.
The cci channels are marked as Advanced, so you will need to check "Show advanced" in order to see them listed in the Administration UI.
They present OPEN/CLOSED states but do not accept commands since Contact items are read-only in openHAB.

Thing configuration file example:

```java
Thing vcrx vcrx1 [ integrationId=13 ]
```

#### QS IO Interface (HomeWorks QS)

The Lutron QS IO Interface (QSE-IO) appears to openHAB as multiple devices.
The 5 contact closure inputs (CCIs) are handled by the **qsio** Thing.
The 5 contact closure outputs (CCOs) are handled by the **cco** Thing (see below).
The only configuration option is `integrationId`

To support the contact closure inputs, CCI channels named _cci[n]_ are created with item type Contact and category Switch.
They are marked as Advanced, so you will need to check "Show advanced" in order to see them listed in the Administration UI.
They present OPEN/CLOSED states but do not accept commands as Contact items are read-only in openHAB.

Some functionality may depend on QSE-IO DIP switch settings. See the Lutron documentation for more information.

Thing configuration file example:

```java
Thing qsio sensorinputs [ integrationId=42 ]
```

#### QS Wallbox Closure Interface (WCI) (HomeWorks QS only)

The Lutron Wallbox Closure Interface (QSE-CI-WCI) is used to interface to contact closure keypads.
It is handled by the **wci** Thing.
The 8 button inputs appear to the HomeWorks system as normal keypad buttons.
There are also 8 LEDs, although they are normally hidden and thus mainly useful for setup and diagnostics.

The only supported option is `integrationId`.
Supplying a model is not required, as there is only one model.
The 8 button inputs are exposed as trigger channels, the same as the **keypad** Thing (see above).

See the Lutron documentation for more information.

Thing configuration file example:

```java
Thing wci specialkeypad [ integrationId=48 ]
```

#### CCO Modules

Contact closure output (**cco**) things accept `outputType` and `pulseLength` parameters.
The `outputType` parameter is a string that should be set to "Pulsed" for pulsed CCOs or "Maintained" for non-pulsed CCOs.
The default is "Pulsed", since this is generally the safer wrong setting.
The `pulseLength` parameter sets the pulse length in seconds for a pulsed output.
It can range from 0.25 to 99.0 seconds and defaults to 0.5. It is ignored if `outputType="Maintained"`.
Be aware that the Lutron controller may round the pulse length down to the nearest 0.25 seconds.

**Note:** The **ccopulsed** and **ccomaintained** things are now deprecated.
You should use the **cco** Thing with the appropriate `outputType` setting instead.

Each **cco** Thing creates one switch channel called _switchstatus_.
For pulsed CCOs, sending an ON command will close the output for the configured pulse time.
Sending an OFF command does nothing.
Because of limitations in RadioRA 2, you cannot monitor the state of a pulsed CCO.
Therefore, the channel state will only transition OFF->ON->OFF when you send an ON command.

For maintained CCOs, sending ON and OFF commands works as expected, and the channel state updates as expected when either openHAB commands or external events change the CCO device state.

Thing configuration file example:

```java
Thing cco garage [ integrationId=5, outputType="Pulsed", pulseLength=0.5 ]
Thing cco relay1 [ integrationId=7, outputType="Maintained"]
```

#### Shades

Each Lutron shade, motorized drape, or QS motor controller output (LQSE-4M-D) is controlled by a **shade** Thing.
The only configuration parameter it accepts is `integrationId`.

A single channel _shadelevel_ with item type Rollershutter and category Rollershutter will be created for each **shade** Thing.
It accepts Percent, Up, Down, Stop and Refresh commands.
Sending a Percent command will cause the shade to immediately move so as to be open the specified percentage.
You can also read the current shade level from the channel.
It is specified as a percentage, where 0% = closed and 100% = fully open. Movement delays are not currently supported.
The shade handler should be compatible with all Lutron devices which appear to the system as shades, including roller shades, honeycomb shades, pleated shades, roman shades, tension roller shades, drapes, and Kirbe vertical drapes.

Motor controller outputs on a LQSE-4M-D (HomeWorks QS only) behave similarly to a shade.
The only difference is that percentages other than 0% and 100% will be ignored, since arbitrary positioning is not supported by the hardware.
The value of _shadelevel_ for a motor will likewise always be either 0% or 100%, depending on whether the last command sent was Up or Down.

**Note:** While a shade is moving to a specific level because of a Percent command, the system will report the target level for the shade rather than the actual current level.
While a shade is moving because of an Up or Down command, it will report the previous level until it stops moving.

Thing configuration file example:

```java
Thing shade libraryshade [ integrationId=33]
```

#### Blinds [**Experimental**]

Each Lutron Sivoia QS Venetian Blind or Horizontal Sheer Blind is controlled by a **blind** Thing.
Besides `integrationId`, it requires that the parameter `type` be set to either "Venetian" for venetian blinds or "Sheer" for horizontal sheer blinds.
There is no default.
If discovery is used, the `type` parameter will set automatically when the **blind** Thing is created.

Two channels, _blindliftlevel_ and _blindtiltlevel_, with item type Rollershutter and category Rollershutter will be created for each **blind** Thing.
They control the up/down motion and the slat tilt motions of the blinds, respectively.
Each channel accepts Percent, Up, Down, Stop and Refresh commands.
Sending a Percent command will cause the blind to immediately move so as to be open the specified percentage.
You can also read the current setting from each channel.
It is specified as a percentage, where 0% = closed and 100% = fully open. Movement delays are not currently supported.

**Note:** While a blind is moving to a specific level because of a Percent command, the Lutron system will report the target position for the blind rather than the actual current position.
While a blind is moving because of an Up or Down command, it will report the previous level until it stops moving.

**Note:** Support for Sivoia QS blinds is new and has been through very limited testing.
Please comment on your use of it in the openHAB community forum.

Thing configuration file example:

```java
Thing blind officeblinds [ integrationId=76, type="Venetian"]
```

#### Green Mode

Radio RA2 and HomeWorks QS systems have a "Green Mode" or "Green Button" feature which allows the system to be placed in to one or more user-defined power saving modes called "steps".
Each step can take actions such as trimming down the 100% level on selected lighting dimmers by a specified percentage, shutting off certain loads, modifying thermostat settings, etc.
Typically step 1 is "Off" or "Normal", and step 2 is "Green Mode", however other steps may be defined by the installer as desired.

The **greenmode** Thing is used to interface to the green mode subsystem.
It requires that the `integrationId` parameter be set to the ID of the green mode subsystem.
This should generally be 22.
It creates a single channel _step_ that can be used to set or query the active green mode step number.

Unlike other Lutron system state settings, the binding is not automatically notified by the bridge device of changes to the current green mode step.
This may be due to a bug in the Lutron firmware.
The handler can be set to poll for the active green mode step so that the binding will know if it has been changed by another station.
The optional `pollInterval` configuration parameter controls how often the handler polls.
It can be set to anywhere between 0 and 240 minutes, and defaults to 15 minutes.
A setting of 0 will disabled polling.
You can also initiate a poll at any time by sending a refresh command (RefreshType.REFRESH) to the step channel.
Note that it should usually be unnecessary for the poll interval to be set to less than 5-10 minutes, since the green mode step typically changes rather infrequently and takes effect gradually.

Thing configuration file example:

```java
Thing greenmode greenmode [ integrationId=22 ]
```

#### Timeclock

RadioRA 2 and Homeworks QS have timeclock subsystems that provide scheduled execution of tasks at set times, randomized times or at arbitrary offsets from local sunrise/sunset.
The tasks executed depend on the currently selected timeclock mode (e.g. Normal, Away, Suspend) and the modes themselves are user-definable (RadioRA 2 only).
In addition, tasks can be individually executed, and enabled or disabled for scheduled execution.

The **timeclock** Thing provides an interface to timeclock functions.
It allows you to get and set the current timeclock mode, get the current day's sunrise and sunset times, execute a specific task, be notified when a task executes, and enable or disable tasks.
The `integrationId` parameter must be set to the ID of the timeclock subsystem.

It creates the following six channels:

- _clockmode_ - Gets or sets the current timeclock mode.
- _sunrise_ - The timeclock's local sunrise time for the current day. Read only. You must send a refresh command (RefreshType.REFRESH) to query the system for the current day's sunrise time, as it is not automatically updated.
- _sunset_ - The timeclock's local sunset time for the current day. Read only. You must send a refresh command to query the system for the current day's sunset time, as it is not automatically updated.
- _execevent_ - Updates with the index number of each executing event. Send an event's index number to start execution of it.
- _enableevent_ - Updates with an event's index number when it is enabled. Send an event's index number to enable it.
- _disableevent_ - Updates with an event's index number when it is disabled. Send an event's index number to disable it.

All channels except _clockmode_ are marked as advanced.

Thing configuration file example:

```java
Thing timeclock timeclock [ integrationId=23 ]
```

Example rule to refresh sunrise/sunset channels daily and at restart:

```java
import org.openhab.core.types.RefreshType

rule "Lutron sunrise/sunset daily refresh"

when
  // Trigger at time 00:05:00 every day
  Time cron "0 5 0 * * ?" or
  Thing "lutron:timeclock:70acb5a7:23" changed to ONLINE
then
  Timeclock_Sunrise.sendCommand(RefreshType.REFRESH)
  Timeclock_Sunset.sendCommand(RefreshType.REFRESH)
end
```

#### System State Variables (HomeWorks QS only) [**Experimental**]

HomeWorks QS systems allow for conditional programming logic based on state variables.
The **sysvar** Thing allows state variable values to be read and set from openHAB.
This makes sophisticated integration schemes possible.
Each **sysvar** Thing represents one system state variable.
It has a single channel _varstate_ with type Number and category Number.
Automatic discovery of state variables is not yet supported.
They must be manually configured.

Thing configuration file example:

```java
Thing sysvar qsstate [ integrationId=80 ]
```

## Channels

The following is a summary of channels for all RadioRA 2 binding things:

| Thing               | Channel           | Item Type     | Description                                  |
|---------------------|-------------------|---------------|--------------------------------------------- |
| dimmer              | lightlevel        | Dimmer        | Increase/decrease the light level            |
| switch              | switchstatus      | Switch        | On/off status of the switch                  |
| fan                 | fanspeed          | String        | Set/get fan speed using string options       |
| fan                 | fanlevel          | Dimmer        | Set/get fan speed using a dimmer channel     |
| occupancysensor     | occupancystatus   | Switch        | Occupancy sensor status                      |
| ogroup              | groupstate        | String        | Occupancy group status                       |
| cco                 | switchstatus      | Switch        | On/off status of the CCO                     |
| keypads (physical)  | button*           | Trigger       | Keypad button events (PRESSED/RELEASED/LONG_PRESSED/DOUBLE_PRESSED) |
| virtualkeypad       | button*           | Switch        | Virtual keypad button                        |
| keypads(except pico)| led*              | Switch        | LED indicator for the associated button      |
| vcrx                | cci*              | Contact       | Contact closure input on/off status          |
| shade               | shadelevel        | Rollershutter | Level of the shade (100% = full open)        |
| blind               | blindliftlevel    | Rollershutter | Level of the blind (100% = full open)        |
| blind               | blindtiltlevel    | Rollershutter | Tilt of the blind slats                      |
| greenmode           | step              | Number        | Get/set active green mode step number        |
| timeclock           | clockmode         | Number        | Get/set active clock mode index number       |
| timeclock           | sunrise           | DateTime      | Get the timeclock's sunrise time             |
| timeclock           | sunset            | DateTime      | Get the timeclock's sunset time              |
| timeclock           | execevent         | Number        | Execute event or monitor events executed     |
| timeclock           | enableevent       | Number        | Enable event or monitor events enabled       |
| timeclock           | disableevent      | Number        | Disable event or monitor events disabled     |
| sysvar              | varstate          | Number        | Get/set system state variable value          |

The channels available on each keypad device (i.e. keypad, ttkeypad, intlkeypad, grafikeyekeypad, pico, vcrx, and virtualkeypad) will vary with keypad type and model.
Appropriate channels will be created automatically by the keypad, ttkeypad, intlkeypad, grafikeyekeypad, and pico Thing handlers based on the setting of the `model` parameter for those Thing types.

### Commands supported by channels

| Thing     | Channel       | Native Type  | Accepts                                               |
|-----------|---------------|--------------|-------------------------------------------------------|
|dimmer     |lightlevel     |PercentType   |OnOffType, PercentType (rounded/truncated to integer)  |
|switch     |switchstatus   |OnOffType     |OnOffType                                              |
|fan        |fanspeed       |StringType    |"OFF","LOW","MEDIUM","MEDIUMHIGH","HIGH"               |
|fan        |fanlevel       |PercentType   |OnOffType, PercentType                                 |
|occ. sensor|occupancystatus|OnOffType     |(_readonly_)                                           |
|ogroup     |groupstate     |StringType    |"OCCUPIED","UNOCCUPIED","UNKNOWN" (_readonly_)         |
|cco        |switchstatus   |OnOffType     |OnOffType, RefreshType                                 |
|keypads (physical)|button* |n/a           |(_none - trigger channels do not accept commands_)     |
|virtualkeypad|button*      |OnOffType     |OnOffType                                              |
|keypads    |led*           |OnOffType     |OnOffType, RefreshType                                 |
|           |cci*           |OpenClosedType|(_readonly_)                                           |
|shade      |shadelevel     |PercentType   |PercentType, UpDownType, StopMoveType.STOP, RefreshType|
|blind      |blindliftlevel |PercentType   |PercentType, UpDownType, StopMoveType.STOP, RefreshType|
|           |blindtiltlevel |PercentType   |PercentType, UpDownType, StopMoveType.STOP, RefreshType|
|greenmode  |step           |DecimalType   |DecimalType, OnOffType (ON=2,OFF=1), RefreshType       |
|timeclock  |clockmode      |DecimalType   |DecimalType, RefreshType                               |
|           |sunrise        |DateTimeType  |RefreshType (_readonly_)                               |
|           |sunset         |DateTimeType  |RefreshType (_readonly_)                               |
|           |execevent      |DecimalType   |DecimalType                                            |
|           |enableevent    |DecimalType   |DecimalType                                            |
|           |disableevent   |DecimalType   |DecimalType                                            |
|sysvar     |varstate       |DecimalType   |DecimalType (rounded/truncated to integer)             |

Most channels receive immediate notifications of device state changes from the Lutron control system.
The only exceptions are **greenmode** _step_, which is periodically polled and accepts REFRESH commands to initiate immediate polling, and **timeclock** _sunrise_ and _sunset_, which must be polled daily using REFRESH commands to retrieve current values.
Many other channels accept REFRESH commands to initiate a poll, but sending one should not normally be necessary.

## RadioRA 2/HomeWorks QS Configuration File Examples

demo.things:

```java
Bridge lutron:ipbridge:radiora2 [ ipAddress="192.168.1.123", user="lutron", password="integration" ] {
        Thing dimmer lrtable "Table Lamp" @ "Living Room" [ integrationId=45, fadeInTime=0.5, fadeOutTime=5 ]
        Thing dimmer lrtorch "Torch Lamp" @ "Living Room" [ integrationId=44, fadeInTime=0.5, fadeOutTime=5 ]
        Thing dimmer lrspot [ integrationId=38, fadeInTime=0.5, fadeOutTime=5 ]
        Thing switch path [ integrationId=61 ]
        Thing keypad entrykeypad [ integrationId=64, model="W7B" ]
        Thing ttkeypad bedroomkeypad [ integrationId=28, model="T15RL" ]
        Thing pico librarypico [ integrationId=71, model="3BRL" ]
        Thing vcrx vcrx1 [ integrationId=34 ]
        Thing cco garage1 [ integrationId=75, outputType="Pulsed", pulseLength=0.5 ]
        Thing shade libraryshade1 [ integrationId=66]
        Thing greenmode greenmode [ integrationId=22 ]
        Thing timeclock timeclock [ integrationId=23 ]
        Thing occupancysensor laundryocc [ integrationId=62 ]
}
```

demo.items:

```java
Dimmer   LivingRm_TableLamp  "Table Lamp"      { channel="lutron:dimmer:radiora2:lrtable:lightlevel" }
Switch   FrontYard_PathLight "Path Light"      { channel="lutron:switch:radiora2:path:switchstatus" }
Switch   LaundryRm_Sensor    "Occ Sensor"      { channel="lutron:occupancysensor:radiora2:laundryocc:occupancystatus" }
Switch   Entryway_Keypad_B1  "Keypad Button 1" { channel="lutron:keypad:radiora2:entrykeypad:button1" [profile="system:rawbutton-toggle-switch"] }
Switch   Entryway_Keypad_L1  "Keypad LED 1"    { channel="lutron:keypad:radiora2:entrykeypad:led1" }
Contact  Vcrx1_CCI1          "Input 1"         { channel="lutron:vcrx:radiora2:vcrx1:cci1" }
Switch   Garage_CCO1         "Garage Door"     { channel="lutron:cco:radiora2:garage1:switchstatus" }
DateTime Timeclock_Sunrise   "Sunrise"         { channel="lutron:timeclock:radiora2:timeclock:sunrise" }
DateTime Timeclock_Sunset    "Sunset"          { channel="lutron:timeclock:radiora2:timeclock:sunset" }
Number   Timeclock_Clockmode "Clock Mode"      { channel="lutron:timeclock:radiora2:timeclock:clockmode" }
Number   Greenmode_Step      "Green Step"      { channel="lutron:greenmode:radiora2:greenmode:step" }
Rollershutter Lib_Shade1     "Shade 1"         { channel="lutron:shade:radiora2:libraryshade1:shadelevel" }

```

dimmerAction.rules:

```java
rule "Test dimmer action"
when
    Item TestSwitch received command ON
then
    val actions = getActions("lutron","lutron:dimmer:radiora2:lrtable")
    actions.setLevel(100, 5.5, 0)
end
```

## Lutron RadioRA (Classic) Binding

This binding integrates with the legacy Lutron RadioRA (Classic) lighting system.

This binding depends on RS232 communication.
It has only been tested using the Chronos System Bridge and Timeclock (RA-SBT-CHR) module, but Lutron's RA-RS232 or RB-RS232 module should work as well.

Support has been added for bridged RadioRA systems.
A system is considered “bridged” when a Chronos System Bridge and Timeclock is used to integrate two RadioRA Systems in a single residence.
In a bridged system, the `system` parameter of each configured ra-dimmer, ra-switch, or ra-phantomButton Thing should be set to indicate which RadioRA system it is a part of (i.e. 1 or 2).
In a non-bridged system, these parameters should be left at their default of 0.

### RadioRA Supported Things

This binding currently supports the following Thing types:

| Thing            | Type ID | Description                                          |
|------------------|---------|------------------------------------------------------|
| ra-rs232         | Bridge  | RadioRA device that supports RS232 communication     |
| ra-dimmer        | Thing   | Dimmer control                                       |
| ra-switch        | Thing   | Switch control                                       |
| ra-phantomButton | Thing   | Phantom Button to control multiple controls (Scenes) |

### RadioRA Thing Configuration Parameters

| Thing            | Parameter    | Description                                                            |
|------------------|--------------|------------------------------------------------------------------------|
| ra-rs232         | portName     | The serial port to use to communicate with Chronos or RS232 module     |
|                  | baud         | (Optional) Baud Rate (defaults to 9600)                                |
| ra-dimmer        | zoneNumber   | Assigned Zone Number within the Lutron RadioRA system                  |
|                  | system       | (Optional) System number (1 or 2) in a bridged system. Default=0 (n/a) |
|                  | fadeOutSec   | (Optional) Time in seconds dimmer should take when lowering the level  |
|                  | fadeInSec    | (Optional) Time in seconds dimmer should take when lowering the level  |
| ra-switch        | zoneNumber   | Assigned Zone Number within the Lutron RadioRA system                  |
|                  | system       | (Optional) System number (1 or 2) in a bridged system. Default=0 (n/a) |
| ra-phantomButton | buttonNumber | Phantom Button Number within the Lutron RadioRA system                 |
|                  | system       | (Optional) System number (1 or 2) in a bridged system. Default=0 (n/a) |

### RadioRA Channels

The following channels are supported:

| Thing Type                 | Channel ID   | Item Type | Description                        |
|----------------------------|--------------|-----------|------------------------------------|
| ra-dimmer                  | lightlevel   | Dimmer    | Increase/Decrease dimmer intensity |
| ra-switch/ra-phantomButton | switchstatus | Switch    | On/Off state of switch             |

### RadioRA Example

lutronradiora.things

```java
Bridge lutronradiora:ra-rs232:chronos1 [portName="/dev/ttys002"] {
    Thing ra-dimmer dimmer1 [ zoneNumber=1 ]
    Thing ra-dimmer dimmer2 [ zoneNumber=2 ]
    Thing ra-switch switch1 [ zoneNumber=3 ]
    Thing ra-switch switch2 [ zoneNumber=4 ]
    Thing ra-phantomButton1 phantomButton1 [ buttonNumber=1 ]
}
```

lutronradiora.items

```java
Dimmer Dimmer_Kitchen "Kitchen Lights" { channel="lutronradiora:dimmer:chronos1:dimmer1:lightlevel" }
Dimmer Dimmer_FamilyRoom "Family Room Lights" { channel="lutronradiora:dimmer:chronos1:dimmer2:lightlevel" }
Switch Switch_Patio "Patio Light" { channel="lutronradiora:dimmer:chronos1:switch1:switchstatus" }
Switch Switch_FrontDoor "Front Door Lights" { channel="lutronradiora:switch:chronos1:switch2:switchstatus" }
Switch Phantom_Movie "Movie Scene" { channel="lutronradiora:phantomButton:chronos1:phantomButton1:switchstatus" }
```

## Legacy HomeWorks RS232 (Serial) Processors

The binding supports legacy HomeWorks processors that interface with a Serial RS232 connection.
To connect to such a system, you would need to use a RS232 -> USB adapter (assuming you don't have a serial port).

Please see [HomeWorks RS232 Protocol Guide](https://www.lutron.com/TechnicalDocumentLibrary/HWI%20RS232%20Protocol.pdf) for information on the protocol.

### HomeWorks RS232 Supported Things

- HomeWorks RS232-connected Processor Units
- Dimmers

Supported in future updates:

- Keypads
- Keypad LEDs

### HomeWorks RS232 Discovery

This binding supports active and passive discovery.
It will detect dimmers as they are manually raised or lowered, or can be made to scan for configured dimmer modules.

### HomeWorks RS232 Thing Configuration

The bridge requires the port location (e.g., /dev/ttyUSB1 or COM1) and the baud rate.  The default baud rate for HomeWorks processors is set to 9600.

```java
lutron:hwserialbridge:home [serialPort="/dev/ttyUSB1", baudRate="9600]
```

Dimmers have one required parameter ``address`` that specifies the device address (e.g., [01:01:03:02:04]) and two optional parameters: ``fadeTime`` which sets the time it takes to set the light level when changed, and ``defaultLevel`` which sets the level to use for the dimmer when turning it on (with a switch rather than a slider).

```java
lutron:hwdimmer:dimmer1 [address="[01:01:03:02:04]", fadeTime="1", defaultLevel="75"]
```

### HomeWorks RS232 Channels

The following channels are supported:

| Thing Type      | Channel Type ID   | Item Type    | Description                                  |
|-----------------|-------------------|--------------|--------------------------------------------- |
| dimmer          | lightlevel        | Dimmer       | Increase/decrease the light level            |

## Lutron Grafik Eye 3x/4x binding via GRX-PRG or GRX-CI-PRG

This lutron binding will also work with Grafik Eye 3x/4x systems in conjuction with the GRX-PRG or GRX-CI-PRG interfaces.
Please see [RS232ProtocolCommandSet](https://www.lutron.com/TechnicalDocumentLibrary/RS232ProtocolCommandSet.040196d.pdf) for more information.

### Grafik Eye Supported Things

1-8 Grafik Eye 3x/4x System(s) through the interface

### Grafik Eye Discovery

This binding does not support discovery of the GRX-PRG or GRX-CI-PRG.
You will need to specify them directly.

### Grafik Eye Thing Configuration

The bridge requires the IP address/Host name of the bridge.
Optionally, you may specify the username (defaults to 'nwk') and retryPolling (in seconds) to retry connections if the connection fails (defaults to 10 seconds).
This bridge does support two way communication with the Grafik Eye units (if a scene is selected or a zone changed on the unit or via a keypad, that information is immediately available in openHAB).

```java
lutron:prgbridge:home [ ipAddress="192.168.1.51", user="nwk", retryPolling=10 ]
```

The Grafik Eye Thing requires the control unit address (1-8).
Optionally you may specify the default fade time (when raising/lowering zones or setting zone intensities) and polling time (in seconds) to refresh the state from the Grafik Eye (defaults to 30 seconds).
If any of the zones control a QED shade (via the SG/SO-SVCN/SVCI keypad), those zones
should be listed (comma separated list) in the shadeZones.

```java
lutron:grafikeye:home (lutron:prgbridge:home) [ controlUnit=1, fade=10, polling=30, shadeZones="2,3,4" ]
```

### Grafik Eye Channels

#### Grafik Eye Bridge channels

| Channel Type ID | Readonly | Item Type | Description                                                   |
|-----------------|----------|-----------|---------------------------------------------------------------|
| zonelowerstop   | No       | Switch    | Stops zone lowering on all control units                      |
| zoneraisestop   | No       | Switch    | Stops zone raising on all control units                       |
| timeclock       | No       | DateTime  | Current time on the PRG                                       |
| schedule        | No       | Number    | Current Schedule (0=Disabled, 1=Weekday, 2=Weekend)           |
| sunrise         | Yes      | DateTime  | Time of Sunrise                                               |
| sunset          | Yes      | DateTime  | Time of Sunset                                                |
| ssstart         | No       | Switch    | Starts the Super Sequence                                     |
| sspause         | No       | Switch    | Pauses the Super Sequence                                     |
| ssresume        | No       | Switch    | Resumes the Super Sequence                                    |
| ssstatus        | Yes      | String    | Status of the Super Sequence (R=Running, S=Stopped)           |
| ssnextstep      | Yes      | Number    | Next sequence number in the Super Sequence                    |
| ssnextminute    | Yes      | Number    | How many minutes until the next step in the Super Sequence    |
| ssnextsecond    | Yes      | Number    | How many seconds until the next step in the Super Sequence    |
| buttonpress     | Yes      | String    | Last keypad button pressed (see Appendix A) in protocol guide |

#### Grafik Eye Thing Channels

| Channel Type ID   | Readonly | Item Type     | Description                                                    |
|-------------------|----------|---------------|--------------------------------------------------------------- |
| scene             | No       | Number        | The current scene                                              |
| scenelock         | No       | Switch        | Locks/unlocks the current scene                                |
| sceneseq          | No       | Switch        | Starts/Stops the scene sequence                                |
| zonelock          | No       | Switch        | Locks/unlocks the zones                                        |
| zonefade          | No       | Number        | The seconds to fade from one intensity to the next             |
| zonelowerX        | No       | Switch        | Lowers the specified zone                                      |
| zoneraiseX        | No       | Switch        | Raises the specified zone                                      |
| zoneintensityX    | No       | Number        | Specifies the zone intensity                                   |
| zoneshadeX        | No       | Rollershutter | Specifies the shade zone                                       |

#### Grafik Eye Notes

- The "buttonpress" channel reports which keypad button was pressed.  DIP switch 6 must be set on the interface for this to be reported.  The "buttonpress" channel is only useful in rules to take action when a specific button (on a specific keypad) has been pressed.
- Sunset/sunrise will only be available if configured via the Liasion software
- scenelock, sceneseq, zonelock cannot be determined from the API and will default to OFF on startup
- Replace the "X" on zonelowerX, zoneraiseX, etc with the zone in question.  "zonelower1" will affect zone 1.  Specifying a zone larger than you have will have no effect (such as using zonelower8 on a Grafik Eye 3506 which only has 6 zones).
- The zonefade value will only be used when zonelower/zonereaise/zoneintensity is issued.
- zoneshade does not support PercentType nor StopMoveType.Move and those commands will be ignored
- zoneintensity can be used on a shade zone if the intensity is from 0 to 5 and should be used if wanting to set a QED preset: 0=Stop, 1=Open, 2=Close, 3=Preset 1, 4=Preset 2, 5=Preset 3
- If you started a zonelower or zoneraise, the only way to stop the action is by executing an all zone stop on the bridge (i.e. zonelowerstop or zoneraisestop).  The PRG API does not provide a way to stop the lowering/raising of any specific zone.

### Grafik Eye Example

demo.Things:

```java
lutron:prgbridge:home [ ipAddress="192.168.1.51", user="nwk", retryPolling=10 ]
lutron:grafikeye:home (lutron:prgbridge:home) [ controlUnit=1, fade=10, polling=10 ]
```

demo.items:

```java
String Prg_ButtonPress "Last Button Press [%s]" { channel = "lutron:prgbridge:home:buttonpress" }
Switch Prg_ZoneLowerStop "Zone Lower Stop" { channel = "lutron:prgbridge:home:zonelowerstop",autoupdate="false" }
Switch Prg_ZoneRaiseStop "Zone Raise Stop" { channel = "lutron:prgbridge:home:zoneraisestop",autoupdate="false" }
DateTime Prg_Time "Current Time: [%1$tF %1$tr]" { channel="lutron:prgbridge:home:timeclock" }
Number Prg_Schedule "Schedule [%s]" { channel="lutron:prgbridge:home:schedule" }
DateTime Prg_Sunrise "Sunrise [%1$tF %1$tr]" { channel="lutron:prgbridge:home:sunrise" }
DateTime Prg_Sunset "Sunset [%1$tF %1$tr]" { channel="lutron:prgbridge:home:sunset" }
Switch Prg_Start "Super Schedule Start" { channel="lutron:prgbridge:home:ssstart", autoupdate="false"  }
Switch Prg_Pause "Super Schedule Pause" { channel="lutron:prgbridge:home:sspause", autoupdate="false"  }
Switch Prg_Resume "Super Schedule Resume" { channel="lutron:prgbridge:home:ssresume", autoupdate="false"  }
String Prg_Status "Super Schedule Status [%s]" { channel="lutron:prgbridge:home:ssstatus" }
Number Prg_NextStep "Super Schedule Next Step [%s]" { channel="lutron:prgbridge:home:ssnextstep" }
Number Prg_NextMinute "Super Schedule Next Step Minutes [%s]" { channel="lutron:prgbridge:home:ssnextminute" }
Number Prg_NextSecond "Super Schedule Next Step Seconds [%s]" { channel="lutron:prgbridge:home:ssnextsecond" }

Number Grx_Scene "Scene [%s]" { channel="lutron:grafikeye:home:scene" }
Switch Grx_SceneLock "Scene Lock" { channel="lutron:grafikeye:home:scenelock" }
Switch Grx_SceneSeq "Scene Sequence" { channel="lutron:grafikeye:home:sceneseq" }
Switch Grx_ZoneLock "Zone Lock" { channel="lutron:grafikeye:home:zonelock" }
Switch Grx_ZoneLower1 "Zone 1 Lower" { channel="lutron:grafikeye:home:zonelower1" }
Switch Grx_ZoneLower2 "Zone 2 Lower" { channel="lutron:grafikeye:home:zonelower2" }
Switch Grx_ZoneLower3 "Zone 3 Lower" { channel="lutron:grafikeye:home:zonelower3" }
Switch Grx_ZoneLower4 "Zone 4 Lower" { channel="lutron:grafikeye:home:zonelower4" }
Switch Grx_ZoneLower5 "Zone 5 Lower" { channel="lutron:grafikeye:home:zonelower5" }
Switch Grx_ZoneLower6 "Zone 6 Lower" { channel="lutron:grafikeye:home:zonelower6" }
Switch Grx_ZoneLower7 "Zone 7 Lower" { channel="lutron:grafikeye:home:zonelower7" }
Switch Grx_ZoneLower8 "Zone 8 Lower" { channel="lutron:grafikeye:home:zonelower8" }
Switch Grx_ZoneRaise1 "Zone 1 Raise" { channel="lutron:grafikeye:home:zoneraise1" }
Switch Grx_ZoneRaise2 "Zone 2 Raise" { channel="lutron:grafikeye:home:zoneraise2" }
Switch Grx_ZoneRaise3 "Zone 3 Raise" { channel="lutron:grafikeye:home:zoneraise3" }
Switch Grx_ZoneRaise4 "Zone 4 Raise" { channel="lutron:grafikeye:home:zoneraise4" }
Switch Grx_ZoneRaise5 "Zone 5 Raise" { channel="lutron:grafikeye:home:zoneraise5" }
Switch Grx_ZoneRaise6 "Zone 6 Raise" { channel="lutron:grafikeye:home:zoneraise6" }
Switch Grx_ZoneRaise7 "Zone 7 Raise" { channel="lutron:grafikeye:home:zoneraise7" }
Switch Grx_ZoneRaise8 "Zone 8 Raise" { channel="lutron:grafikeye:home:zoneraise8" }
Number Grx_ZoneFade "Zone Fade [%s sec]" { channel="lutron:grafikeye:home:zonefade" }
Dimmer Grx_ZoneIntensity1 "Zone 1 Intensity [%d %%]" { channel="lutron:grafikeye:home:zoneintensity1" }
Dimmer Grx_ZoneIntensity2 "Zone 2 Intensity [%d %%]" { channel="lutron:grafikeye:home:zoneintensity2" }
Dimmer Grx_ZoneIntensity3 "Zone 3 Intensity [%d %%]" { channel="lutron:grafikeye:home:zoneintensity3" }
Dimmer Grx_ZoneIntensity4 "Zone 4 Intensity [%d %%]" { channel="lutron:grafikeye:home:zoneintensity4" }
Dimmer Grx_ZoneIntensity5 "Zone 5 Intensity [%d %%]" { channel="lutron:grafikeye:home:zoneintensity5" }
Dimmer Grx_ZoneIntensity6 "Zone 6 Intensity [%d %%]" { channel="lutron:grafikeye:home:zoneintensity6" }
Dimmer Grx_ZoneIntensity7 "Zone 7 Intensity [%d %%]" { channel="lutron:grafikeye:home:zoneintensity7" }
Dimmer Grx_ZoneIntensity8 "Zone 8 Intensity [%d %%]" { channel="lutron:grafikeye:home:zoneintensity8" }
Rollershutter Grx_ZoneShade1 "Zone 1 Shade" { channel="lutron:grafikeye:home:zoneshade1" }
Rollershutter Grx_ZoneShade2 "Zone 2 Shade" { channel="lutron:grafikeye:home:zoneshade2" }
Rollershutter Grx_ZoneShade3 "Zone 3 Shade" { channel="lutron:grafikeye:home:zoneshade3" }
Rollershutter Grx_ZoneShade4 "Zone 4 Shade" { channel="lutron:grafikeye:home:zoneshade4" }
Rollershutter Grx_ZoneShade5 "Zone 5 Shade" { channel="lutron:grafikeye:home:zoneshade5" }
Rollershutter Grx_ZoneShade6 "Zone 6 Shade" { channel="lutron:grafikeye:home:zoneshade6" }
Rollershutter Grx_ZoneShade7 "Zone 7 Shade" { channel="lutron:grafikeye:home:zoneshade7" }
Rollershutter Grx_ZoneShade8 "Zone 8 Shade" { channel="lutron:grafikeye:home:zoneshade8" }
```

Lutron, GRAFIK Eye, HomeWorks, HomeWorks QS, RadioRA, RadioRA 2, RA2 Select, Caseta, Sivoia QS, Serena, seeTouch, Pico, and Quantum are trademarks of Lutron Electronics Co., Inc.
HomeLink is a registered trademark of Gentex Corporation.
This software and its associated documentation are not endorsed or approved by Lutron Electronics Co.
