Migrate HS3 documentation

[b_weijenberg]

https://docs.homeseer.com/display/HSPI/Using+the+SDK
Migrate an existing HS3 plugin
Documentation on this subject will be coming soon.

We see this remark for a long time on the docs page, when can we expect this migration document so that I can start ???

[kriz83]

Same thing here. I haven't even started to work on the migration. Need some decent documentation/guides before I can justify putting effort in it. Unfortunately I don't have time to figure things out on my own :-(

[stefxx]

Waiting as well. Can't afford to reinvent the wheel.

[alexbk66]

I spent a few months mastering HS3 development, now start again?

[kriz83]

rjh Any update on this ?

[alexbk66]

jseer JLDubz ?

[kriz83]

An update would be appreciated here ...

[jseer]

The best answer I can give you is soon. We are working on converting Z-Wave and creating a doc simultaneously. The conversion of Z-Wave is giving us a better understanding of the intricacies of the development as well as best practices. We will update you when we have more information to provide.

~Jon

[mnsandler]

I'm waiting for this information as well. That means no HS4 Insteon support until I'm up to speed on all of this. I need clear guidance/documentation as to what is expected in an HS4 plugin. I'm not going to fumble around with the sample plugin, or the sdk.

[rjh]

This page lists the API changes which should give you a start. Let me know if I can answer any questions regarding this. Once we complete the Z-Wave plugin port we will create a more detailed guide.

https://docs.homeseer.com/display/HS...+API+Reference

[Michael McSharry]

This is a nice reference, but surprised me at the degree of change there is under the hood.

In the prior HS generations I had to deal with maintaining code for different versions. My standalone mcsSprinklers was developed along side HS1 plugin so the HS1 API was the basis. I had to keep the HS1 API for the standalone so for HS2 (and HS3) I used a HSPI wrapper around the HS1 API to translate at run time. This meant that for any HS1 procedure that I was using I had this procedure defined in the wrapper. Quite often it was just a pass-through of parameters, but in some cases it was more substantial code. While this took care of 95% of upgrade there was still that 5% that was done using conditional logic in the core. Originally the conditional logic was compile-time, but later migrated to run time as compile time became too complex as Linux support was added.

I have not started with any HS4 migration so don't know if this strategy will work. I suspect my mcsMQTT plugin is more like other HS3 plugins that do not have the backward compatibility constraint. It should not be that difficult to fork and when HS4 gets out of Beta then stop HS3 code change support. While it may be much effort for rewriting the plugin there will not be a continued HS3 maintenance problem.

What is not yet clear to me is the need to update HS3 plugin code if HS3 code runs under HS4. I also do not understand how HS3 devices can have controls but HS4 devices are only root entities with Features being the container for controls. I suspect I will learn when I try to do something with the HS4SDK.

[rjh]

For some. if they are just using devices, their HS3 plugin will look the same as an HS4 plugin. Note that the HS4 plugin API is a wrapper over HS3. We have not changed anything underneath. The UI of course is different so that's where issue can show.

While I feel its better to just create an HS4 plugin, you could check the version in your HS3 plugin and if you are running under HS4 change your HTML on your config pages to return it in Bootstrap format. This way it looks and works fine in HS4.

This is a nice reference, but surprised me at the degree of change there is under the hood.

In the prior HS generations I had to deal with maintaining code for different versions. My standalone mcsSprinklers was developed along side HS1 plugin so the HS1 API was the basis. I had to keep the HS1 API for the standalone so for HS2 (and HS3) I used a HSPI wrapper around the HS1 API to translate at run time. This meant that for any HS1 procedure that I was using I had this procedure defined in the wrapper. Quite often it was just a pass-through of parameters, but in some cases it was more substantial code. While this took care of 95% of upgrade there was still that 5% that was done using conditional logic in the core. Originally the conditional logic was compile-time, but later migrated to run time as compile time became too complex as Linux support was added.

I have not started with any HS4 migration so don't know if this strategy will work. I suspect my mcsMQTT plugin is more like other HS3 plugins that do not have the backward compatibility constraint. It should not be that difficult to fork and when HS4 gets out of Beta then stop HS3 code change support. While it may be much effort for rewriting the plugin there will not be a continued HS3 maintenance problem.

What is not yet clear to me is the need to update HS3 plugin code if HS3 code runs under HS4. I also do not understand how HS3 devices can have controls but HS4 devices are only root entities with Features being the container for controls. I suspect I will learn when I try to do something with the HS4SDK.

[mnsandler]

the following is a start (for the programming details), but what we really need to understand is all the parts of the HS3 plugin we must change/rewrite for HS4.

https://docs.homeseer.com/display/HSPI/Using+the+SDK

What is the totality of what we have to change?

the plugin configuration pages
the device edit pages
the event UI/config page
the trigger UI/config pages
the condition UI/config pages

will all our saved event definitions still work in HS4? (i use serialized data objects to store event definitions; will this continue to work as-is in HS4?)

remove multiple instance support logic (that's a big blow to my alarm plugin which i spent weeks/months converting)

what else? please elaborate on other migration issues

[mnsandler]

how do we migration HS devices without breaking the dv.ref values? I had a parent device with standard on/off controls and child devices with other status and controls? What does this look like in HS4?

rjh and jseer, we could use some sample code snippets in the SDK

It would be extremely helpful if every API reference had a code snippet on how to use that method, or property

[rjh]

If the functionality of the device is not changing, you really don't need to migrate it. Is there a reason you want to do this?

how do we migration HS devices without breaking the dv.ref values? I had a parent device with standard on/off controls and child devices with other status and controls? What does this look like in HS4?

rjh and jseer, we could use some sample code snippets in the SDK

It would be extremely helpful if every API reference had a code snippet on how to use that method, or property