\n\n## π Installation and Setup\n\nThis plugin requires [`homebridge-config-ui-x`](https://github.com/oznu/homebridge-config-ui-x#readme) for initial setup. Install the plugin using the UI.\n\nOnce that's done, open the configuration screen:\n\n\n\nClick \"Settings\" for this plugin. You should see your bridges listed. I only have one, but if you have more, they'll appear here. They are discovered automatically.\n\n\n\nClick on \"Associate\", and then press the button on the back of your Smart Bridge 2 device within 30 seconds. The UI will update, and if all goes well, you will see:\n\n\n\nClick the save button at the bottom, and you're done.\n\n### Options\n\n#### Exclude Picos...\n\nBy default, all known Pico remotes are shown in the Home app. This means their functionality is duplicated, in a sense. Configuration in Homekit has no effect on operation with paired accessories, or anything else in the Lutron app. With no further action, you can use them (HomeKit and the Lutron App) both simultaneously.\n\n_If you want to only show Picos that do not have associations_ in the Lutron app, check the configuration box for \"Exclude Pico remotes...\". This will hide them from HomeKit. Please note that hiding them is not a destructive operation, and you can un-hide them in the future and (I _think..._) you won't lose their setup when they come back.\n\n#### Disable support for Serena...\n\nWhen this plugin was written, Lutron did not support the Serena Tilt-Only Wood Blinds in HomeKit. They have since added that support. If you do not disable support in the plugin, your blinds will show up twice. _This is the default behavior_ in order not to break existing configurations, but you _probably_ want to turn on this option.\n\n#### Double- and long-press speed\n\nThis lets you set the speed with which you must click buttons in order to trigger a double- or a long-press of a button. The default should be comfortable for most modern computer users. My hope is that slow and fast are better for some users. If you find they do not work for you, please let me know!\n\nThese features can also be disabled individually in the settings. This can improve responsiveness to the remaining types of presses. **The configuration options in HomeKit do not change, but the plug-in will ignore disabled press types.**\n\n#### Log Verbosity\n\nTwo settings control how chatty the plugin's logs are:\n\n- **Log Verbosity** (`logLevel`): `normal` (default), `quiet`, or `errors-only`. `quiet` suppresses info-level lines (startup banners, retry-attempt notices, etc.) and `errors-only` additionally suppresses warnings, leaving only errors. Homebridge's own global debug toggle is unaffected β if you turn that on, debug output will still flow.\n- **Button Press Logging** (`buttonPressLogging`): `debug` (default), `info`, or `silent`. Button presses are special-cased because they're useful when wiring up automations but are noise the rest of the time. `debug` keeps them out of normal logs (visible only when global debug is enabled); `info` makes them visible in normal logs; `silent` drops them entirely.\n\nThe defaults reflect a sane \"production posture\" β startup and per-device discovery lines are visible at info, but per-event noise (button presses, mDNS re-announcements, blind-position polls) is at debug. Turn things up with `buttonPressLogging: info` for short-term troubleshooting, or down with `logLevel: quiet`/`errors-only` for long-term operation.\n\n## π User Information\n\n### Adding and Removing Devices\n\nIn order to add a device to the hub, you must use the Lutron app to pair the device. This plugin will re-scan the known devices 30 seconds after you announce the device. This means you must **complete adding the device in less than 30 seconds** in order for the device to appear in HomeKit without restarting the plugin. If you _do_ miss that deadline, don't worry: the device will appear after you restart Homebridge.\n\nTo remove a device from Homebridge after you're removed it from the Smart Bridge 2, you must [delete the cached accessory out of Homebridge manually](https://github.com/oznu/homebridge-config-ui-x/issues/525).\n\n### Pico Remote Button Mapping\n\nPico buttons are mapped according to the following diagram:\n\n\n\nThe iOS Home app doesn't actually show button names (e.g. \"On\"), but only shows \"Button 1\". Other, better, iOS Homekit apps do, though. In any case, buttons are mapped from top-to-bottom. The top-most physical button is button 1, and is shown at the top of the list in the app.\n\nI don't own one of every remote type, so I've had to make guesses about the other supported remotes, and defer implementing some others. Currently supported are:\n\n- [2 Button](https://www.lutron.com/en-US/pages/SupportCenter/support.aspx?modelNumber=PJ2-2B&Section=Documents)\n- [2-Button with raise/lower](https://www.lutron.com/en-US/pages/SupportCenter/support.aspx?modelNumber=PJ2-2BRL&Section=Documents)\n- [3-Button](https://www.lutron.com/en-US/pages/SupportCenter/support.aspx?modelNumber=PJ2-3B&Section=Documents) (_untested_)\n- [3-Button with raise/lower](https://www.lutron.com/en-US/pages/SupportCenter/support.aspx?modelNumber=PJ2-3BRL&Section=Documents)\n- [3-Button Shade with raise/lower](https://www.lutron.com/TechnicalDocumentLibrary/369612.pdf) (`-S01`)\n- [4-Button](https://www.lutron.com/TechnicalDocumentLibrary/369847.pdf) (note only `-L01` model is supported)\n- [4-Button Scene Keypad](https://www.lutron.com/TechnicalDocumentLibrary/3691066_eng.pdf) (`-P01`)\n- [4-Button Dual Group](https://www.lutron.com/TechnicalDocumentLibrary/369847.pdf) (`-L21`)\n\nI'd love to have complete, tested support of all remote types. If you have hardware that is partially- or un-supported and, adding support is fast and easy. I would also be happy to add support for hardware that is provided to me.\n\n## β οΈ Support and Troubleshooting\n\nIf you need find a bug, need help with this plugin, or have questions, the best way to reach me is via a Github Issue. Please don't be shy about opening one. You can also reach me via the email address in my Github profile.\n\nThis plugin doesn't often change, but when I add big features or make big changes, I will occasionally join the [Lutron channel](https://discord.com/channels/432663330281226270/927991341923852389) on the [Homebridge Discord server](https://discord.gg/RcV7fa8).\n\n### Something weird is happening / The plugin is running slowly / Devices aren't appearing\n\nIf the plugin is generally misbehaving, users have reported success in running this plugin in a [child bridge](https://github.com/homebridge/homebridge/wiki/Child-Bridges). Doing this will require adding the bridge as a separate device and re-configuring your devices, which may or may not be acceptable. [This issue](https://github.com/homebridge-plugins/homebridge-lutron/issues/96) has some steps to accomplishing that.\n\nWhy does this change things? To be honest, I don't really know (and not knowing really bugs me). I've tried my best to follow best practices in designing this plugin but it seems to help sometimes. :(\n\n### My bridge doesn't appear in the configuration UI\n\nBridge discovery works using mDNS aka Bonjour aka zeroconf. This means that your Homebridge server sends a special message that's sent to every computer on the local network. If your bridge can't hear that packet for some reason, discovery won't work.\n\nWhy can't your bridge hear that packet? There are, unfortunately, an infinite number of possible reasons. Some keyword soup that might match something in your network configuration: broadcast relay repeat forwarding.\n\nSadly, that's all the support I can offer, as the particular problems are impossible to diagnose without access to your network. My best advice is to keep the bridge as close, network-wise, to the Homebridge server as possible. Good luck, and I'm sorry you're having problems.\n\n## πͺ² Enabling debugging\n\nIn order to enable debugging, set the DEBUG environment variable in the Homebridge UI to `leap:*`. This will make this plugin, and its main library `lutron-leap-js`, noisier. Logging at this level is required for diagnosis and new hardware support.\n\nTo do this, use the drop-down menu and click on \"Homebridge Settings\":\n\n\n\nThen, enter `leap:*` in the DEBUG field:\n\n\n\nThen, restart Homebridge.\n\nNote that enabling DEBUG logging increases the amount of log information _greatly_. This can mean other informational messages are drowned out. (Un)Fortunately, the log file is limited to 1 megabyte, so forgetting to turn it off won't mean that you fill your hard disk, but I do recommend disabling it after you're done collecting data.\n\n## π To-do and contributions\n\nThe following items are on my wishlist:\n\n- Extend the Serena blind support to enable the tilt characteristic directly (in addition to faking lift w/ tilt)\n- Add/validate support for RA2 bridges (would require hardware donation)\n\nI welcome contributions! I wrote this to scratch an itch (no Serena wood blind support), but would be fine with additional devices. To add a device:\n\n- Add a case to `LutronCasetaLeap.configureAccessory` and `handleBridgeDiscovery` for your new device type.\n- Add a class for your device. The constructor should wire up event handlers and manage services and characteristics.\n- Add relevant methods to the [`SmartBridge`](https://github.com/thenewwazoo/lutron-leap-js/blob/main/src/SmartBridge.ts) class in the `lutron-leap-js` project to control the device. These methods should construct command requests.\n- Add an \"unsolicited events\" and/or \"subscribed event\" handler in your new device class to update itself when new information arrives from the bridge, and to update characteristic values.\n\n## π Development setup\n\n(rough notes)\n\n- Check this out\n- Check out the lutron-leap-js repo\n- Make changes there and `npm run build` it\n- `npm install ../lutron-leap-js`\n- Make changes here\n- `rm ~/.homebridge/accessories/cachedAccessories; DEBUG='leap:*,HAP-NodeJS:Accessory' npm run watch`\n- `npm run lint`\n\n## π¨ Legacy Configuration\n\n> :warning: **This only applies if the UI doesn't work for you**: If that's the case, please file a ticket too.\n\n### Get your bridge ID\n\nThe bridge ID is the serial number, and is printed on the underside of the bridge, indicated here in green:\n\n\n\n### Get your bridge credentials\n\nThe easiest way is to use the [`get_lutron_cert.py`](https://github.com/gurumitts/pylutron-caseta/blob/dev/get_lutron_cert.py) script that comes with the [`pylutron-caseta`](https://github.com/gurumitts/pylutron-caseta) project, without which this would not have been possible.\n\n_NOTE_: these instructions require Python 3, which you may need to [install it yourself](https://www.python.org/downloads/).\n\n_NOTE_: these instructions may be out of date! If this doesn't work, please read the script itself.\n\nTo use the script, you'll want to check out the repo:\n\n```\ngit clone https://github.com/gurumitts/pylutron-caseta.git && cd pylutron-caseta\n```\n\nThen, create a venv and install the depedencies:\n\n```\npython3 -m venv env\n. env/bin/activate\npip install pyOpenSSL==19.1.0\npip install .\n```\n\nThen run the helper script:\n\n```\npython get_lutron_cert.py\n```\n\nEach file corresponds to a configuration item:\n\n- `caseta-bridge.crt` => CA certificate\n- `caseta.key` => Private key\n- `caseta.crt` => Signed certificate\n\n## Legacy Configuration File\n\nEach bridge on your network that you wish to control needs its own configuration entry.\n\n### Using `homebridge-config-ui-x`\n\nIf you're using the GUI, you'll want to fill out the form, copying and pasting in the appropriate fields:\n\n\n\nThe UI will handle multi-line input, so just paste it in.\n\nClick the \"ADD SECRETS\" button to add additional bridges.\n\n### Using `config.json`\n\nThe shape of the configuration is:\n\n```json\n{\n \"platform\": \"LutronCasetaLeap\",\n \"options\": {\n \"filterPico\": false,\n \"excludedDeviceTypes\": [],\n \"clickSpeedLong\": \"default\",\n \"clickSpeedDouble\": \"default\",\n \"logLevel\": \"normal\",\n \"buttonPressLogging\": \"debug\"\n },\n \"secrets\": [\n {\n \"bridgeid\": \"0a1b2c3d\",\n \"ca\": \"-----BEGIN CERTIFICATE-----\\nMII...\",\n \"key\": \"-----BEGIN PRIVATE KEY-----\\nMII...\",\n \"cert\": \"-----BEGIN CERTIFICATE-----\\nMII...\"\n }\n ]\n}\n```\n\nThe authn strings are newline-escaped versions of the files you generated.\n","readmeFilename":"README.md"}
![\"homebridge-verified\"](\"https://raw.githubusercontent.com/homebridge/plugins/latest/icons/homebridge-lutron.png?sanitize=true\"){kind=icon}
\n\n# Homebridge Lutron\n\n![](\"assets/PP_Acceptance_Marks_for_LogoCenter_76x48.png\")
\n![](\"assets/cash_app_dollar_icon.png\"){kind=icon}
\n![](\"assets/Venmo_Monogram.png\")
\n