Click or drag to resize

HzDimEx Class

The Wireless Horizon Ligthing Dimmer that has 5 individual backlight rows, a total of 10 buttons that can host a number of different keypad combos and control of a single dimmable lighting load.

This class will trigger the LoadStateChange and BaseEvent events.

Inheritance Hierarchy

Namespace: Crestron.SimplSharpPro.Lighting.Horizon
Assembly: Crestron.SimplSharpPro.Lighting (in Crestron.SimplSharpPro.Lighting.dll) Version: 2.21.121
Syntax
C#
public sealed class HzDimEx : HzDimExBase

The HzDimEx type exposes the following members.

Constructors
 NameDescription
Public methodHzDimEx Constructor for a new Horizon EX Lighting Dimmer
Top
Properties
 NameDescription
Public propertyAuxKeypad Property to return an object of Auxiliary keypad.

This requires device firmware version 2.000.0050 or greater


(Inherited from HzDimExBase)
Public propertyBacklightLedSettings Backlight LED Settings present on this device.

This property will trigger BaseEvent with event IDs defined in HzKpBase.


(Inherited from HzDimBase)
Public propertyButton Collection of buttons supported by the device.
(Inherited from AdvDimmer)
Public propertyConnectedIpList A property containing the list of the ConnectedIpInformation objects which contain information about the devices that are connected to this IP ID. This property is only valid for an ethernet device. If this is not an ethernet device, then this property will return null. If this is an ethernet device, the list will be non-null. It will be empty if no devices are connected. The order of items in this list is not guaranteed.
(Inherited from GenericDevice)
Public propertyDefeatLocalButtonLogic When set to 'false', the device will control the local load. If set to 'true', the device will operate the buttons only as a remote logic (send button state information only).
(Inherited from HzDimBase)
Public propertyCode exampleDescription Get/Set the description of this device.
(Inherited from GenericBase)
Public propertyDimmingLoads Collection of Dimmable load for this device.
(Inherited from Dimmer)
Public propertyDisposed Property to indicate if the device has been disposed.
(Inherited from GenericDevice)
Public propertyFeedbacks Property to get the collection of feedbacks with on and active indicators on HzDimBase.
(Inherited from HzDimBase)
Public propertyID Property to get the ID of the device.
(Inherited from GenericDevice)
Public propertyIsOnline Property to get the current online state of the device.
(Inherited from GenericDevice)
Public propertyLedBacklightEnabledFeedback Property to indicate the current LED Backlight status set by the EnableLedBacklight or DisableLedBacklight methods. true = LEDs enabled, false = LEDs disabled

This property will trigger BaseEvent with event id LedBacklightEnabledEventId.


(Inherited from HzDimBase)
Public propertyName Get the name of this device.
(Inherited from GenericBase)
Public propertyParameterActiveFeedbackBlinkRate Parameter to define the fade blink rate time between the LED On color and LED Off color. Value in seconds (units of 0.01 sec precision) for the blink/fade period of the LEDs when they are in active feedback state. Valid range is from 0.1 to 2 seconds. 1 second is represented as 100. Default value is 0.75 seconds. Use the SecondsToUshort(Single) to convert the seconds to a ushort value or the UshortToSeconds(UInt16) to convert the ushort value to seconds.
(Inherited from HzDimBase)
Public propertyParameterAlternateColorTheme Parameter to select the color theme that is applied to the particular Button Feedback as set by the corresponding ButtonAlternateFeedback (true = Use Alternate Color Theme; false = Use Local Color Theme). If Custom is chosen, then the corresponding RedOrHue, GreenOrSaturation and BlueOrValue properties will get processed instead of preset internal color themes that match much of the defined 'local' color themes. Refer HzKpBaseeLedAlternateColorTheme enum for valid values.
(Inherited from HzDimBase)
Public propertyParameterCustomColorInputType Selects whether the properties in LedDayOnSettings/ LedDayOffSettings/ LedNightOnSettings/ LedNightOffSettings are to be processed as RGB (Red/Green/Blue) or HSV (Hue/Saturation/Value) component values. Refer HzKpBaseeCustomColorInputType enum for valid values.
(Inherited from HzDimBase)
Public propertyParameterDayNightThresholdSetting Indicates which internal setting to use when device is automatically configured to switch between day and night mode based on sensor reading. Default (0) indicates it uses either the factory default threshold setting or the manually calibrated setting if it was saved at least once. Other preset selections are estimated values based on a typical room brightness setting. Valid values are from 0 to 5. Refer HzKpBaseeDayNightThresholdSetting enum for valid values.
(Inherited from HzDimBase)
Public propertyParameterDoubleTapSpeed Returns and sets the time between the end of the first tap and the start of the second tap for a "DoubleTap" to be recognized. Use the SecondsToUshort(Single) to convert the seconds to a ushort value or the UshortToSeconds(UInt16) to convert the ushort value to seconds. Valid range is from 0.2 seconds to 1.0 seconds. 1 second is represented as 100.
(Inherited from HzDimBase)
Public propertyParameterFakeFeedback Parameter to set and get the Fake Feedback state. When set to true, the LED corresponding to button will fade blink between On LED color and Off LED color at the ParameterActiveFeedbackBlinkRate time, for a minimum of 2 sec, until the State or Active property value is initialized to some other state.
(Inherited from HzDimBase)
Public propertyParameterHoldTime Time value in seconds. A press longer than this value triggers a Hold event. A press shorter than this value triggers a Tap or DoubleTap event. Use the SecondsToUshort(Single) to convert the seconds to a ushort value or the UshortToSeconds(UInt16) to convert the ushort value to seconds. Valid range is from 0.2 seconds to 1.0 seconds. 1 second is represented as 100.
(Inherited from HzDimBase)
Public propertyParameterIsLargeRockerButtonInstalled Returns and sets the setting that tells the keypad if a large rocker button is installed false – LEDs on row 2 and 4 are enabled true – LEDs on row 2 and 4 are disabled

This parameter requires device firmware version 2.000.0050 or greater


(Inherited from HzDimBase)
Public propertyParameterLocalButton Parameter to specify which button combination/mode this device is set to. This device does not support None.
(Inherited from HzDimBase)
Public propertyParameterLocalButtonActiveFeedback Parameter to define the behavior of the LED(s) when a local button is pressed to turn on or off a load. LED(s) can either flash, enable, or do nothing, disable. The timing of the blink is set by ParameterActiveFeedbackBlinkRate.

For quick ramps to the preset level or 100% which take place within a second, the LED will flash at least one transition and end up at on or off state. For a manual raise/lower operation where the button is held down, it will continue to flash while the button is held down, but stop once the ramp is completed and ended at the target level.


(Inherited from HzDimBase)
Public propertyParameterLocalButtonStatusFeedback Parameter to define what LED(s) are turned on when the load is on (level above zero percent) or off.
(Inherited from HzDimBase)
Public propertyParameterLocalOnLevel Paramter defines what the local 'on' level setting should be when a 'local' button defined to control the load is triggered.

Valid values range from 1% to 100%. Default value is 100%.

Use PercentToUshort(Single) to convert the percentage to a ushort value or UshortToPercent(UInt16) to convert the ushort value to percentage.
(Inherited from HzDimBase)
Public propertyParameterOffFadeTime Sets the time that it takes to ramp the light level from its current level to 0% when FullOff is used.

Field is in hundredths of a second where 25 is 0.25s.

Valid values range from 0.25s to 30s. Default value is 1 second (100 hundredths of a second).

Use SecondsToUshort(Single) to convert the time to a ushort value or the UshortToSeconds(UInt16) to convert the ushort value to seconds.


(Inherited from HzDimBase)
Public propertyParameterOnFadeTime Sets the time that it takes to ramp the light level from its current level to 100% when FullOn is used.

Field is in hundredths of a second where 25 is 0.25s.

Valid values range from 0.25s to 30s. Default value is 1 second (100 hundredths of a second).

Use SecondsToUshort(Single) to convert the time to a ushort value or the UshortToSeconds(UInt16) to convert the ushort value to seconds.


(Inherited from HzDimBase)
Public propertyParameterRaiseLowerRate Sets the time that it takes to ramp the light level from 0% to 100% (or vice versa) in raise/lower operations.

Field is in hundredths of a second where 25 is 0.25s.

Valid values range from 1 second to 10 seconds. Default value is 3 seconds (300 hundredths of a second).

Use SecondsToUshort(Single) to convert the time to a ushort value or the UshortToSeconds(UInt16) to convert the ushort value to seconds.


(Inherited from HzDimBase)
Public propertyParameterSuppressFeedbackMode Parameter that defines how the SuppressFeedback property will operate when set to 'true'. It may hold of all feedback and only send the latest snapshot when a button is released, or always send with a predetermined delay.
(Inherited from HzDimBase)
Public propertyParameterWaitForDoubleTap Returns and sets the setting that determines whether a "Tap" should be sent immediately. false – Tap is reported at the end of every short press, DoubleTap is reported at the end of the second short press. true – Tap reporting is postponed to see if a second tap comes in. In this case only DoubleTap is reported.
(Inherited from HzDimBase)
Public propertyParameterZeroCrossSyncOnOffThreshold Set something magical

Valid values range from 0% to 100%. Default of 15%. Defines the threshold for the light level of the dimmer where it will switch to either Full On or Off when the zero cross symc is lost due to noise on the AC line.

Use PercentToUshort(Single) to convert the percentage to a ushort value or UshortToPercent(UInt16) to convert the ushort value to percentage.


(Inherited from HzDimExBase)
Public propertyParent The parent that a given object was added to.
(Inherited from GenericBase)
Public propertyRegisterable Property to indicate that this device can be registered.
(Inherited from GenericDevice)
Public propertyRegistered Property to get the current registration state of the device.
(Inherited from GenericDevice)
Public propertyRegistrationFailureReason Property to get the Registration Failure Reason, this will match the return value from the call to register.
(Inherited from GenericDevice)
Protected propertySIMPLDeviceImplementation Internal protected member used for actual device control.
(Inherited from GenericDevice)
Public propertySuppressFeedback When set to 'true', the device will send button feedback information based on the ParameterSuppressFeedbackMode selected.
(Inherited from HzDimBase)
Public propertyType Property to determine to type of device this is.
(Inherited from GenericDevice)
Public propertyUnRegistrationFailureReason Property to get the Unregistration Failure Reason, this will match the return value from the call to unregister.
(Inherited from GenericDevice)
Public propertyUserSpecifiedObject Can be assigned anything that user wants.
(Inherited from GenericBase)
Protected propertyXioEndpointStubSIMPLDevice The SIMPL "stub" Device that the XiO Director creates for an endpoint to send the 1C/0E to the correct place in hierarchy.
(Inherited from GenericDevice)
Top
Methods
 NameDescription
Public methodDisableLedBacklight Method to disable all LED functionality and keeps them off.
(Inherited from HzDimBase)
Public methodDispose Clean up of resources.
(Inherited from GenericBase)
Protected methodDispose(Boolean) Method to perform the actual disposing of the device.
(Inherited from GenericDevice)
Public methodEnableLedBacklight Method to enable all LED normal functionality for all operating modes.
(Inherited from HzDimBase)
Public methodEqualsDetermines whether the specified object is equal to the current object.
(Inherited from Object)
Protected methodFinalize Destructor of the device.
(Inherited from GenericDevice)
Public methodGetHashCodeServes as the default hash function.
(Inherited from Object)
Public methodGetTypeGets the Type of the current instance.
(Inherited from Object)
Protected methodOnBaseEvent(Int32) Protected member used to fire the BaseEvent with the default extended information.
(Inherited from GenericBase)
Protected methodOnBaseEvent(Int32, UInt16) Protected member used to fine the BaseEvent with extended event information.
(Inherited from GenericBase)
Protected methodOnButtonStateChange Method to fire the button state change event.
(Inherited from AdvDimmer)
Protected methodOnLoadStateChange Method to fire the LoadStateChange event.
(Inherited from HzDimBase)
Public methodRegister Register this device with the system.
(Inherited from GenericDevice)
Public methodSendParameters This will send the parameters fields (if any) to the device. It allows the parameters to be modified and resent without unregistering and re-registering a device. It requires firmware support on the device. Not Currently implemented. This will throw a NotSupportedException
(Inherited from LightingBase)
Public methodToString Return the name of the device.
(Inherited from GenericDevice)
Public methodUnRegister Unregister this device with the system. This function can not be called from the device's own SigChange event handler.

On successful unregistration, if this device supports the OnlineStatusChange event, it will trigger indicating the device when offline.


(Inherited from GenericDevice)
Top
Events
 NameDescription
Public eventBaseEvent Generic base event, triggered when the there are no other handlers available for a specific EventID.
(Inherited from GenericBase)
Public eventButtonStateChange Event fired when a button state change was received from the device.
(Inherited from AdvDimmer)
Public eventIpInformationChange Event that tells what IP Address is connected/disconnected from an IP ID for a non-UDP device. This is only valid for an Ethernet device. An exception will be thrown if it is not.
(Inherited from GenericDevice)
Public eventLoadStateChange

Event triggered when information from a load is received.

Support for local button feedback events requires device firmware version 2.000.0050 or greater

EventIds for this event are located in the LoadEventIds class.
(Inherited from HzDimBase)
Public eventOnlineStatusChange Event triggered when the Online status of the device changes.
(Inherited from GenericDevice)
Top
Fields
 NameDescription
Public fieldDimmingLoads Collection of Dimming loads for this device.
Top
Example
Example program using the Wireless Horizon Dimmer.
C#
using Crestron.SimplSharp;                              
using Crestron.SimplSharpPro;                           
using Crestron.SimplSharpPro.DeviceSupport; 
using Crestron.SimplSharpPro.Gateways;
using Crestron.SimplSharpPro.Keypads;
using Crestron.SimplSharpPro.Lighting.Horizon;

namespace HzDimExTest
{
    public class ControlSystem : CrestronControlSystem
    {
        private HzDimEx _exHorizonDimmer;
        private CenRfgwEx _rfGateway;

        //Program constructor
        public ControlSystem()
            : base()
        {

            //Setup some console commands
            CrestronConsole.AddNewConsoleCommand(CreateDevice, "CreateDevice", "Create the Horizon Ex Switch for this program.", ConsoleAccessLevelEnum.AccessOperator);
            CrestronConsole.AddNewConsoleCommand(CycleFeedbacks, "CycleFeedbacks", "Fucntion to cycle the state of feedbacks on the Ex Switch.", ConsoleAccessLevelEnum.AccessOperator);
            CrestronConsole.AddNewConsoleCommand(CycleDayTimeCmd, "CycleDayTime", "Cycle the Ex Switch between Day/Night time modes.", ConsoleAccessLevelEnum.AccessProgrammer);
            CrestronConsole.AddNewConsoleCommand(CycleLoadsCmd, "CycleLoads", "Cycle the Dimming loads of this Ex Dimmer.", ConsoleAccessLevelEnum.AccessProgrammer);

        }

        //Command handler to call a function the change the state of the 
        private void CycleLoadsCmd(string cmdParameters)
        {
            //Cycle all the loads between on/off
            CycleDimmingLoads(_exHorizonDimmer);
        }

        //function will cycle the switched loads of the device passed in.
        private void CycleDimmingLoads(IDimmer dimmingDevice)
        {
            //Let's toggle all of the loads on this device.
            foreach (var dimLoad in dimmingDevice.DimmingLoads)
            {
                //If the load is on
                if (dimLoad.LevelFeedback.UShortValue > 0)
                {
                    dimLoad.FullOff();
                    CrestronConsole.ConsoleCommandResponse("Turning off Load {0} from device {1}.\r\n", dimLoad.Number, dimLoad.Parent);
                }
                else
                {
                    dimLoad.FullOn();
                    CrestronConsole.ConsoleCommandResponse("Turning on Load {0} from device {1}.\r\n", dimLoad.Number, dimLoad.Parent);
                }
            }
        }

        //function to cycle between Day and Night time modes for the LEDs of the keypad.
        private void CycleDayTimeCmd(string cmdParameters)
        {
            if (_exHorizonDimmer == null)
            {
                CrestronConsole.ConsoleCommandResponse("EX Switch is not initialized.\r\n");
                return;
            }

            if (_exHorizonDimmer.BacklightLedSettings.InNightTimeFeedback.BoolValue)
            {
                _exHorizonDimmer.BacklightLedSettings.EnableDayTime();
                CrestronConsole.ConsoleCommandResponse("Enable Daytime mode of the switch's keypad part.\r\n");

            }
            else
            {
                _exHorizonDimmer.BacklightLedSettings.EnableNightTime();
                CrestronConsole.ConsoleCommandResponse("Enable Nighttime mode of the keypad.\r\n");
            }
        }

        //Function to cycle the current state of the button's feedbacks. 
        private void CycleFeedbacks(string cmdParameters)
        {
            if (_exHorizonDimmer == null)
            {
                CrestronConsole.ConsoleCommandResponse("EX Switch is not initialized.\r\n");
                return;
            }

            PrintAndToggleFeedbacks(_exHorizonDimmer.Feedbacks);

        }

        private void PrintAndToggleFeedbacks<T>(CrestronCollection<T> feedbacks) where T : Feedback
        {
            //Let's start with printing all the feedbacks
            for (uint i = 0, found = 0; found < feedbacks.Count; i++)
            {
                T feedback;
                //Try get the current index
                if (feedbacks.TryGetValue(i, out feedback))
                {
                    //Success let's try the indexer 
                    var localFeedback = feedbacks[i];
                    //Toggle the state of the feedback
                    localFeedback.State = !localFeedback.State;

                    CrestronConsole.ConsoleCommandResponse("Feedback[{0}]: {1}\r\n", i, localFeedback.State);

                    //Let's see if this is an active feedback
                    var activeFeedback = localFeedback as FeedbackWithActive;
                    if (activeFeedback != null)
                    {
                        activeFeedback.Active.BoolValue = !activeFeedback.Active.BoolValue;

                        CrestronConsole.ConsoleCommandResponse("Feedback[{0}]: Active State: {1}\r\n", i, activeFeedback.Active.BoolValue);
                    }

                    found++;
                }

                if (i > 20)
                {//If we somehow got to an index of 20 let's break out ...
                    break;
                }
            }
        }

        private void CreateDevice(string cmdParameters)
        {
            if (_rfGateway != null)
            {//This means we've already create the device... I hope. 
                CrestronConsole.ConsoleCommandResponse("Device already created.");
            }

            _rfGateway = new CenRfgwEx(0x44, this);
            _exHorizonDimmer = new HzDimEx(0x30, _rfGateway);

            //Register the event handlers for the dimmer
            _exHorizonDimmer.ButtonStateChange += ButtonPressHandler;
            _exHorizonDimmer.BaseEvent += ExHorizonDimmerOnBaseEvent;
            _exHorizonDimmer.OnlineStatusChange += ExHorizonSwitchOnOnlineStatusChange;
            _exHorizonDimmer.LoadStateChange += ExHorizonDimmerOnLoadStateChange;

            //Setup how this dimmer behaves 
            _exHorizonDimmer.ParameterLocalOnLevel = SimplSharpDeviceHelper.PercentToUshort(80); //Set the local on level to 80%
            _exHorizonDimmer.ParameterOffFadeTime = 100; //take one second to fade off.
            _exHorizonDimmer.ParameterOnFadeTime = 50; //Take half a second to fade on.
            _exHorizonDimmer.ParameterRaiseLowerRate = 100; //Take 1 second for level change operations.

            //Setup some dimmer parameters for the first load
            var firstLoad = _exHorizonDimmer.DimmingLoads[1];
            firstLoad.ParameterMaxLevel = SimplSharpDeviceHelper.PercentToUshort(80); //Set the max brightness to 80%
            firstLoad.ParameterMinLevel = SimplSharpDeviceHelper.PercentToUshort(5); //Set the min brightness to 5%


            _rfGateway.Register();
        }

        private void ExHorizonDimmerOnLoadStateChange(LightingBase lightingObject, LoadEventArgs args)
        {
            var dimmingLoad = args.Load as DimmingLoad;

            if (dimmingLoad == null)
                return; //Odd

            CrestronConsole.PrintLine("Dimming Load[{0}] is now {1}", dimmingLoad.Number, (dimmingLoad.LevelFeedback.UShortValue>0) ? "On" : "Off");
        }

        private void ButtonPressHandler(GenericBase device, ButtonEventArgs args)
        {
            CrestronConsole.PrintLine("Button[{0}]'s state is: {1}", args.Button.Name, args.Button.State);
        }

        private void ExHorizonSwitchOnOnlineStatusChange(GenericBase currentDevice, OnlineOfflineEventArgs args)
        {
            //Print a message when the online state of the keypad changes.
            if (currentDevice == _exHorizonDimmer)
            {
                CrestronConsole.PrintLine("The Horizon Ex Dimmer is now : {0}", args.DeviceOnLine ? "Online" : "Offline");
            }
        }

        private void ExHorizonDimmerOnBaseEvent(GenericBase device, BaseEventArgs args)
        {
            //Need to check for some specific error cases..
            switch (args.EventId)
            {
                case (HzKpBase.LocalColorThemeFeedbackEventId):
                    CrestronConsole.PrintLine("The Dimmer's Local Color Theme has changed to : {0}", _exHorizonDimmer.BacklightLedSettings.LocalColorThemeFeedback);
                    break;
                case (HzKpBase.InDayTimeEventId):
                    if (_exHorizonDimmer.BacklightLedSettings.InDayTimeFeedback.BoolValue)
                        CrestronConsole.PrintLine("The Dimmer is now in Day time mode.");
                    break;
                case (HzKpBase.InNightTimeEventId):
                    if (_exHorizonDimmer.BacklightLedSettings.InNightTimeFeedback.BoolValue)
                        CrestronConsole.PrintLine("The Dimmer is now in Night time mode.");
                    break;
            }
        }
    }

}

Version Information

.NET

Supported in: 6.0

.NET Compact Framework

Supported in: 3.5
See Also