To create a device in your plug-in, you can use the same hs commands that you use in scripts. However, to create an I/O device which is typically owned by a plug-in, then there are some special commands you would use to accomplish this.
First, if you do not already have a house code for use with your plug-in devices, call GetNextFreeIOCode to obtain it.
Create at least one device so HomeSeer does not assign the house code to another plug-in.
When you create your device(s), keep the following in mind:
Using an IO house code helps to make sure the user cannot change the house code using the HomeSeer UI.
Use the undocumented (in the public DeviceClass documentation) IOMISC string property of a device to hold information about the device specific to your plug-in. If the device is user created, created by another plug-in, or a shared device, do not use IOMISC as you may overwrite another application's information. If the device is to be owned by your plug-in, you can use IOMISC to put information about the device right in the device itself, thus (as an example of a good use) the user can completely change the name, location, or location2 properties and you can still find the device.
At startup, get a DeviceEnumerator object and process all of the devices in the system.
Examine the device, and if the interface property is set to the name of your plug-in, then examine the IOMISC property to determine the type of device it is for your plug-in.
When you find a device, store its device reference ID or a copy of the device object in an array or some other internal means for use in modifying the device while your plug-in is running.
Set the undocumented (in the public DeviceClass documentation) INTERFACE property to the name of your plug-in. This is how HomeSeer knows that your plug-in owns that device. When the device is controlled, and depending upon other settings, the SetIO or SetIOEx procedure in your plug-in will be called.
Set the MISC property of the device accordingly. If you are modifying an existing device to work with your plug-in, remember that MISC is an option bit property, and so modifications should be done using AND and OR logic operations.
If you do not wish to use the X-10 centric device status model built into HomeSeer with these devices, you have two other options: A) Set the device string and optionally update the device value and device last change date/time, or B) Establish device value/status pairs and then just update the device value to invoke triggers and update the displayed status.
If you do not wish to use device value/status pairs and only want some control buttons, set the buttons property of the device.
If you want to get a SetIO or SetIOEx call to your plug-in whenever the device is changed by the user or another plug-in using hs script commands, remember to logically OR the two values documented in the device class documentation of the HomeSeer help file to your device's MISC setting. Here is a copy of what is written in that help file under the MISC property of the DeviceClass:
&h4000 = This device, when its status
is changed, calls SetIO/SetIOEx in the plug-in that owns it.
&h8000 = This device, when its value is changed, should call SetIO/SetIOEx
in the plug-in that owns it.
After you receive a houscecode for your devices, you may want save this code in your INI file. When HomeSeer is restarted, you can retrieve this housecode and therefore know where your devices are located. See the sample plug-in for how this may be done. The only issue with this method is that its possible for a user to delete your INI file which will force you to re-build your devices, which may cause duplicates. Always search for your devices first to verify that they exist. Enumerate all the devices and see if any devices have the INTERFACE property set to your plugin name. An alternate method is to simply create your devices initially then search for them when HomeSeer starts. When you find the first one, you now have the housecode for all your devices. There is no need to save the housecode in this case, and you do not need to be concerned about your INI file being deleted.
If you create devices that you intend to manage
with device value/status pairs exclusively, and are not going to update
their status using hs.SetDeviceStatus commands, then you may wish to add
the MISC_NO_STATUS_TRIG property to the MISC property.
(dv.misc
= dv.misc OR MISC_NO_STATUS_TRIG)
This will prevent that device from appearing in the drop down list
of devices on the device status trigger screen, as well as prevent the
device from appearing in the list of devices for the device conditions,
which depend upon device status.
(There are other device options set by the MISC property values - See
the MISC values in HomeSeer
Constants.)