Has the HS4 programmer documentation improved since jan/feb 2020

[mnsandler]

The SDK looks about the same as it did at the end of 2019.

I'm looking for guidance on how to upgrade my hs3 plugin to hs4 so it will continue to supports my hs3 users.

also looking for guidance on how to convert an hs3 multi-instance plugin to HS4.

It seems like i have to add a dummy root device to everything i already have.

Maybe it would be easier to write a completely new hs4 plugin, and then write an upgrade routine to migrate devices, and events to HS4

i dont see how one can just assume the hs3 devices, and events will just work in hs4.

anyone want to make some money on the side

[sirmeili]

Why do you feel you need to add a dummy device? You mean for the new Root/Feature device architecture or do you feel you have to add a dummy root device due to the multi-instance replacement?

[Michael McSharry]

Start by redoing your HS3 plugin where the plugin manages multiple hardware components rather than doing only one and expecting HS to manage the multiple. I just made my objects arrays to handle multiple instances. After this structure is in place then you only have API change to manage. Of course you could ignore multiple instance until converted and the update for multiple later.

[sirmeili]

I generally use dictionaries and use a unique ID to differentiate between "instances" of some kind of communication client.

[dcorsus]

I tweaked but mostly kept the HS3 provided (I believe in the example) functions. Instead of instantiating an instance of class HSPI, I instantiate whatever class I created for each instance, MediaDevice in the example below

Module OldHS3MultiInstanceFunctions

Public AllInstances As New SortedList

Public Function AddInstance(InstanceName As String) As MediaDevice
If piDebuglevel > DebugLevel.dlErrorsOnly Then Log("AddInstance called with InstanceName = " & InstanceName, LogType.LOG_TYPE_INFO)
AddInstance = Nothing
If AllInstances.Contains(InstanceName) Then
If piDebuglevel > DebugLevel.dlErrorsOnly Then Log("Warning AddInstance called with InstanceName = " & InstanceName & " but instance already exists", LogType.LOG_TYPE_WARNING)
Exit Function
End If
Dim MediaDeviceAPI As MediaDevice = (New MediaDevice())

MediaDeviceAPI.instance = InstanceName
MediaDeviceAPI.isRoot = False
SyncLock (AllInstances)
Try
AllInstances.Add(InstanceName, MediaDeviceAPI)
If piDebuglevel > DebugLevel.dlErrorsOnly Then Log("AddInstance successfully added InstanceName = " & InstanceName & ", Count = " & AllInstances.Count.ToString & ", Capacity = " & AllInstances.Capacity.ToString, LogType.LOG_TYPE_INFO)
Catch ex As Exception
MediaDeviceAPI.DestroyPlayer(True)
MediaDeviceAPI = Nothing
Log("Error in AddInstance connecting or disconnecting InstanceName = " & InstanceName & " with Error = " & ":" & ex.Message, LogType.LOG_TYPE_ERROR)
End Try
End SyncLock
Return MediaDeviceAPI
End Function

Public Function RemoveInstance(InstanceName As String) As String
RemoveInstance = ""
If piDebuglevel > DebugLevel.dlErrorsOnly Then Log("RemoveInstance called with InstanceName = " & InstanceName, LogType.LOG_TYPE_INFO)
If Not AllInstances.Contains(InstanceName) Then
Return "Instance does not exist"
End If
SyncLock (AllInstances)
Dim DE As DictionaryEntry
Try
For Each DE In AllInstances
Dim key As String = DE.Key
If key.ToLower = InstanceName.ToLower Then
Dim md As MediaDevice = DE.Value
md.ShutdownAPI()
AllInstances.Remove(key)
Exit For
End If
Next
Catch ex As Exception
If piDebuglevel > DebugLevel.dlErrorsOnly Then Log("Error in RemoveInstance for InstanceName = " & InstanceName & " with Error = " & ex.Message, LogType.LOG_TYPE_ERROR)
RemoveInstance = "Error removing instance: " & ex.Message
End Try
End SyncLock
End Function

Public Function GetInstance(InstanceName As String) As MediaDevice
If piDebuglevel > DebugLevel.dlErrorsOnly Then Log("GetInstance called with InstanceName = " & InstanceName, LogType.LOG_TYPE_INFO)
If Not AllInstances.Contains(InstanceName) Then
Return Nothing
End If
Dim DE As DictionaryEntry
Try
For Each DE In AllInstances
Dim key As String = DE.Key
If key.ToLower = InstanceName.ToLower Then
Return DE.Value
End If
Next
Catch ex As Exception
If piDebuglevel > DebugLevel.dlErrorsOnly Then Log("Error in GetInstance for InstanceName = " & InstanceName & " with Error = " & ex.Message, LogType.LOG_TYPE_ERROR)
Return Nothing
End Try
Return Nothing
End Function


End Module

[mnsandler]

Why do you feel you need to add a dummy device? You mean for the new Root/Feature device architecture or do you feel you have to add a dummy root device due to the multi-instance replacement?

Regarding the dummy device: In my HS3 plugin, the parent device is the main switch with the On/off/dim controls, and the child devices are other controls/buttons. Now i have to have a root device that does nothing and move all my devices and controls to feature devices.

how does this work for existing hs3 users moving hs4? do i have to rebuild all the hs3 devices in the hs4 architecture?

[dcorsus]

Regarding the dummy device: In my HS3 plugin, the parent device is the main switch with the On/off/dim controls, and the child devices are other controls/buttons. Now i have to have a root device that does nothing and move all my devices and controls to feature devices.

how does this work for existing hs3 users moving hs4? do i have to rebuild all the hs3 devices in the hs4 architecture?

I assume you mean converting your HS3 PI to a native HS4 PI, right?

So what I did, actually upon recommendation from Rich, when your HS4 PI starts up for the first time, it notices no HS4 settings file for your PI but notices a HS3 settings file for your PI, it starts an "import/conversion" procedure.

To prevent that you break actions/events etc. it is critical you keep the same HS references, so the trick is to create a new device which will become your new root (with no controls on them), you take your old root device, make it a child of the new root and change its flags from "device" to "feature". As such the reference remains unchanged and any action that was depending on that reference (and the controls attached to that reference) will properly work. Last thing you do, is to take all your old children and make them children of the new root and remove them from the old root. Again no references change and all will work as it should.

There is one gotcha however, the SDK has an issue with redefining associations (parent/children) in that it seems to support only adding children and is not capable of removing them, so there is a bug report that has been open forever and for the life of me, doesn't seem to get any attention (https://github.com/HomeSeer/Plugin-SDK/issues/82).

Next on your list, is to convert old triggers/conditions/actions to new format, there is a thread I believe by Michael McSharry that explains which functions to add, it was all but straightforward for me, but could be the way and the complexity of my actions.

Hope this helps, I can post conversion code if you like

[Michael McSharry]

dcorsus
In my HS4 mcsMQTT plugin I do quite a bit of relationship management and this does include removing features or changing the device to which a feature is associated. If I recall I am just using the updateProperty method on AssociatedDevices property. I guess I need to go back and make certain it is doing everything that is expected. I’ll also look at #82.

[mnsandler]

thanks for the all the feedback and suggestions

what do you think about the current state of the HS4 SDK docs? Does it have enough examples and detail to get me through all this?

I dont want to have to start a thread each time i get stuck. I want to be able to focus on this for about a week and get it done.

[mnsandler]

are you guys still building pages like the following to allow users to manage all the plugin devices from one screen? is this an html (or settings) page, or should we just use the hs4 device pages now, and have the users manage device features there?

[dcorsus]

I think you can decide whatever you want to support, the challenge is the effort you are going to spend. HS4 provides a "quick" way to make config pages, but the functions are very limited. You can create your own HTML pages using bootstrap and scriban/liquid tags. Reasonably powerful but you better become an HTML expert if you liked all the JSQuery support we had in HS3. Here are some of my screens ...

[rmasonjr]

are you guys still building pages like the following to allow users to manage all the plugin devices from one screen? is this an html (or settings) page, or should we just use the hs4 device pages now, and have the users manage device features there?

I'm writing a new plugin and I gave up on SettingsPages. You cant really modify the layout very much. I went with plain HTML and used the liquid tags to reach back into the plugin to get data for display. You have to do a fair amount of JavaScript to check setting values, then use modal dialogs to notify the user. It was a HUGE learning curve for me.

On my old OMNI plugin, I was already using parent/child devices, so that plugin appears to work unmodified for HS4.