Lutron OH2 binding

ah okay, thanks. That’s very surprising. I figured it’d be available on Amazon. Even going to their website they don’t make it very clear. It felt so buried. Thanks.

Where’s the documentation for the “DSL” for this binding?

I’m failing miserably trying to even get dimmers and keypads recognized through manual configuration (as I’m told that best practice is only to use the Paper UI / jsondb configuration for auto-discovered devices), not to mention limiting the overabundance of channels created and setting their names to something meaningful.

http://docs.openhab.org/addons/bindings/lutron/readme.html is very incomplete.

Eclipse SmartHome Designer, at least when it comes to defining Lutron Things, hasn’t suggested/completed anything at all. I’ve tried both v0.8.0 and v0.9.0 (as I started this before the changes to the docs were made telling people to avoid the snapshot versions).

https://www.eclipse.org/smarthome/documentation/features/dsl.html doesn’t have any meaningful information past general concepts.

http://docs.openhab.org/configuration/things.html is barely a skeleton.

Running openHAB-2.0.0 (release) on RPi 3, Raspian

Trying to add these manually so that I have some control over the naming of things and the plethora of useless channels attached to the keypads (Pico remotes only have buttons 2-6, not the other four buttons or the eight LEDs), things are failing miserably, even without getting to channels and their naming.

The following gets SmartBridge PRO recognized and I can see it responding in the openHAB logs.

Thing lutron:ipbridge:smartbridgepro	"SmartBridgePRO"	[ ipAddress="<ip address>", user="lutron", password="integration" ]

However, the dimmers and keypads all show “UNINITIALIZED” in Paper UI Configuration > Things list and " UNINITIALIZED - HANDLER_CONFIGURATION_PENDING" when clicking through to their detail screen.

Thing lutron:dimmer:hall_cans		"Hall Cans"		( lutron:ipbridge:smartbridgepro ) [ integrationID=6 ]
Thing lutron:keypad:hall_remote		"Hall"			( lutron:ipbridge:smartbridgepro ) [ integrationID=7 ]

I have confirmed that the integrationID is correct.

I know that the fade in/out times are optional, both from the documentation cited above, as well as previous Paper UI configuration and looking at the jsondb entries.

I know that the bridge, dimmers, and remotes are working, as the Lutron software can read and control the lights, as well as seeing the keypad presses and light levels on the bridge’s telnet port.

Any assistance in at least getting these devices recognized by openHAB would be greatly appreciated, especially if I can prevent the auto-generation and auto-naming of the channels for the keypad. The auto-generated ones are just going to lead to completely unreadable triggers and conditions in rules.

Could you expound on what is missing so we can add it?

You should be able to turn off unused channels in Paper UI. If you turn off Simple Mode in the Paper UI settings, the auto-discovery should stop creating items for every channel. You can then manually (through Paper UI when editing a “thing” under Configuration) link channels to new items that you create and can name whatever you want.

Generally speaking, the only thing that devices need are the link to the bridge and the integration ID. The only problem I see with your setup is that you’re using integrationID instead of integrationId.

So I actually went out and got the Smart Bridge Pro. Thought it’d show up immediately in my OH2 inbox, but alas, nothing. Is there something I need to do to set this up? People appear to be mentioning that the .jar needed some modification to work with the Caseta Smart Bridge Pro.

Should the Smart Bridge Pro immediately be recognized or do I have to do something to make it work? Telnet is enabled.

They don’t show up currently. I have a change to add Smart Bridge discovery, but I haven’t submitted it yet. Even then, it’ll only discover the bridge itself, it won’t discover any other devices.

Can the lights be added manually?

Or are you saying that the only current functionality is seeing the bridge?

Has anyone come up with a way to do this at all? I thought people were saying they could configure the binding to see the caseta bridge pro because it uses a similar telnet system as the other lutron products.

Sorry, just spent sooooo much money outfitting my house. I wanna make this work.

Yes, they can be added manually. I only meant that the automatic discovery won’t work.

I appreciate your quick response, and apologize for not responding sooner.

Unfortunately, Paper UI and internally managed configuration is a not a reasonable possibility for several reasons:

  • Usability when trying to enter a non-trivial number of devices. With 20 dimmers and a dozen remotes, that’s over 120 individual entries that need to be made. With a one-by-one UI, that is infeasible

  • Auto-naming results in unrecognizable device names for rules or UI development. Since it is the colon-notation name that needs to be used and not a human-readable name, having a “random” string in not acceptable for anything but the most trivial tasks. Even if the parent is named in Paper UI, “Button2” is not anywhere near as useful and readable as “ButtonOn” or the like.

  • Auto-named items cannot be renamed. Goes along with the above. No way in Paper UI to be able to change the unique identifier for anything, once generated.

  • Perhaps most importantly, internally managed devices can’t be accessed by Designer to create rules. Believing that a graphical UI for rules generation is usable for anything more than the simplest rules with a trivial number of devices is questionable, at best.

What documentation is missing?

  • There is nothing that I can find about even the high-level syntax of the files, not to mention lower-level things like the acceptable character set and length for a given field. https://eclipse.org/smarthome/documentation/index.html describes some of how to write a binding, but not how to use one. While not specifically a problem with this binding, the lack of information about the file syntax makes it very difficult to use any binding.

  • I believe that it is possible to specify the channels in the same block as the thing itself. I can’t find any documentation for this, nor is there an example in the Lutron OH2 binding documentation. Being able to keep everything related with a single, physical device in one place in a single file is a key tenet of maintainability. Note: Found again what I recalled seeing, https://eclipse.org/smarthome/documentation/features/dsl.html#defining-channels

  • The Lutron OH2 binding does not show how to specify location, label, tag,… and there is no way that I know of to “export” internally managed devices to the file-based format to gain insight.

  • There is no documentation of how to respond to or generate events for the SmartBridge Pro itself (IntegrationId 1), which generates events when a preset is “matched” and accepts events to activate a preset (represented as a button)

Edit – As I try again to decipher the inconsistent documentation across the OpenHAB project, I find that http://docs.openhab.org/addons/bindings/lutron/readme.html appears to “steal” the group notation from Items for a configuration parameter:

Thing lutron:dimmer:livingroom (lutron:ipbridge:radiora2) [ integrationId=8, fadeInTime=0.5, fadeOutTime=5 ]

and is inconsistent with the syntax given for a Thing on http://docs.openhab.org/configuration/things.html

Thing <binding_id>:<type_id>:<thing_id> "Label" @ "Location" [ <parameters> ]

Contrary to documentation (http://docs.openhab.org/configuration/items.html for example) that states

When you install a binding through PaperUI it will automatically create a .cfg file in conf/services/ for the appropriate binding.

there is no “conf” directory to be found anywhere that has anything to do with OpenHAB:
$ sudo find / -type d -name conf
/proc/sys/net/ipv4/conf
/proc/sys/net/ipv6/conf

nor is there anything named lutron.cfg or close in or under /var/lib/openhab2

Edit 2 - https://eclipse.org/smarthome/documentation/features/dsl.html states that

Bridges that are defined somewhere else can also be referenced in the DSL:

Thing hue:0210:mybridge:bulb (hue:bridge:mybridge) [lightId="3"]

The referenced bridge is specified in the parentheses. Please notice that the UID of the thing also contains the bridge ID as third segment. For the contained notation of things the UID will be inherited and the bridge ID is automatically taken as part of the resulting thing UID.

This, however, is also contradictory to the documentation of the Lutron binding.

Past this, there appears to be a parser problem with the "description" @ "location" syntax, causing the file parsing to halt without giving any error or warning in the logs. I had at first thought it a problem with the Eclipse Designer 0.8.0, as the example from http://docs.openhab.org/configuration/things.html

Thing network:device:webcam "Webcam" @ "Living Room" [ hostname="192.168.0.2", timeout="5000", ... ]

gives the reasonably meaningless error message “missing EOF at ‘@’” but I have confirmed that the "description" @ "location" notation causes failure to parse at run time.

2 Likes

How would I add then manually? Or could you point me to some documentation on it? I’m digging through it, but its a little confusing what to follow.

Very strange behavior with Pico remotes is present and is showing up with trying to run rules. It appears that the state transitions related to the buttons are not followed properly.

The bridge is configured and responding. The remote in question has been set up with integration ID 30, and is not associated with any lights in the Smart Bridge Pro. Configuration of the lutron:keypad and associated items are as follows:

lutron:keypad:Test_Pico "Test Pico@Jeff Office Desk" (lutron:ipbridge:SmartBridgePro) [ integrationId=30 ]
lutron:dimmer:Jeff_Office "Jeff Office@Jeff Office" (lutron:ipbridge:SmartBridgePro) [ integrationId=24 ]

(No, the above doesn’t allow the location of the keypad to be defined, just my last-ditch attempt at guessing how to use the "description" @ "location" notation)

Group group_room_Jeff_Office
Dimmer caseta_dimmer_Jeff_Office "Dimmer Jeff Office %.0f" <dimmablelight> (group_room_Jeff_Office) { channel="lutron:dimmer:Jeff_Office:lightlevel" }
Group group_pico_Test_Pico

Switch pico_Test_Pico_on "Pico Test Pico On" <switch> (group_pico_Test_Pico) { channel="lutron:keypad:Test_Pico:button2" }

Switch pico_Test_Pico_preset "Pico Test Pico Preset" <switch> (group_pico_Test_Pico) { channel="lutron:keypad:Test_Pico:button3" }

Switch pico_Test_Pico_off "Pico Test Pico Off" <switch> (group_pico_Test_Pico) { channel="lutron:keypad:Test_Pico:button4" }

Switch pico_Test_Pico_up "Pico Test Pico Up" <switch> (group_pico_Test_Pico) { channel="lutron:keypad:Test_Pico:button5" }

Switch pico_Test_Pico_down "Pico Test Pico Down" <switch> (group_pico_Test_Pico) { channel="lutron:keypad:Test_Pico:button6" }

The only rules in play are ones that should turn on the lights when I click the top button, and turn off the lights when I click the bottom button.

rule "Test_Pico_Button_On"
when
	Item pico_Test_Pico_on changed from OFF to ON
then
	sendCommand(caseta_dimmer_Jeff_Office, ON)
end

rule "Test_Pico_Button_Off"
when
	Item pico_Test_Pico_off changed from OFF to ON
then
	sendCommand(caseta_dimmer_Jeff_Office, OFF)
end

What follows in the code blocks are the outputs of tail -F /var/log/openhab2/openhab.log and tail -F /var/log/openhab2/events.log running in the background, with the terminal session running telnet into the Smart Bridge Pro. As such there may be some skew between the three, depending on how buffering is being done.

For readers not immediately familiar with the Lutron protocol, ~DEVICE,m,n,p indicates a state change in one of the devices. 30,2 is the on button, 30,4 is the off button, ,3 is key pressed and ,4 is key released.

Light is off, press on button

2017-03-12 11:23:29.341 [ItemCommandEvent          ] - Item 'pico_Test_Pico_on' received command ON
2017-03-12 11:23:29.586 [ItemCommandEvent          ] - Item 'pico_Test_Pico_on' received command OFF
2017-03-12 11:23:29.592 [ItemStateChangedEvent     ] - pico_Test_Pico_on changed from ON to OFF
~DEVICE,30,2,3
~DEVICE,30,2,4

Nothing happens. The light is still off.

Although the keypad transitioned from off (up) to on (depressed) and back to off again, there was only a single ON to OFF state change, rather than two events, OFF to ON and ON to OFF.

Light is off, press on button

2017-03-12 11:23:58.098 [ItemCommandEvent          ] - Item 'pico_Test_Pico_on' received command ON
~DEVICE,30,2,3
2017-03-12 11:23:58.104 [ItemStateChangedEvent     ] - pico_Test_Pico_on changed from OFF to ON
2017-03-12 11:23:58.127 [ItemCommandEvent          ] - Item 'caseta_dimmer_Jeff_Office' received command ON
2017-03-12 11:23:58.136 [GroupItemStateChangedEvent] - group_room_Jeff_Office changed from 0.00 to 100 through caseta_dimmer_Jeff_Office
2017-03-12 11:23:58.140 [ItemStateChangedEvent     ] - caseta_dimmer_Jeff_Office changed from 0.00 to 100
2017-03-12 11:23:58.167 [INFO ] [nding.lutron.handler.IPBridgeHandler] - Ignoring message GNET> ~OUTPUT,24,1,100.00
~OUTPUT,24,1,100.00
~DEVICE,30,2,4
2017-03-12 11:23:58.353 [ItemCommandEvent          ] - Item 'pico_Test_Pico_on' received command OFF
2017-03-12 11:23:58.356 [ItemStateChangedEvent     ] - pico_Test_Pico_on changed from ON to OFF

This time transition is seen and the dimmer is commanded to turn on, as expected.

This time, both state change events occurred, as expected, OFF to ON and ON to OFF.

Light is on, press off button

~DEVICE,30,4,3
2017-03-12 11:24:18.764 [ItemCommandEvent          ] - Item 'pico_Test_Pico_off' received command ON
~DEVICE,30,4,4
2017-03-12 11:24:18.985 [ItemCommandEvent          ] - Item 'pico_Test_Pico_off' received command OFF
2017-03-12 11:24:18.990 [ItemStateChangedEvent     ] - pico_Test_Pico_off changed from ON to OFF

Once again, nothing happens, the light is still on.

Again, there was only a single ON to OFF state change, rather than two events, OFF to ON and ON to OFF.

Light is on, press off button

2017-03-12 11:24:34.434 [ItemCommandEvent          ] - Item 'pico_Test_Pico_off' received command ON
2017-03-12 11:24:34.440 [ItemStateChangedEvent     ] - pico_Test_Pico_off changed from OFF to ON
2017-03-12 11:24:34.465 [ItemCommandEvent          ] - Item 'caseta_dimmer_Jeff_Office' received command OFF
2017-03-12 11:24:34.471 [ItemStateChangedEvent     ] - caseta_dimmer_Jeff_Office changed from 100 to 0
2017-03-12 11:24:34.471 [GroupItemStateChangedEvent] - group_room_Jeff_Office changed from 100 to 0 through caseta_dimmer_Jeff_Office
~DEVICE,30,4,3
~OUTPUT,24,1,0.00
~DEVICE,30,4,4
2017-03-12 11:24:34.678 [INFO ] [nding.lutron.handler.IPBridgeHandler] - Ignoring message GNET> ~DEVICE,30,4,4

Again, the second time, the transition is seen and the light changes state, to off.

This time, only a single state change events occurred, OFF to ON, and the binding ignored the message from the Smart Bridge Pro indicating that key-up event.

OK, so maybe the initialization of state isn’t right. By now, I’ve cycled both the dimmer and the remote and both should arguably be “in sync” with the devices, right? No, it still requires two pushes of the on or off button to see one change in state.

Maybe I’m missing something here, but this binding doesn’t appear tracking keypad button events properly at all.

Thanks to @actong88 and the maintainers, this has been resolved in the master branch.

This binding definitely is not functioning in a way that keypad events can be used to moderate lighting levels, at least with a Smart Bridge Pro. It might be different with the $1000 Lutron controllers, but given that they use the same protocol, I would be surprised if this the same issues did not exist there as well.

Edit – PR submitted, and there appears to be another PR on this topic (which has been accepted)

In Paper UI, you can add things from the Inbox or from Configuration->Things. I don’t have it in front of me, but there should be a plus (+) button you click on. This may trigger an automatic search, but you can click the Add Thing Manually link, at which point you’ll be directed through a wizard to select the binding and thing type to add.

Besides implementing autodiscovery, I’m not sure what the binding can do about that. I’d love to implement autodiscovery for Caseta, but I don’t know of a way to do that.

The colon-separated names are the thing IDs, but it’s the item names that you use in rules, not the thing IDs. Items can be named whatever you want if you create the items manually, which presumably you’d have to do if you don’t want auto-generated names.

These sound like issues with Paper UI and/or OpenHAB in general. The only thing I can suggest is to open issues for the appropriate subsystems. For renaming auto-generated items, I believe the usual recourse is to unlink and delete the item and recreate it manually; obviously not ideal.

The Lutron binding won’t use these custom-defined channels.

You can specify item location in Paper UI, but the binding doesn’t really have anything to do with that. As far as exporting things from the Paper UI database, I’m not really sure how to do that. I’d suggest opening another thread to pose that question.

This is something the binding currently doesn’t handle, for Caseta or any other system.

That associates the thing to a bridge and is not anything specific to the Lutron binding. I do remember having to hunt that syntax down because its documentation does seem hard to come by.

I wasn’t aware of this, and I’m not sure if that’s a binding issue, a Paper UI issue, or a stale documentation issue, but in any case, there is no binding-level configuration for the Lutron binding, so there would be nothing to configure in a .cfg file.

Looks like you found the documentation about linking things to their bridge :slight_smile:. I guess you’re referring to the fact that the hue thing has the bridge name in its thing ID, but that’s not present in the sample Lutron configuration? I think that’s just a convention and not strictly necessary, but I could update the documentation if it confuses things.

I’d suggest opening an issue for this. This does not look like a binding issue.

Thanks to @steve1 in

I’ve been able to update my scripts to output syntactically correct Things and Items for the Lutron OH2 binding. While there are gaps in the documentation, @actong88 is correct that this is not a binding issue. From what I can tell, the binding does not parse the file at all. It just “takes” the configuration values that the parser populates and uses them.

I’ve written simple Bash scripts that take tab-separated value input of the integration ID, “friendly” name, and room for the (Caseta) dimmers and remotes and create the .things and .items files from them. PM me if you’d like them.

I haven’t delved into “tags” yet, but the referenced syntax specifications make it clear how they would be added. I’m poking around with defining “phantom” channels on the dimmers to hold state information to be able to emulate the increase/decrease functionality of the dimmers and remotes. To be clear, these channels are outside of the binding’s prevue and will be managed by rules/scripts.

Here are some examples from my current configuration.

###Things

####Bridge

lutron:ipbridge:SmartBridgePro "Smart Bridge Pro" @ "Home" [ ipAddress="smartbridgepro.example.com", user="lutron", password="integration" ]

####Dimmer

lutron:dimmer:Bedroom_East_Cans "Bedroom East Cans" (lutron:ipbridge:SmartBridgePro) @ "Bedroom" [ integrationId=2 ]

####Keypad

lutron:keypad:Bedroom "Bedroom" (lutron:ipbridge:SmartBridgePro) @ "Bedroom" [ integrationId=3 ]

###Items

####Dimmer

Dimmer caseta_dimmer_Bedroom_East_Cans "Dimmer Bedroom East Cans [%.0f]" <dimmablelight> (group_room_Bedroom) { channel="lutron:dimmer:Bedroom_East_Cans:lightlevel" }

####Switches

Group group_pico_Bedroom

Switch pico_Bedroom_on "Pico Bedroom On" <switch> (group_pico_Bedroom) { channel="lutron:keypad:Bedroom:button2" }

Switch pico_Bedroom_preset "Pico Bedroom Preset" <switch> (group_pico_Bedroom) { channel="lutron:keypad:Bedroom:button3" }

Switch pico_Bedroom_off "Pico Bedroom Off" <switch> (group_pico_Bedroom) { channel="lutron:keypad:Bedroom:button4" }

Switch pico_Bedroom_up "Pico Bedroom Up" <switch> (group_pico_Bedroom) { channel="lutron:keypad:Bedroom:button5" }

Switch pico_Bedroom_down "Pico Bedroom Down" <switch> (group_pico_Bedroom) { channel="lutron:keypad:Bedroom:button6" }

A Smart Bridge PRO has 100 “buttons” which correspond to the preset scenes set through the Lutron app. “Pressing” one sets the associated dimmers to their preset levels. I believe that if the Smart Bridge PRO detects that the dimmers associated with a scene have the same level as one or more scenes, then it notifies that the button(s) has (have) been “pressed” (though I’ll have to confirm that).

I’m going to try to modify the binding to make these accessible within openHAB2.

Is there a preference for 100 channels, or one channel with, for example, a set of strings that correspond to the scene names? It appears that the Lutron app won’t let you set duplicate names. The names can be changed through the app, so they are not an invariant identifier for rules, and the like.

If you’ve wanted to implement the up/down functionality of Pico remotes and/or Caseta/maestro dimmers, there is a patch and a PR to make the changes to support INCREASE/DECREASE/STOP for dimmers under this binding.

Tying INCREASE (or DECREASE) to button-down and STOP to button-release events mimics the behavior of Pico remote quite nicely.

This appears related to a previous attempt to try and add support for phantom buttons (PR #1670). Note, however, that if you’re planning on simulating button pushes from within OH, that has met with resistance in the past. See the discussion here (open up the hidden comments that say Show 11 comments).

I think the gist of it is that the binding should expose scenes rather than buttons, but scenes are going to vary from installation to installation; some phantom buttons may trigger a preset scene (always set loads to preset levels), while other phantom buttons may act like a toggle (“press” once to turn a set of loads on, “press” again to turn them off). It was suggested that this be handled through custom ad-hoc channels instead of predefining channels as part of the thing-type.

Hey Allan, thanks for your work on this binding. My RadioRA2 system is the heart of my home automation, so I’m well acquainted with the Lutron Integration protocol. However, I’m just diving into OpenHAB, so I have some pretty basic questions.

  1. Is there anyway to simulate a button press through the OpenHab Keypad switch item? When I add a keypad button in the Paper UI, it correctly updates the LED status when I press the physical button, but when I press the virtual button in Paper UI, it doesn’t do anything. Is there something I can define in a .map file or .rules file to send the Lutron command to press, for example, button 1 on integration ID 27 (#DEVICE,27,1,3)?

  2. Could individual keypad buttons be added as things using both the Integration ID and component - ie Integration ID 27, button1 for the top button on a keypad with ID=27? I have a Grafik Eye in my Radio RA2 system, which basically just works as a large keypad with non standard button numbers. Instead of buttons 1-6, the range is, in my system, 38-83. Or perhaps the best way to do this is in a .items file - would Switch GrafikEye38 { channel=“lutron:keypad:GrafikEye:button38” } define a valid item/ channel? This would also allow me to use the phantom buttons on my main Repeater (Integration ID=1, components = 1 to 100, plus LEDs 101-200).

As you noted above, there appears to be some resistance to simulating button presses, but as I’ve already defined all of my scenes using the RadioRA2 software, it makes more sense to keep it that way, and use OpenHab to press phantom/ physical buttons.

I’m using a Smart Bridge PRO, but at least there when I use Switch Items (see my previous post for my file-based config) for Pico remotes an openHAB event is generated on both press and release. Where the Pico is configured with the Lutron app, the corresponding action is taken without openHAB intervention. I can also trigger openHAB actions through rules, either or both on button-down and -up.

openHAB, for better or worse, abstracts things to a very fine-grained level. That your bridge’s configuration or innate behavior is apparently to update the LEDs, openHAB sees them as independent. You can emulate the behavior in rules.

I’m not sure what you’re trying to achieve in (2). In openHAB you need a Thing to represent the physical device, then one or more Items to access the state and/or send commands to the predefined Channels of the Thing. Sounds wacky at first, OK, still, but you need a Thing for a keypad that creates individual Channels for all its buttons and LED. Then you need Items for each button or LED you what state information from or to command. I generate all of these with some shell scripts as the “simple mode” creates opaque Item names, making rules close to unreadable.

There isn’t a great way to improve this naming, especially when the friendly name of “ID 27” can be changed through consumer apps and a Thing or Item name needs to be a unique identifier in openHAB. It’s further complicated in that I’m not aware of an officially documented way to get the mapping from integration ID to friendly name from the Smart Bridge series through direct access to the bridge.

Unfortunately no. A workaround might be to have an OH rule do everything that the native keypad button does (assuming OH can do everything that the keypad button is doing), but of course this means defining and maintaining your scene twice.

Edit: just saw Jeff’s reply. With (1), I was assuming you’re trying to have OH “send” a button press to RadioRA2. The binding should be able to respond to physical button presses coming from RadioRA2.

It doesn’t work that way. The current keypad handler has a fixed set of buttons it handles. We probably need to define a new thing type for the Grafik Eye.