Custom Key Functions

If the predefined Key Functions do not offer the function required, there are four user-definable Custom Key Functions available. These can be defined in the same way as using the “Key Functions” tab with the old key units in C-Bus Toolkit.

Custom Key Functions define the 4 actions (called “Microfunctions”) to be taken on each of the 4 possible events that occur when a key is pressed.

Key Events

Every time a key is pressed, either two or three of the following events occur.

Event	Description
Just Pressed	Event occurs as soon as the key is pressed (after the debounce time). This Event occurs for every key press.
Short Release	Event occurs if the key is released before the Long Press time has elapsed. No subsequent events occur. If the key is held for longer than the Long Press time, the Short Release Event does not occur and the Long Press Event occurs instead.
Long Press	Event occurs if the key is still held when the Long Press time has elapsed.
Long Release	Event occurs when the key is released after the Long Press event has been generated.

A Key Function is defined by the combination of the 4 Microfunctions that are performed for these events.

There are 16 standard Microfunctions:

Microfunction	Description
Idle	No Event
Store1	Saves current level to Widget's Level parameter.
Dncycle	Ramps up and down at the Widget's Ramp Rate on alternate presses. First press after minimum of 15 seconds of inactivity will always ramp level down unless level is at minimum
MemTog2	Recalls last active level if off, store last active level and turn off if on.
DnKey	Ramp level to minimum (1) at the Widget's Ramp Rate
UpKey	Ramp level to maximum (255) at the Widget's Ramp Rate
Recall2	Sets the level to last active level with instant ramp.
Retrig	Starts the timer if the level of the group is non-zero. If the unit is not the Active* unit, also generates an instant ramp to the current level.
Start	Starts/retriggers the timer regardless of group state. If the device is not the active device, or if the timer is already running, also generates an instant ramp to the current level. At the expiry of the timer, the Expiry Level is set with the Expiry Ramp Rate.
RampOff	Ramps to off at the Widget's Ramp Rate, only if the group is on.
RampRecall1	Ramps to the Preset Level at the Widget's Ramp Rate
Toggle	Sends OFF if currently on, or ON if currently off.
Recall1	Sets the Level to the Widget's Preset level with instant ramp.
OnKey	Sends ON if target level is zero.
EndRamp	If currently ramping, sends instant ramp to current level. If not currently ramping, sends Terminate Ramp.
OffKey	Sends OFF if target level is non-zero.

NOTE: All microfunctions except Idle, Start, and Retrig will cancel a running timer. Therefore, when using Start or Retrig to implement a timer, these microfunctions should either be associated with one of the release events, or followed by an Idle in the corresponding release event.

For example, a standard one-key Toggle Dimmer Key Function, which toggles the state when short-pressed, and dims up or down when held down, has the following Microfunctions:

Event	Microfunction	Description
Just Pressed	Idle	When the key is first pressed, nothing happens, because we don't know yet if it will be a long press or a short press
Short Release	Toggle	If this event happens, we know it was a short press, so we want to toggle the state of the group.
Long Press	DnCycle	If this happens, we know it was a long press, so we want to start ramping. The DnCycle microfunction starts the ramp. If the group is already on and key hasn't been touched for more than 15s then we ramp down, otherwise we ramp in the opposite direction to the last time.
Long Release	EndRamp	When the key is released after the long press, we send a command to stop ramping at the current level.

Active Unit

Where multiple input units (such as key units or sensors) control the same group, the “Active” unit is simply the last unit to send a message to control that group. The “Active” unit status is used internally by the firmware to track which unit is currently running the timer in cases where there may be multiple units set to run timer functions, or also to decide which unit is responsible for status correction if required. It is not important to understand for normal functionality however it can help to understand more complex interactions between multiple units controlling a common group.