Class AbstractHsDevice 

[Obfuscation(Exclude = true, ApplyToMembers = true)]
[Serializable]
public abstract class AbstractHsDevice
Inheritance
System.Object
AbstractHsDevice
HsDevice
HsFeature
Inherited Members
System.Object.ToString()
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: HomeSeer.PluginSdk.Devices
Assembly: PluginSdk.dll

The base implementation of a HomeSeer device.

Used to represent devices and features as either a HsDevice or HsFeature


Remarks

Due to the fact that both HsDevices and HsFeatures derive from this class some documentation may refer to either as a device. Be careful to ensure you know which one you are working with at all times to avoid unexpected InvalidOperationExceptions.

Constructors

View Source

AbstractHsDevice()

Create a new AbstractHsDevice with default properties

Declaration
protected AbstractHsDevice()
View Source

AbstractHsDevice(Int32)

Create a new AbstractHsDevice with a specific uniqueRef

Declaration
protected AbstractHsDevice(int uniqueRef)
Parameters
Type Name Description
System.Int32 uniqueRef

The unique ID as an integer

Fields

View Source

_address

Declaration
protected string _address
Field Value
Type Description
System.String
View Source

_assDevices

Declaration
protected HashSet<int> _assDevices
Field Value
Type Description
System.Collections.Generic.HashSet<System.Int32>
View Source

_cacheChanges

Flag used to indicate whether to cache changes in Changes when setting properties and not adjust the underlying value or to cache changes in Changes and adjust the underlying value.

Declaration
protected bool _cacheChanges
Field Value
Type Description
System.Boolean
Remarks

Setting this to TRUE allows you to quickly revert changes made by discarding Changes

View Source

_displayedStatus

Declaration
protected string _displayedStatus
Field Value
Type Description
System.String
View Source

_image

Declaration
protected string _image
Field Value
Type Description
System.String
View Source

_interface

Declaration
protected string _interface
Field Value
Type Description
System.String
View Source

_invalidValue

Declaration
protected bool _invalidValue
Field Value
Type Description
System.Boolean
View Source

_lastChange

Declaration
protected DateTime _lastChange
Field Value
Type Description
System.DateTime
View Source

_location

Declaration
protected string _location
Field Value
Type Description
System.String
View Source

_location2

Declaration
protected string _location2
Field Value
Type Description
System.String
View Source

_misc

Declaration
protected uint _misc
Field Value
Type Description
System.UInt32
View Source

_name

Declaration
protected string _name
Field Value
Type Description
System.String
View Source

_plugExtraData

Declaration
protected PlugExtraData _plugExtraData
Field Value
Type Description
PlugExtraData
View Source

_relationship

Declaration
protected ERelationship _relationship
Field Value
Type Description
ERelationship
View Source

_status

Declaration
protected string _status
Field Value
Type Description
System.String
View Source

_statusString

Declaration
protected string _statusString
Field Value
Type Description
System.String
View Source

_typeInfo

Declaration
protected TypeInfo _typeInfo
Field Value
Type Description
TypeInfo
View Source

_userAccess

Declaration
protected string _userAccess
Field Value
Type Description
System.String
View Source

_userNote

Declaration
protected string _userNote
Field Value
Type Description
System.String
View Source

_value

Declaration
protected double _value
Field Value
Type Description
System.Double
View Source

_version

Declaration
protected double _version
Field Value
Type Description
System.Double
View Source

_voiceCommand

Declaration
protected string _voiceCommand
Field Value
Type Description
System.String

Properties

View Source

Address

A physical address for the device/feature.

Use this to store a unique identifier for the physical device this device/feature is associated with.

Declaration
public string Address { get; set; }
Property Value
Type Description
System.String
Remarks

Since v1.2.5.0, this field is overloaded with the legacy Code field for backwards compatibility. If you are accessing a device/feature that was created using this API then you can safely ignore this remark. If you are accessing a device/feature that was created using the HS3 legacy API you may note that this field now includes the Code value if it exists. You can get the Code directly by using the Code field.

This table shows the return value of Address based on the value stored in the HS database.

Address ValueReturns
Address OnlyAddress
Code OnlyCode
Address and CodeAddress-Code

You can use GetAddressFromAddressString(String) and GetCodeFromAddressString(String) to pull the address and code, respectively, from this value.

View Source

AssociatedDevices

A set of unique IDs that represent the devices/features that are associated with this device/feature

Declaration
public HashSet<int> AssociatedDevices { get; set; }
Property Value
Type Description
System.Collections.Generic.HashSet<System.Int32>
View Source

Changes

A collection of changes to the device/feature since its initialization

Declaration
public Dictionary<EProperty, object> Changes { get; }
Property Value
Type Description
System.Collections.Generic.Dictionary<EProperty, System.Object>
Remarks

This acts as a local cache and makes it easier to change multiple things about a device/feature and then send all of the changes to HomeSeer as a bundle via UpdateDeviceByRef(Int32, Dictionary<EProperty, Object>) or UpdateFeatureByRef(Int32, Dictionary<EProperty, Object>)

View Source

Code

Get the code stored in the Address string.

Declaration
public string Code { get; }
Property Value
Type Description
System.String
Remarks

This field is only used for legacy support and grabs a value from the Address field directly. The code is grabbed from the Address field by using GetCodeFromAddressString(String)

View Source

DisplayedStatus

The current status of the device/feature

This is the exact string that users see in the UI

Declaration
public string DisplayedStatus { get; set; }
Property Value
Type Description
System.String
See Also
View Source

Image

The address of an image that represents the current status of the device/feature

Declaration
public string Image { get; set; }
Property Value
Type Description
System.String
View Source

Interface

The ID of the interface that is responsible for processing interactions with this device/feature

Declaration
public string Interface { get; set; }
Property Value
Type Description
System.String
View Source

IsValueInvalid

Whether the device/feature is in an invalid state and should display as such to users.

Declaration
public bool IsValueInvalid { get; set; }
Property Value
Type Description
System.Boolean
Remarks

Use this as a manual way to flag the device/feature as invalid when the automatic check through IsValueValid() will not produce the desired result. Setting this to TRUE will force the device/feature's state to invalid.

View Source

LastChange

The date and time that this device/feature was last updated or changed

Declaration
public DateTime LastChange { get; set; }
Property Value
Type Description
System.DateTime
View Source

Location

The primary location of the device/feature according to the locations configured on the user's system

Declaration
public string Location { get; set; }
Property Value
Type Description
System.String
Remarks

Do not set this directly on features. It will be ignored/overwritten in favor of the location set on the owning device.

To optimize the user experience, it is recommended to ask the user which location they wish to assign to a device before finishing the inclusion process.

View Source

Location2

The secondary location of the device/feature according to the locations configured on the user's system

Declaration
public string Location2 { get; set; }
Property Value
Type Description
System.String
Remarks

Do not set this directly on features. It will be ignored/overwritten in favor of the location2 set on the owning device.

To optimize the user experience, it is recommended to ask the user which location they wish to assign to a device before finishing the inclusion process.

View Source

Misc

A collection of bit flags used to represent various configuration options for a device/feature.

It is not recommended to set this directly. Instead, use AddMiscFlag(EMiscFlag), RemoveMiscFlag(EMiscFlag), and ContainsMiscFlag(EMiscFlag) to interface with this property

Declaration
public uint Misc { get; set; }
Property Value
Type Description
System.UInt32
See Also
View Source

Name

The name of the device/feature

Declaration
public string Name { get; set; }
Property Value
Type Description
System.String
Remarks

To optimize the user experience, it is recommended to ask the user what name they wish to assign to the device before finishing the inclusion process.

View Source

PlugExtraData

A memory space available for plugins to store keyed and non-keyed data associated with the device/feature

Declaration
public PlugExtraData PlugExtraData { get; set; }
Property Value
Type Description
PlugExtraData
Remarks

Use this to store device/feature specific configuration options accessed via the DeviceConfig page

See Also
View Source

Ref

The unique identifier for this device/feature. This is the primary key for devices and features in HomeSeer.

Declaration
public int Ref { get; }
Property Value
Type Description
System.Int32
View Source

Relationship

The type of relationship this device/feature has with other devices/features. See ERelationship for valid types and more details.

Declaration
public ERelationship Relationship { get; set; }
Property Value
Type Description
ERelationship
Exceptions
Type Condition
DeviceRelationshipException

Thrown when setting the relationship while there are listed devices/features still associated with this device/feature
View Source

Status

The current status of the device/feature. (incorrect - the raw, unformatted status string)

WARNING - This property is being replaced by StatusString and DisplayedStatus

Declaration
[Obsolete("This property is being replaced by StatusString and DisplayedStatus", false)]
public string Status { get; set; }
Property Value
Type Description
System.String
View Source

StatusString

The raw, unformatted status of the device/feature.

This is combined with a string returned from a StatusGraphic or StatusControl that matches the current Value to produce the DisplayedStatus

Declaration
public string StatusString { get; set; }
Property Value
Type Description
System.String
View Source

TypeInfo

Type info for this device/feature

Declaration
public TypeInfo TypeInfo { get; set; }
Property Value
Type Description
TypeInfo
Remarks

This is used to describe this device/feature in a manner that is easily understood by UI generation engines and other smart home platforms. When these systems can understand what this device/feature is, they are better able to tailor the experience of the user to their expectations.

See Also
View Source

UserAccess

A string representation of the HomeSeer user access rights for this device/feature

Declaration
public string UserAccess { get; set; }
Property Value
Type Description
System.String
Remarks

This is typically configured by users and can be safely ignored when creating a HsDevice or HsFeature

View Source

UserNote

Notes attached to this device/feature by users

Declaration
public string UserNote { get; set; }
Property Value
Type Description
System.String
Remarks

This is typically configured by users and can be safely ignored when creating a HsDevice or HsFeature

View Source

Value

A numeric value representing the current state of the device/feature.

Declaration
public double Value { get; set; }
Property Value
Type Description
System.Double
Remarks

Although this is available on devices it should not be set directly. This should only be set on features; as the information of the identified primary feature will be automatically pushed to the device to better adhere to user experience expectations.

This value relates to the TargetValue and TargetRange properties on the StatusControl and StatusGraphic classes.

View Source

Version

The version of the internal structure used in HomeSeer Core to represent this device/feature

Declaration
public double Version { get; set; }
Property Value
Type Description
System.Double
Remarks

When loading a device/feature created by a legacy plugin this property is less than or equal to 3.2. When loading a device/feature created by a plugin using this SDK, this property is equal to 4.0

To migrate a device/feature created by a legacy plugin, first clear all its attached StatusControl and StatusGraphic using ClearStatusControlsByRef(Int32) and ClearStatusGraphicsByRef(Int32), for features only recreate some new StatusControl and StatusGraphic using methods such as AddStatusControlToFeature(Int32, StatusControl) and AddStatusGraphicToFeature(Int32, StatusGraphic), then set the Version property to 4.0.

View Source

VoiceCommand

A voice friendly command string used to identify this device/feature

Declaration
public string VoiceCommand { get; set; }
Property Value
Type Description
System.String

Methods

View Source

AddMiscFlag(EMiscFlag)

Add the specified EMiscFlag to the device/feature

Declaration
public void AddMiscFlag(EMiscFlag misc)
Parameters
Type Name Description
EMiscFlag misc

The EMiscFlag to add
View Source

ClearMiscFlags()

Clear all EMiscFlags on the device/feature.

Declaration
public void ClearMiscFlags()
View Source

ContainsMiscFlag(EMiscFlag)

Determine if the device/feature contains the specified EMiscFlag

Declaration
public bool ContainsMiscFlag(EMiscFlag misc)
Parameters
Type Name Description
EMiscFlag misc

The EMiscFlag to look for
Returns
Type Description
System.Boolean

TRUE if the device/feature contains the EMiscFlag, FALSE if it does not.
View Source

GetAddressFromAddressString(String)

Get the address from an address-code string.

Declaration
public static string GetAddressFromAddressString(string addressString)
Parameters
Type Name Description
System.String addressString

The Address-Code value string to parse
Returns
Type Description
System.String

The Address value from the string
Remarks

HS3 supported an Address and Code field, but the Code field has been deprecated. The Address and Code fields used to also be combined into a single string with the format of ${ADDRESS}-${CODE}. The pseudocode for this is "${ADDRESS}-${CODE}".Trim('-'); To maintain backwards compatibility support, the Address field will be overloaded with the Code for devices created using HS3. Use this method to get the address from the returned address-code string.

View Source

GetCodeFromAddressString(String)

Get the code from an address-code string.

Declaration
public static string GetCodeFromAddressString(string addressString)
Parameters
Type Name Description
System.String addressString

The Address-Code value string to parse
Returns
Type Description
System.String

The Code value from the string
Remarks

HS3 supported an Address and Code field, but the Code field has been deprecated. The Address and Code fields used to also be combined into a single string with the format of ${ADDRESS}-${CODE}. The pseudocode for this is "${ADDRESS}-${CODE}".Trim('-'); To maintain backwards compatibility support, the Address field will be overloaded with the Code for devices created using HS3. Use this method to get the address from the returned address-code string.

View Source

GetMiscForFlags(EMiscFlag[])

Get the value for any combination of EMiscFlags

Declaration
public static uint GetMiscForFlags(params EMiscFlag[] misc)
Parameters
Type Name Description
EMiscFlag[] misc

EMiscFlags to combine
Returns
Type Description
System.UInt32

A uint representing the combined EMiscFlags
View Source

IsValueValid()

Determine whether the current value is valid.

Declaration
protected virtual bool IsValueValid()
Returns
Type Description
System.Boolean

Always TRUE when not overriden
View Source

RemoveMiscFlag(EMiscFlag)

Remove the specified EMiscFlag from the device/feature

Declaration
public void RemoveMiscFlag(EMiscFlag misc)
Parameters
Type Name Description
EMiscFlag misc

The EMiscFlag to remove
View Source

RevertChanges()

Clear all changes since initialization and reset the Changes property

Declaration
public void RevertChanges()