The Device Class
Overview
Use caution when working with the DeviceClass properties directly. Internally, HomeSeer will compare, for example, an address from the device class to the address provided in a script command by making both lowercase or both uppercase. When you access the DeviceClass directly, you are getting the address exactly as it was entered by the user, so one device could have an address of "Hello" while another has an address of "HeLLo".
In MOST cases of accessing a property or procedure, there is a parameter of "hs" which is the type IHSApplication. This is the hs object itself. The reason for this is for data continuity. When you access the DeviceClass from a plug-in, a COPY of the DeviceClass object is what traverses the interface to the plug-in, and the plug-in is not accessing the real object. By including the hs object, you are indicating to HomeSeer that you want the latest information (GET) or are making a change (SET) and HomeSeer uses this reference to work with the actual DeviceClass object.
Reference
Public Property Ref(ByVal hs As IHSApplication) As Integer
The Ref property holds the device's unique device reference number. The Ref should never be changed except by a plug-in or script which has first used a procedure to generate a Ref that is guaranteed to be unique in the system.
Public Property Address(ByVal hs As IHSApplication) As String
The Address is a user or plug-in assigned string that identifies the device within a logical grouping. When you GET the value of this property, it always returns the Address AND the Code separated by a hiphen. For example, if the Address were set to HELLO, and the Code were set to WORLD, retrieving the Address would result in the string "HELLO-WORLD". The Code is always set separate from the Address. This field might be used to identify the module in a machine for which there are several sub-points, and each sub-point is a different Code - as such, all of the members of the module would be given the same Address and unique Code values.
Public Property Code(ByVal hs As IHSApplication) As String
The Code is treated both separately and in combination with the Address property. Both GET and SET may be done on the Code, but when a GET is done on the Address, the string returned is in the format Address-Code, with the value in this property being the Code. For example, a Z-Wave device that is a part of the network 00AABBCC and is Node 6 might have 5 child devices, so each device would have an Address of 00AABBCC-6, but a unique Code such as Q01, Q02, Q03 such that any one of the devices may have a full address of 00AABBCC-6-Q02
Identity
The Name property holds the name of the device, such as "Light", "Lamp", or "Heater"
Public Property Location(ByVal hs As IHSApplication) As String
This is the location name of the device, such as "Family Room".
Public Property Location2(ByVal hs As IHSApplication) As String
This is a second location modifier, which may be disabled in the HomeSeer settings, or if used can be used to further qualify the location of a device such as "First Floor".
Public Property UserNote(ByVal hs As IHSApplication) As String
This property stores any information the user so chooses, and is also editable on the device management page by clicking on the note icon.
Status
Public ReadOnly Property devString(ByVal hs As IHSApplication) As String
This is the device string for the device. When this property contains a value, it can override the display of the device's normal status display which is based upon the device's value. This property may contain HTML if HTML features are desired to be used when the device is viewed on the device utility page or the status views. This property is Read Only, so script commands must be used to modify the string value such as hs.SetDeviceString
Public ReadOnly Property devValue(ByVal hs As IHSApplication) As Double
This is the device's numerical value, which can be positive or negative and may contain a decimal point. Setting the device's value can cause changes to occur or change the status of the device. This property is Read Only, as the device value needs to be changed using commands such as hs.SetDeviceValue
Public Property Last_Change(ByVal hs As IHSApplication) As Date
This is the date and time that the device's value or string was last updated. Some ways of updating the value or string may explicitly block this from being updated, but in most cases it reflects the date and time of the last change.
Public Property Attention(ByVal hs As IHSApplication) As String
This property is used to enable/disable the attention icon on a device when viewed in HomeSeer, and the text that is displayed when you hover your mouse over the attention icon. When set to a non-null value, HomeSeer will display an attention icon in the device management page and status views to alert the user that there is a message. When the mouse is over the alert icon, the contents of the message (this property) will be displayed.
Configuration
Public Property Device_Type_String(ByVal hs As IHSApplication) As String
The actual device type of a device is determined by information in the DeviceTypeInfo object (See DeviceType_Get and DeviceType_Set). This property may be used to hold a more "user friendly" device type string which is displayed on the device utility page. For example, if the device is owned by the Z-Wave plug-in, the DeviceTypeInfo object may identify it as a plug-in device type, but this property might display "Z-Wave Switch Multilevel".
Public ReadOnly Property DeviceType_Get(ByVal hs As IHSApplication) As DeviceTypeInfo
Public WriteOnly Property DeviceType_Set(ByVal hs As IHSApplication) As DeviceTypeInfo
The DeviceTypeInfo object holds several pieces of information describing the device type of the device. If the device is used with a technology API such as a Thermostat, Media, or Security, then the DeviceTypeInfo specifically identifies which part of the API the device fulfills.
Public Property Status_Support(ByVal hs As IHSApplication) As Boolean
This property indicates (when True) that the device supports the retrieval of its status on-demand through the "Poll" feature on the device utility page. The plug-in which owns the device is responsible for returning the status when the poll command is issues.
Public Property Can_Dim(ByVal hs As IHSApplication) As Boolean
This property is largely unused in HS3. When set to True and no other device value/status pairs have been assigned to the device, the default value/status pairs assigned will allow for levels/values from 1 to 99 in addition to 0 (Off) and 100 (On).
Public Property Image(ByVal hs As IHSApplication) As String
The Image property holds a path string to an image file to represent the device on the status views pages. The image path should be referenced from the root of the HTML folder under the main HomeSeer folder.
Public Property Interface(ByVal hs As IHSApplication) As String
This property holds the name of the plug-in that owns/manages this device. If the property is null or an empty string, the device is not managed by a plug-in.
Public Property InterfaceInstance(ByVal hs As IHSApplication) As String
This property holds the instance name of the plug-in that owns/manages this device. If the property is null or an empty string, either the plug-in does not support multiple instances (if the Interface property is not blank) or the device is not managed by a plug-in.
Public Property ScriptName(ByVal hs As IHSApplication) As String
Public Property ScriptFunc(ByVal hs As IHSApplication) As String
These properties are used ONLY when the Device_Type's API is set to Script, and the Device_Type's Device_Type is set to one of the script action values (See eDeviceType_Script) This provides functionality that will cause a script to be run when the device's value, string, or either are changed. ScriptName is the name of the script file to be run, and ScriptFunc is the name of a procedure in the script file to be called - if no ScriptFunc is provided, then Sub Main will be called.
When the script is run, it will be passed parameters as an object array, and those parameters are:
Parm(0) - Integer - The device reference ID.
Parm(1) - DeviceScriptChange (Integer) - Indicates what changed to cause the script to be run.
Parm(2) - Double - The device's new value.
Parm(3) - String - The device's new string.
Display
Public Property ScaleText(ByVal hs As IHSApplication) As String
A device that is used to display (for example) a temperature, the scale (Fahrenheit or Celsius) may not be known at the time the device is created or may be set/changed by an external device such that the device value/status pairs cannot be configured to display the proper scale symbol. To address this, plug-ins may update this property with the correct scale text just prior to adjusting the device's value. This property may be retrieved by other systems displaying this device's status and used in a similar manner to how it is used with the HomeSeer user interfaces.
Public Property AdditionalDisplayData(ByVal hs As IHSApplication) As String()
Similar to ScaleText, this property is used to enhance the device status display when variable elements of data are a part of the device status. For example, a Z-Wave enabled Smoke Detector may report an alarm, as well as location information. Since the variable location information cannot be assigned to value/status pairs in advance, this array of string values may be used.
Device Association
Public Sub AssociatedDevice_Add(ByVal hs As IHSApplication, ByVal dvRef As Integer)
Public ReadOnly Property AssociatedDevices_Count(ByVal hs As IHSApplication) As Integer
Public Sub AssociatedDevice_ClearAll(ByVal hs As IHSApplication)
Public ReadOnly Property AssociatedDevices(ByVal hs As IHSApplication) As Integer()
Public ReadOnly Property AssociatedDevices_List(ByVal hs As IHSApplication) As String
Public Sub AssociatedDevice_Remove(ByVal hs As IHSApplication, ByVal dvRef As Integer)
Public ReadOnly Property Parent As Enums.eRootChildStatus
Public ReadOnly Property Child As Enums.eRootChildStatus
These procedures and properties allow for getting information or making changes regarding the association of devices to one another. The typical usage is to associate one device (for example a Z-Wave Root Device) with several devices (Z-Wave Child Devices). For devices owned by plug-ins which represent technology API devices, it is strongly recommended for enumeration purposes that the single parent-multiple child relationship is used.
Associating devices should also be accompanied by the setting of the Root (Parent) device type on the parent device in a cluster of related devices. Each defined Device Type API contains a Device Type which indicates a Root device for that API, and a Device Type constant also exists to indicate a root device in the situation where there is a parent/child relationship between devices that do NOT belong to a specific technology API.
To add an association of another device to a device, use AssociatedDevice_Add. Example: dv.AssociatedDevice_Add(hs, 1234) - associates the device referenced by the device ID 1234 to the device class object dv.
To determine how many devices are associated to a device (in the device class object 'dv'), use AssociatedDevices_Count.
AssociatedDevice_ClearAll will remove all associated devices from the one which the AssociatedDevice_ClearAll procedure is called from.
AssociatedDevices and AssociatedDevices_List both return the device reference ID numbers for any devices associated with the device in which the property/procedure is called. AssociatedDevices returns an array of integers, and AssociatedDevices_List returns a comma separated string list.
AssociatedDevice_Remove will remove a single associated device reference number from the list of associated devices, which removes the association.
Relationship Status
Public Property Relationship(ByVal hs As IHSApplication) As Enums.eRelationship
The Relationship property can be used to determine or set the parent (root) or child status of a device. The return value is an Enum (eRelationshiplationship ) which can indicate whether the device is a Parent/Root (it has child devices associated with it), a Child device (it is associated with a parent device), or Standalone (it is not associated with any other device). Additionally, the return value will indicate Not Set if the device has never had one of the values set to it, or Indeterminate, which may be used by a device in the process of being created or that could be in transition from one state to another. (Indeterminate is rarely used.)
Misc Bits - Check, Clear, Set
Public Function MISC_Check(ByVal hs As IHSApplication, ByVal Misc As Enums.dvMISC) As Boolean
Public Sub MISC_Clear(ByVal hs As IHSApplication, ByVal MISC As Enums.dvMISC)
Public Sub MISC_Set(ByVal hs As IHSApplication, ByVal MISC As Enums.dvMISC)
These procedures allow you to determine if various bits in the device's MISC settings are set or not, or to make changes to those bit settings. All of these procedures are aided by the use of an Enum called dvMISC so that more friendly names may be used instead of odd numerical values. The list of dvMISC values may be viewed here.
MISC_Check is used to determine if the selected MISC bit is Set (Returns True) or not set/cleared (Returns False).
Example: If dv.MISC_Check(hs, Enums.dvMISC.NO_LOG) Then can be used to determine if the NO_LOG option was set.
MISC_Set and MISC_Clear are used to Set/Enable or Reset/Clear the indicated bit respectively.