Lux Configurable Keypad Driver Documentation

Driver download

Filename: control4_lux_configurable_keypad.c4z

Overview

This drivers is designed to be used with the following SKUs:

  • C4-L-KC

The driver contains firmware version 5.21.53.

Hardware Setup

See https://ctrl4.co/lux-qs for complete hardware setup information.

Known Issues

Current known issues for Lux drivers:

Control4 Driver Configuration

System Requirements

Requires OS 4.0.0 or higher.

The Lux devices require a ZigBee Lux mesh running on a Core controller. Before adding any Lux devices to the system, the ZigBee Lux mesh must be created using the project ZigBee Configuration interface and the mesh enabled and running.

Zigbee Configuration

In the Connections tab, under Network->Zigbee Network, double click on the driver you wish to identify. When prompted to identify the device, press the top button on the device four times.

Zigbee Button sequences

Button Sequence Function
4 tap Identify
15 tap Reboot
9-4-9 tap Factory Restore
13-4-13 tap Leave Mesh and Factory Restore

Firmware Upgrade

Once the device is identified to the driver or after a driver update has occured, the driver will automatically deploy the firmware image it comes bundiled with. The OS will then check with the device if a firmware update is needed or not. Note that it can take up to 10 minutes for the upgrade procedure to start. To manually initiate the check 4-tap the top keypad button or power-cycle the device.

Advanced Configuration

Device Details

The Details tab under Advanced Properties->Settings provides information about the driver and the device: driver and firmware versions, MAC address and Zigbee Information.

Ambient Light

Ambient light settings allow the user to configure the behavior of status and backlight LEDs. Depending on the recorded light level, room can be marked as either dark, dim or bright room. Image bellow displays the behavior of the status and backlight LEDs depending on the current room ambiance level.

Transition Levels

Ambient Light behavior can be configured on the Advanced Properties -> Settings -> Configure page. Status and Backlight LEDs can be independently enabled or disabled when the room is dark, dim or bright.

Status and Backlight LED intensities and transition levels between dark and dim, and dim and bright room can be configured by clicking on the Manage button.

Dark Room Status LED – Enable/disable status LEDs when the room is dark

Dark Room Backlight LED – Enable/disable backlight LEDs when the room is dark

Dim Room Status LED – Enable/disable status LEDs when the room is dim

Dim Room Backlight LED – Enable/disable backlight LEDs when the room is dim

Bright Room Status LED – Enable/disable status LEDs when the room is bright

Bright Room Backlight LED – Enable/disable backlight LEDs when the room is bright

Dark Room Status LED Intensity – Status LED intensity when the room is dark, provided that the LED is enabled

Dark Room Backlight LED Intensity – Backlight LED intensity when the room is dark, provided that the LED is enabled

Dim Room Status LED Intensity – Status LED intensity when the room is dim, provided that the LED is enabled

Dim Room Backlight LED Intensity – Backlight LED intensity when the room is dim, provided that the LED is enabled

Bright Room Status LED Intensity – Status LED intensity when the room is bright, provided that the LED is enabled

Bright Room Backlight LED Intensity – Backlight LED intensity when the room is bright, provided that the LED is enabled

Dark Room Transition Level - Ambient light level which defines a border between the dark and the dim room

Bright Room Transition Level - Ambient light level which defines a border between the dim and the bright room

Ambient Light functionality can also be disabled. In this case, Status and Backlight LEDs will have fixed intensities, that can be set from the driver, regardless of the room's light level.

NOTE: Disabling Ambient Light will disconnect all Ambient Light Level connections for this device. If Ambient Light is enabled afterwards, Ambient Mode will be set to Independent, and all Source/Follower connections will need to be recreated manually.

NOTE: When Backlight and/or Status LEDs are disabled from Composer Programming, changing any of their respective parameters will have no visible effect on the device. Only once they are enabled back again from programming will the changes be applied.

The Backlight Color Temperature can also be set to Warm White, Neutral White or Cold White.

Ambient Light settings from one device can be applied to one or more selected Lux devices with the APPLY TO button. If Ambient Light is enabled, Backlight Color Temperature and Dark/Dim/Bright Room settings will be copied over. If Ambient Light is disabled, Backlight Color Temperature and Backlight/Status LED Intensity values will applied.

Ambient Light Modes

Depending on which sensor is used for ambient light level reporting, the device can be in one of three Ambient Light Modes:

  • Source - The device is reading the ambient light level from its own sensor and broadcasting it to all follower devices
  • Follower - The device is using the ambient light level reported by the source device it is bound to
  • Independent - The device is operating in a standalone mode (i.e. ambient connections are not used) and is read the ambient light level from its own sensor

Source and Follower Ambient Mode is set using Ambient Light Level control connection on the Connections tab:

  1. Determine which Lux device is the source for the ambient light level
  2. Connect the Ambient Light Level (Source) connection of the source device to the Ambient Light Level (Follower) connection of each follower device.

Ambient Light Level Connections

It is also possible configure Ambient Light Mode using the Make This a Source Device button. This has the following effect:

  • Sets the current device as a source
  • Sets every selected devices as a follower
  • Automatically applies all Ambient Light settings from the source device to all selected devices.

This action is useful for Lux devices in a multi-gang box. In this case, all devices in a box should have the same Ambient Light settings and follow a single ambient light source.

Keypad Configuration

The keypad layout configuration can be assembled by arranging different buttons, which may occupy varying numbers of slots and exhibit different behaviors. The keypad configuration is valid only if all the slots are occupied. Until the layout is fully assembled, incomplete layouts will continue to behave the same as the previously known complete configuration.

Driver Actions

Reboot: Reboots the device

Factory Restore: Resets the device to its factory settings, but does not remove it from the mesh. The device will remain connected to the driver, and the driver will reconfigure it to its current settings in the project.

Add Firmware Image: Pass the firmware image to the OTA server. The result of this action will be displayed in the Firmware Image Status property. For testing and development purposes only.

LED Commands

LED commands are available on the keypad driver. For every button, status LED Current Color can be set at any time using LED Programming Commands:

  • Set LED Current: Sets the Current Color of the status LED for a button
  • Set All LED Current: Sets the status LED Current Color for all buttons
  • Use On Color: Sets the Current Color of the status LED for a button to the On color. On color for a button is defined with the LED Behavior.
  • Use Off Color: Sets the Current Color of the status LED for a button to the Off color. Off color for a button is defined with the LED Behavior.

Current Color takes precedence over the On/Off (Push/Release) LED colors. For example, if LED Behavior is Push/Release, but Current Color is set, LED color will remain Current Color when a button is pushed and released. Similarly, if Current Color is set, and LED behavior is Follow Load or Follow Connection, status LED color will not change when connected load or other device changes state.

LED Current Color is cleared for a button with Clear LED Current. Once the Current Color is cleared, status LED will operate according to the LED behavior. LED Current Color can be cleared for all buttons using the Clear All LED Current Device specific command.

It is also possible to change On/Off (Push/Release) colors via Programming LED Commands:

  • Set LED On: Changes the On (Push) color for a button
  • Set LED Off: Changes the Off (Release) color for a button
  • Set All LED On: Changes the On (Push) color for all buttons
  • Set All LED Off: Changes the Off (Release) color for all buttons

Driver Events

TODO

Troubleshooting

Log Level – This property allows to filter which message types display in the Lua Output window. Options 0 - 5 correspond to Fatal through Trace levels, increasing in level of verbosity.   

Log Mode – Activates logging of diagnostic information. The log level is set in the above property. Options include Off, Print (to the window), Log (to the Director Log), and Print and Log (both). Default is Off

NOTE: When Log Mode is enabled (set to anything but the Off value) the driver will disable it (revert back to Off) automatically after 45 minutes. If logging is enabled from Composer Pro programming this reverting mechanism will be bypassed and it's up to the installer to disable logging manually or via Composer Pro programming.

Changelog

  • v67

    • Light: [DRIV-12858] Fix driver not behaving as switch when "Switch Mode - High Wattage LED" is selected

  • v66

    • tests: Add test for validating FSC preset speed when added
    • Keypad Zigbee: [DRIV-12169] Don't send FactoryRestore on project restore
    • Documentation updates for the release (#40)
    • [DRIV-12782] Fix spelling mistake in dimming mode description
    • Fan: [DRIV-12827] Make Medium-High the default preset
    • CRC: Add sync function for AutoOffTime
    • react: [DRIV-11827] Add tooltip to AL Apply To button
    • react: Add confirmation dialog when applying AL settings
    • Ambient: Update validation to use bright/dark hysteresis values
    • react: Change Transition Level Tolerance Validation
    • react: [DRIV-11979] Restore values when AL Customization dialog is closed

  • v65

    • Ambient: [DRIV-12598] Allow all Followers to be unbound at once
    • CDSW: Fix for adding Light devices in order
    • Create Ambient Light runtime configuration check
    • Actions: Add Factory Restore and Reboot
    • Actions: Remove deprecated actions
    • Keypad: [DRIV-10506] Disable backlight when blank rocker is ordered
    • [DRIV-12718] Rename Fan Speed Controller to Variable Speed Controller
    • Fix online notification for light and keypad
    • CRC: Fix reading invalid configuration

  • v64

    • Add firmware v5.21.53 (zigbee and wired)
    • Ambient: Fix property name typo
    • Zigbee Common: Read NoNeutral for selected devices
    • Ambient: [DRIV-12682] Set final button backlight configuration
    • CRC: [DRIV-12657] Fix error in FSC
    • CDSW: [DRIV-12619] Fix lights not being added when light driver is not on the controller
    • driver.xml: Remove LED commands only from LightV2 proxy
    • Ambient:[DRIV-12681] Change default Status LED levels
    • Update faults and add any fault variables
    • Faults: [DRIV-12605] Remove driver ability to clear Zero Cross fault
    • Zigbee: [DRIV-11893] Disable default responses for all command types
    • Ambient Light: [DRIV-12606] Driver fails to sync ambient light configuration

  • v63

    • Keypad Zigbee: Fix group persistence
    • Add CRC mechanism
    • Zigbee Common: Add ZigbeeDispatchAndNotifyClass
    • driver.xml: [DRIV-12547] Update xml to pass validation and add auto_update tag
    • Add firmware 5.20.57 (zigbee and wired)
    • Light: [DRIV-12321] Implement scene flashing functionality

  • v62

    • Light: [DRIV-12472] Move group initialization to OnDriverInit
    • Light: [DRIV-12182] Remove button events from light part of the driver
    • Ambient: Recheck source EUID when Ambient configuration is sent to the device
    • Ambient: Add new values for invalid Source EUID and group id
    • Groups: Fix group id no being indexable (requires drivers be re-added to Load Groups)
    • Faults: Stop reading NoNeutral attribute for non-dimmer devices
    • Fan: [DRIV-12330] Add default engravings when FSC is added to project
    • keypad_template: Allow engraving to be passed when creating a new button
    • Zigbee: Clear queue when device goes offline
    • Zigbee: [DRIV-12381] Fix configuration not picked up on online event

  • v61

    • Add firmware v5.19.0 (zigbee and wired)

  • v60

    • Add firmware v5.18.47 (zigbee and wired)

  • v59

    • LightScenes: Add ability to exclude scene from scene ramping
    • Switch from AddGroup to C4AddGroup command
    • [DRIV-12001] Allow Log Mode and Log Level to be set from Composer Programming
    • Light: [DRIV-12041] Add Switch Mode - High Wattage LED dimming mode (UDIM and KDS only)
    • keypad_template: [DRIV-12235] Add support for blank keypad buttons
    • driver.xml: [DRIV-12046] Set max ramp rate to 86400 seconds

  • v58

    • ZigbeeSyncLoopClass: Jitter sync timer from 1 to 300s
    • Add ZCL queue implementation

  • v57

    • [DRIV-12166] Update Backlight color values
    • Add firmware v5.18.44 (zigbee and wired)
    • Light: Fix not getting configuration on dimmer devices
    • Light: Start/Stop sending messages when light goes online/offline
    • Keypad Zigbee: [DRIV-11983] Stop reading LCP related attributes on KC
    • Keypad Zigbee: Don't send button layout for rocker devices
    • Set sync loop timeout to 10 minutes (with 1-60s jitter) and recheck every 6 hours
    • Remove getting device state when driver reloads
    • ZigbeeSyncBaseClass: Force a recheck if sync commands fails or timeouts
    • Move BootCause parsing to single point of entry
    • Keypad Zigbee: Fix ButtonLayout sync
    • Zigbee Common: Add sync for BootCause
    • ZigbeeSceneSyncClass: Preform ALS action count check before getting scene data
    • Keypad Zigbee: Don't clear Service Tag when it is read again
    • [DRIV-12130] Mark that adding a group is needed when force-syncing in case we remove a group and don't get notified

  • v56

    • Add firmware v5.18.40 (zigbee and wired)

  • v55

    • Add firmware v5.18.37 (zigbee and wired)
    • Keypad Common: [DRIV-11924] Handle Aux Keypad not being connected (#37)
    • Zigbee: Stop sending to offline nodes
    • Keypad Zigbee: [DRIV-11951] Rebind AL followers when source is reset to defaults
    • Keypad Zigbee: [DRIV-11952] Set groupId and Source LID to all zeros when AL mode is Independent

  • v54

    -Aux Keypads: [DRIV-11940] Add engraving_slot_type -driver.xml: [DRIV-11943] Update minimum_os_version to 4.0.0 -ZigbeeSyncLoopClass: Log sync state when check is performed -ZigbeeSyncBaseClass: Send error message to metrics and ignore transition states -ZigbeeCommandSyncClass: Log response error more verbose -Add global switches for enabling/disabling DefaultResponseCommands from being requested -Deprecate RetryCommands class -[DRIV-11851][DRIV-11852] Remove Wiring Mode property from DDS Keypad and Non-Dimmable Light driver -Relay: [DRIV-11853] Add RELAY binding for external control -Fan: [DRIV-11832] Implement Online notification for ALS (Device reboot required)

  • v53

    • Fan: Disable auto feedback
    • [DRIV-11718] Add Dimming Curves to 10V dimmer and update Dimming Curve values
    • [DRIV-11776] Allow setting Backlight Color Temperature from Composer Programming
    • [DRIV-11406] Add ALS support to Fan Speed Controller
    • Add firmware 5.14.80 (zigbee) and 5.14.74 (wired)

  • v52

    • [DRIV-11415] Wired Keypad: Add reboot handlers for various reported reboot causes
    • Ambient: Fix ambient slider
    • [DRIV-11445] Wired Keypad: Add bootloader info

  • v51

    • [DRIV-10417] Add ST Number to Zigbee driver properties

  • v50

    • Add firmware 5.13.54 (zigbee and wired)
    • [DRIV-11643] Implement FSW Pulse using AutoOff command
    • Light: Fix SceneSyncList not being initialized
    • Keypad Zigbee: Fix SystemEvents handler firing on wrong event
    • Keypad Zigbee: [DRIV-11552] Query firmware versions 1min after getting back online
    • control4_lux_fireplace_switch: [DRIV-11541][DRIV-11542] Add supports_invert (False) and supports_invert capability (False)
    • Light: Fix response commands not getting SUCCESS when getting device configuration (scenes)

  • v49

    • [DRIV-11347] Update default Ambient Light settings
    • Zigbee Common: Add metrics to ZigbeeSyncLoopClass:SetState
    • Keypad Common: Execute OnButtonInfoBound only when class is initialized
    • Remove ability to set Transition Level Tolerance (aka hysteresis) values
    • Zigbee Common: Reset last sync timer when starting check or sync
    • Add firmware 5.12.98 (zigbee and wired)
    • [DRIV-11502] Change dimming curve name and descriptions
    • Zigbee Common: Stop sync when a check command return a default response other then SUCCESS
    • Light: Fix scenes not syncing when CLEAR_ALL_SCENES is called
    • react: [DRIV-11460] Hide LCP values for devices that don't have it
    • react: [DRIV-11416] Display only Current Ambient Level
    • Zigbee Common: [DRIV-10947] Change Faults timestamp to US format (m/d/y)
    • Handle status field being added to C4 specific response commands
    • Light: [DRIV-11425] Immediately notify ALS of expected light state on scene activation
    • Add Load Group support to lights with keypads

  • v48

    • Add firmware 5.10.131 (ZigBee and wired)
    • Deprecated C4EnhancedAddScene in favor of EnhancedAddScene
    • Show progress while detecting dimming mode
    • Added Ambient Light Mode UI section for easier configuration
    • Added Apply to functionality for Ambient Light settings
    • Backlight Color Temperature configuration added
    • [DRIV-10927] Fix follower not unbinding when its AL mode is disabled

  • v47

    • control4_lux_fan_speed_controller: Fix Control Load not showing in the Up/Down behaviors
    • control4_lux_keypad_dimmer_switch: Fix Control Load not showing in the Up/Down behaviors
    • react: Remove Fan Preset Level from HTML page
    • [DRIV-11018] react: Remove Fan color picker from HTML page
    • [DRIV-11141] keypad_template: Fix Up/Down buttons stop working after Director restart
    • [DRIV-11020] Keypad Common: Enable/Disable Status and/or Backlight LEDs from Programming
    • [DRIV-10772] Wired Keypad: Send button layout to device
    • [DRIV-10541] react: Add refresh button for current ambient level. Make ambient slider more responsive.
    • [DRIV-10959] react: Fix displayed ambient current level based on ambient mode.

  • v46

    • [DRIV-11090] Check last set OnLevel attribute instead of the preset level stored in the template code
    • [DRIV-11062] Allow only Forward Phase option for UDIM, KDS and CDSW when wired without a neutral
    • [DRIV-10971] Add Wiring Mode to UDIM, KDS and CDSW drivers
    • [DRIV-11020] Keypad Common: Add enable/disable the Ambient Light feature to programming
    • [DRIV-11089] Light: Change default Brightness On mode to Preset (Default On)
    • [DRIV-11095] Add firmware v5.8.304 (zigbee and wired)
    • [DRIV-11030] Document dimming modes and add tooltips in HTML page
    • [DRIV-10730] Send button layout to device
    • [DRIV-10878] Clear faults when ZigBee device is unbound from the driver
    • [DRIV-10810] Auxiliary keypad: Added engraving only auxiliary keypad

  • v45

    • Add firmware 5.7.96 (zigbee and wired)
    • [DRIV-11016] Consolidate 0-10V dimming mode names with those for Gen3 and Centralized Lighting
    • [DRIV-10975] Lux - remove "Incandescent" from the label used for Forward Phase
    • [DRIV-10432] Identification animation too slow
    • Light: Fix scenes table not getting initialized
    • Zigbee Common: Disable Zigbee retry mechanism
    • Add Zigbee sync for all Attributes, Commands and Scenes
    • General: Make pcall wrapper and send errors to c4metrics

  • v44

    • [DRIV-10730] Send button layout do device
    • [DRIV-10775] Rename secondary (keypad) proxy when primary (load) proxy is renamed
    • Add firmware 5.7.90 (zigbee and wired)
    • Keypad Wired: [DRIV-10855] Fix Control-Control behavior for clicks over binding connections

  • v43

    • [DRIV-10809] Rename Combo Dimmer Switch driver to Dual Dimmer Switch Keypad
    • Added firmware 5.7.81 (zigbee and wired)
    • Fix LUA error when removing Up/Down buttons
    • [DRIV-10731] Docs and react: Remove Dimming Curve note
    • [DRIV-10752] Docs: Add Lux mesh not in System Requirements

  • v42

    • Add Lux Auxiliary Keypad driver
    • Light: Fix RemoveAllScenes error when driver initializes
    • General: Fix JSON dev variables being too big to load
    • Keypad Zigbee: [DRIV-10161] Send country code to device
    • Keypad Common: [DRIV-10618] Programmed color not cleared on Control-Control UI
    • Light: [DRIV-10584] LUX default click rates should match Gen3
    • Keypad Zigbee: [DRIV-9601] Do a factory reset of a device when a project is loaded

  • v41

    • tests: Fix typo in test_zigbee_retry
    • Keypad Zigbee: [DRIV-10234] Toggle LED colors for ButtPress commands when LED behavior is Push/Release
    • Light: Just return when brightness preset gets deleted
    • Keypad Zigbee: Initialize FaultCommander for the ConfigurableKeypad
    • react: Adapt Faults to be SKU specific
    • Zigbee Common: Add Faults that can be reset to FaultCommander
    • Zigbee Common: Hide MOSFET fault on 2nd channel
    • Doc: Show only faults that apply to that SKU
    • Show and allow reset of device specific faults
    • Light: [DRIV-10663] Fix scenes not getting applied to switches
    • Light: Make Dimming Modes static
    • Add renamed nesting capabilities

  • v40

    • Internal Beta Release Candidate