Address-Code vs PlugExtraData
Plug-In Authors: It has come to my attention that some of you are using the Address and/or Code fields to hold unique identifier information that your plug-in needs. While this is certainly NOT wrong or bad, it is also not the preferred thing to do and here is why:
1. Address and Code fields are visible to the user. The only legitimate use of the code field by a plug-in would be an X-10 plug-in, but even in that case it is not necessary. The point is, the end users writing scripts are limited to what they can see and what they can use to reference a device. Using the name is not always going to be accurate, and there is no correlation between the device reference ID and a group of devices owned by the same plug-in. So, the user's ability to use or even SET one or both of those fields is important to them being able to access devices in scripts.
2. In HS3 we have provided a super-powerful thing in the PlugExtraData property for you to store a LOT of information in the device. Once you find a device that is yours using the interface/interfaceInstance, you can get the PlugExtraData object, and then use it to see what kind of device it is for your plug-in. The PlugExtraData (PED) object has methods for adding named or unnamed objects, for accessing those objects by name or by iterating through all of the unnamed objects, and so - for example - if you wanted to store the address of something and that address was an array of numbers for example, you can store it by using PED.AddNamed("MyPlugAddress",objAddress) - and retrieving it is just as easy. If you add or change an object, you just have to remember to put the updated PED back to the device with the SET property of PlugExtraData.
Since PED is intended to be used by plug-ins and is not visible in the UI, the end user is not going to muck with it by accident.
So, set the address and code to something meaningful when you create a device, but don't depend on those fields to identify it later (with an exception to an X10 device for historical reasons more than anything). That way, the user can access the device in a script easily, and you still have a very powerful storage mechanism that can be used.
If you are more confused after reading this than before, drop me a line (I can send some example code), but I thought I would mention it in the case where somebody may just be getting started on another HS3 plug-in conversion!
1. Address and Code fields are visible to the user. The only legitimate use of the code field by a plug-in would be an X-10 plug-in, but even in that case it is not necessary. The point is, the end users writing scripts are limited to what they can see and what they can use to reference a device. Using the name is not always going to be accurate, and there is no correlation between the device reference ID and a group of devices owned by the same plug-in. So, the user's ability to use or even SET one or both of those fields is important to them being able to access devices in scripts.
2. In HS3 we have provided a super-powerful thing in the PlugExtraData property for you to store a LOT of information in the device. Once you find a device that is yours using the interface/interfaceInstance, you can get the PlugExtraData object, and then use it to see what kind of device it is for your plug-in. The PlugExtraData (PED) object has methods for adding named or unnamed objects, for accessing those objects by name or by iterating through all of the unnamed objects, and so - for example - if you wanted to store the address of something and that address was an array of numbers for example, you can store it by using PED.AddNamed("MyPlugAddress",objAddress) - and retrieving it is just as easy. If you add or change an object, you just have to remember to put the updated PED back to the device with the SET property of PlugExtraData.
Since PED is intended to be used by plug-ins and is not visible in the UI, the end user is not going to muck with it by accident.
So, set the address and code to something meaningful when you create a device, but don't depend on those fields to identify it later (with an exception to an X10 device for historical reasons more than anything). That way, the user can access the device in a script easily, and you still have a very powerful storage mechanism that can be used.
If you are more confused after reading this than before, drop me a line (I can send some example code), but I thought I would mention it in the case where somebody may just be getting started on another HS3 plug-in conversion!