**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.
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.
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.
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.
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.
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.
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.
seeTouch and Hybrid seeTouch keypads are interfaced with using the **keypad** thing.
In addition to the usual `integrationId` parameter, it accepts `model` and `autorelease` parameters.
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.
The `autorelease` parameter is a boolean.
Setting it to true will cause each button channel state to transition back to OFF (released) automatically after a going to ON when a button is pressed.
Normally, a Lutron keypad will send a "pressed" event when a button is pressed, and a "released" event when it is released.
The handler will set the button channel state to ON when it receives the "pressed" event, and "off" when it receives the "released" event.
This allows you to take actions on both state changes.
However, some integration applications such as Lutron Home+ only cause a "pressed" event to be generated when remotely "pressing" a button.
A "release" is never sent, therefore the button channel would become "stuck" in the ON state.
To prevent this the `autorelease` parameter defaults to true.
If you do not use integration applications that exhibit this sort of anti-social behavior and you wish to trigger rules on both button press and release, you should set `autorelease` to false.
The `autorelease` parameter also effects behavior when sending an ON command to a button channel to trigger a remote button press.
If `autorelease` is set, the handler will send action "release" to the device component immediately after sending action "press".
When the controller responds, the channel state will be transitioned back to OFF.
A channel _button[nn]_ with item type Switch and category Switch is created for each button, and a channel _led[nn]_ with item type Switch and category Light is created for each button indicator LED.
You can monitor button channels for ON and OFF state changes to indicate button presses and releases, and send ON and OFF commands to remotely press and release buttons.
Ditto for the indicator LED channels.
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.
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.
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.
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.
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.
It accepts the same `integrationId`, `model`, and `autorelease` 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.
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.
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`, `model`, and `autorelease` 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.
It presents ON/OFF states the same as a keypad button.
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.
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.
The behavior of this binding is the same as the other keypad bindings, with the exception that the button and LED channels created have the Advanced flag set.
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).
Supported options are `integrationId` and `autorelease`.
Supplying a model is not required, as there is only one model.
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.
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.
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.
**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.
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.
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.
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.
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.
- _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.
| 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.
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.
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.
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.
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).
# 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.
## Supported Things
1-8 Grafik Eye 3x/4x System(s) through the interface
## Discovery
This binding does not support discovery of the GRX-PRG or GRX-CI-PRG.
You will need to specify them directly.
## 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).
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.
- 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.
