v1.5.0.0

https://homeseer.github.io/Plugin-SDK-Docs/release_notes/pluginsdk_releasenotes_1_5_0_0.html

Summary

This release contains a small change to devices and an update to Newtonsoft. The Version property was exposed on AbstractHsDevice. This property can be used to seamlessly migrate devices from a legacy configuration without having to recreate the entire device. This ensures that existing events and other links to that device remain the same. When setting the Version property to "4.0", make sure you clear all StatusControls and StatusGraphics on HsDevices first. For HsFeatures, recreate the StatusControls and StatusGraphics before setting the Version.

Changes

• Update Newtonsoft to v13.0.3
• Add AbstractHsDevice.Version
• Add EProperty.Version

Example

string deviceName = (string) _hs.GetPropertyByRef(legacyDeviceRef, EProperty.Name);
//We use int instead of ERelationship here because ERelationship does not contain the Standalone=3 value
int relationship = (int)_hs.GetPropertyByRef(legacyDeviceRef, EProperty.Relationship);

switch(relationship) 
{
    case 3:
        //This is a standalone device, we need to create a root and turn the standalone device as a child of this new root
        NewDeviceData devData = DeviceFactory.CreateDevice(PLUGIN_ID)
            .WithName(deviceName)
            .PrepareForHs();

        int newDevRef = _hs.CreateDevice(devData);

        //Set the standalone ref as a child of the root
        _hs.UpdatePropertyByRef(newDevRef, EProperty.AssociatedDevices, new HashSet<int> { legacyDeviceRef });
        //Turn the standalone as a feature of the newly created device
        _hs.UpdatePropertyByRef(legacyDeviceRef, EProperty.Relationship, ERelationship.Feature);
        _hs.UpdatePropertyByRef(legacyDeviceRef, EProperty.AssociatedDevices, new HashSet<int> { newDevRef });
        
        //Set the interface (only needed if the new plugin has a different ID)
        _hs.UpdatePropertyByRef(legacyDeviceRef, EProperty.Interface, PLUGIN_ID);
        
        //Clear all the controls and status
        _hs.ClearStatusControlsByRef(legacyDeviceRef);
        _hs.ClearStatusGraphicsByRef(legacyDeviceRef);
        
        //Recreate them using AddStatusControlToFeature() and AddStatusGraphicToFeature()
        _hs.AddStatusControlToFeature(legacyDeviceRef, statusControl);
        ...
        _hs.AddStatusGraphicToFeature(legacyDeviceRef, statusGraphic);
        ...
        //Set the version to 4.0
        _hs.UpdatePropertyByRef(legacyDeviceRef, EProperty.Version, 4.0);
        break;
    case 2:
        //This is a root device with children and without any controls or status

        //Set the interface (only needed if the new plugin has a different ID)
        _hs.UpdatePropertyByRef(legacyDeviceRef, EProperty.Interface, PLUGIN_ID);
        ...
        //Set the version to 4.0
        _hs.UpdatePropertyByRef(legacyDeviceRef, EProperty.Version, 4.0);
        break;
    case 4:
        //This is a child device (i.e feature)

        //Set the interface (only needed if the new plugin has a different ID)
        _hs.UpdatePropertyByRef(legacyDeviceRef, EProperty.Interface, PLUGIN_ID);
        
        //Clear all the controls and status
        _hs.ClearStatusControlsByRef(legacyDeviceRef);
        _hs.ClearStatusGraphicsByRef(legacyDeviceRef);
        
        //Recreate them using AddStatusControlToFeature() and AddStatusGraphicToFeature()
        _hs.AddStatusControlToFeature(legacyDeviceRef, statusControl);
        ...
        _hs.AddStatusGraphicToFeature(legacyDeviceRef, statusGraphic);
        ...
        //Set the version to 4.0
        _hs.UpdatePropertyByRef(legacyDeviceRef, EProperty.Version, 4.0);
        break;
    default:
            //Not set / unknown state
            break;
}