Creating devices, parrent, childs

[dcorsus]

I'm working on an HS3 to HS4 migration guide that will include things like an API reference map to help you find new methods from older naming conventions and various architecture changes that effect how you develop your plugins. I'm hoping to have something for you to start with this week.

Appreciate that, thanks! Do want to clarify that first and foremost, I'm talking data structures here, especially if all the data was created in HS3 BUT I want to make a 100% compliant HS4 PI, how do I get the data structures there? One of my examples was that I have a standalone device that has controls and status on it. I understand going forward that would not be supported (perhaps why this devices is currently not working in HS4 with HS3 PI). Same goes for all my parent devices that currently have controls, status and children.

My fear is that any database migration tool might end up migrating a single device into devices and new features (children). When that happens new references get introduces and all events will be hosed, not correct?

Dirk

[bpwwer]

Another good example is a weather station. Would it be better to ahve a "tile" per attribute (temp, rainfall, UV, etc) which means a "Device" and "Feature for each one, or 1 tile with all those attributes: 1 Device with X attributes will get a bit messy in the tile, but all represent the 1 weather station (hardware device)

To me, one "tile" with 25 status features and then 25 control features (For controlling POE) means that that "tile" will never show me all the information I need. So I would look at making each "port" a device, but then that moves away from the parading that 1 tile represents 1 piece of hardware.

Interestingly, the plug-in I'm currently trying to port is for a weather station. In HS3 it was a parent device with each child device representing a sensor value. So based on what we know so far, this should translate to a device with a bunch of features, one for each sensor value. But the current UI isn't going to make that real useful. My initial attempt had each sensor value be a separate device, but configure them with device/feature associations. This made each sensor value have it's own tile and also had the root device include all the other devices within it's tile. I'm about to try creating them as all individual devices, each with one feature and see how that works out. I'm currently grouping them by giving them a location when I create them and then filter on that location.

It's going to take some experimentation to figure how best to implement this in HS4.

[jstuyts]

In my opinion the new model is too simplistic. I understand that new users are confused, but I believe you should onboard them in another way than dumbing down the system so it can no longer handle complex devices.

And devices get more complex all the time. The plug-in I am working on has a root device with a clear status (e.g. configuration error, connecting, connected) and up to 32 (which can become more) child devices. None of these child devices is the primary device, because they provide the same, or at least a similar, function.

Another example is the Nanoleaf plug-in. It currently only supports the whole set of panels as a root device with multiple child devices (which in this case neatly map to features). But I would love to have a Nanoleaf plug-in that allows me to control individual panels.

An ethernet switch is yet another example of a device with sub devices, and I am sure there are devices that have even more levels of sub devices.

So instead of a system that takes a simplistic view: a device with one or more features, one of which is the primary, I would like to have a home automation system that allows me to manage and control complex device trees at a fine-grained level.

[bpwwer]

I've now spent half a day trying to convert my code to create a device with a single feature. Based on the example a ways back, I'm creating the device using a device factory. While doing that I use feature factory to create a feature and include it in the device with deviceFactory.WithFeature(featureFactory);

In the UI, this seems to work as the main device tile shows up with a small icon on the top row representing the feature.

However, I cannot figure out how to access the feature in the code. I want to set a StatusGraphic on it and I want to be able to set it's status and value. But to do that I believe I need the feature reference Id and nothing I've tried has provided that.

Logically, the HsDevice class contains a property called Features which says it's a list of feature id's associated with the device. But it always has zero entries, even right after creating the device. There's also a method GetFeatureByType() but I can't get that to return a feature either.

So how do I manipulate this feature that I created?

[JLDubz]

So instead of a system that takes a simplistic view: a device with one or more features, one of which is the primary, I would like to have a home automation system that allows me to manage and control complex device trees at a fine-grained level.

We are aiming to support both methodologies. We are aware of the power this has as a granular system for those with the expertise and desire to work with a system at that level. There are also a lot of users that want a plug and play experience, and we can't effectively compete in the current market if we do not support this kind of user. Under the hood, the data for devices is still exactly the same as it used to be in HS3. (An idea floating around the office to solve this is a "power-user" type UI that is more data driven and geared towards the DIY crowd as an option instead of the condensed one you see now. This would still be done in the new bootstrap styling, but be a closer fit to the HS3 list style for everything. A stop-gap for you in the meantime, is to use the HS3 pages while you are doing device work in your plugins. Just replace /devices.html with /deviceutility in your web browser.)

This is NOT the end-all solution for how everything is going to work moving forward. This is an evolving system. Think of this paradigm as a structured framework we can more easily build onto and extend as we move forward. This was a particularly difficult thing to support in HS3 because of the way the API and core system were coded. It has made adding new features very, very difficult from a development and support perspective. Now, it is far easier and a less volatile process.

jstuyts, sirmeili, and bpwwer,

Please keep in mind that the currently displayed tile UI is not final, and we are currently working through the design process to provide appropriate tile layouts to effectively display all of the different styles of devices that are out there. One of those examples is a device that has 4+ control or status features that are all important. Another possibility, in a similar way that we have a unique layout for thermostats, is if we do a unique layout for network switches and weather hubs. These are great examples of common devices that do not fit the current blueprint.

Pulling back the curtain for you a little, I currently have the types roughly outlined like so:

• Single feature devices - Device with one feature
• Multi-feature devices - Device with multiple features
  • Single control devices - A device with multiple features, but only one control feature
  • Primary status devices - A device with multiple features and an identified primary status feature
• Dual primary feature devices - Devices with multiple primary features
  • Multi-control devices - A device with multiple features and 2 primary control features
  • Multi-sensor devices - A device with multiple features and 2 primary status features
• Unique devices - Devices that have unique combinations of control and status features
  • Thermostats
  • Network Switches *WIP*
  • Weather Hubs *WIP*
  • Media Remotes *WIP*

How these translate to a tile layout is currently not written out anywhere with matching UI examples. This is part of the blueprinting discussions I've been talking about.

Optimally, I would like to either move the layout definition to something determined via the DeviceTypeInfo or put together some kind of flowchart to help developers understand exactly how HomeSeer is choosing the layout for the device. Thoughts? I'm open to feedback on this.

[JLDubz]

My fear is that any database migration tool might end up migrating a single device into devices and new features (children). When that happens new references get introduces and all events will be hosed, not correct?

We are not planning on any automatic data conversion. As stated in my last post, under the hood, the data in HomeSeer is still exactly the same as HS3. We advise that you build in upgrade mechanisms into your HS4 plugin to update any HS3 style devices to the new format. How you implement this in your plugin is entirely up to you, but I will work through an example of this in the near future.

[dcorsus]

but I will work through an example of this in the near future.

I will gladly lend you my database or PI for you to work on that example

[bpwwer]

I've now spent half a day trying to convert my code to create a device with a single feature. Based on the example a ways back, I'm creating the device using a device factory. While doing that I use feature factory to create a feature and include it in the device with deviceFactory.WithFeature(featureFactory);

In the UI, this seems to work as the main device tile shows up with a small icon on the top row representing the feature.

However, I cannot figure out how to access the feature in the code. I want to set a StatusGraphic on it and I want to be able to set it's status and value. But to do that I believe I need the feature reference Id and nothing I've tried has provided that.

Logically, the HsDevice class contains a property called Features which says it's a list of feature id's associated with the device. But it always has zero entries, even right after creating the device. There's also a method GetFeatureByType() but I can't get that to return a feature either.

So how do I manipulate this feature that I created?

Made a little bit of progress by first creating the device and getting the device reference number and then using FeatureFactory.CreateFeature(plugin, devref) followed by a HomeSeerSystem.CreateFeatureForDevice() to get the feature reference id.

So I now have the devices getting created and I have an ID that I can use to set the status and value of the feature. It appears to be working, but the HS4 UI still doesn't reflect any of the changes. Here's one of the devices in both the HS4 UI and HS3 UI



So based on the HS3 interface, it looks like the status/value for both the main and the feature are getting set, but neither shows up in the HS4 interface.

[Toby]

Pulling back the curtain for you a little, I currently have the types roughly outlined like so:

• Single feature devices - Device with one feature
• Multi-feature devices - Device with multiple features
  • Single control devices - A device with multiple features, but only one control feature
  • Primary status devices - A device with multiple features and an identified primary status feature
• Dual primary feature devices - Devices with multiple primary features
  • Multi-control devices - A device with multiple features and 2 primary control features
  • Multi-sensor devices - A device with multiple features and 2 primary status features
• Unique devices - Devices that have unique combinations of control and status features
  • Thermostats
  • Network Switches *WIP*
  • Weather Hubs *WIP*
  • Media Remotes *WIP*

How these translate to a tile layout is currently not written out anywhere with matching UI examples. This is part of the blueprinting discussions I've been talking about.

Optimally, I would like to either move the layout definition to something determined via the DeviceTypeInfo or put together some kind of flowchart to help developers understand exactly how HomeSeer is choosing the layout for the device. Thoughts? I'm open to feedback on this.

This sounds promising.
I think it would be a good idea to have this based on deviceType and then also alow us to create new custom deviceType with custom layout. In this way I could adjust the layout to better fit my plugin and get some differentiation to other plugins.

There has always been cases of multiple plugin that more or less are overlapping each other, but with different features and functions. With this we could add different design/layout to the list.

And ideally I would to be able to set a default blueprint for Web, mobile and HSTouch layout. But still wit possible to access the individual features/values and display them separately in mobile and HSTouch when needed.
(I would typically want to see a different view in a day to day view oposed to a admin view.)

[rjh]

What does it look like in the HS4 list view? That view shows a little more information.

Made a little bit of progress by first creating the device and getting the device reference number and then using FeatureFactory.CreateFeature(plugin, devref) followed by a HomeSeerSystem.CreateFeatureForDevice() to get the feature reference id.

So I now have the devices getting created and I have an ID that I can use to set the status and value of the feature. It appears to be working, but the HS4 UI still doesn't reflect any of the changes. Here's one of the devices in both the HS4 UI and HS3 UI



So based on the HS3 interface, it looks like the status/value for both the main and the feature are getting set, but neither shows up in the HS4 interface.

[bpwwer]

What does it look like in the HS4 list view? That view shows a little more information.

List view shows device/feature reference numbers and the feature name, that the only differences.

[rjh]

If you hover over the icon at the top of the view, does that show the temp? I think what is happening is that the status in the main view is the root device, which does not have status. We display the children at the top. But if this was true, the list view should display the all the child devices with their status.

We are working on a way so you can specify which device(s) are your primary devices. Primary devices appear in the grid view as the "main" device. Right now we pick a primary by picking the first device that has controls. In your case your child devices (features) do not have controls so we don't pick one. We will have the selection option (primary ref) available soon.

What does it look like in the HS4 list view? That view shows a little more information.

[lpitman]

I am still waiting a complete example in VB as promised. In addition to creating devices, how are they updated in new API?

[lpitman]

What is wrong with this code? Id is a property in HSPI, but isn't recognized as used below.

Imports HomeSeer.PluginSdk
Imports HomeSeer.PluginSdk.Devices

Friend Module Devices

#Region "    InitDevices    "

    '**************************************************************
    ' Create some virtual devices from HS for use in displaying information
    ' about your hardware. Devices can represent I/O points, temperature points, etc.
    Public Sub InitDevices()

        ClsLogging.OutputHSLog("Entering...Devices.InitDevices().", DEBUG_LOGGING, "Debug", COLOR_BLACK)


        CreateDevices()
    End Sub

    '**************************************************************
    Sub InitHSDevice(ByRef dv As Scheduler.Classes.DeviceClass, Optional ByVal Name As String = "Sample")

        ClsLogging.OutputHSLog("Entering...Devices.InitHSDevice().", DEBUG_LOGGING, "Debug", COLOR_ORANGE)


    End Sub

#End Region

#Region "    Create Devices    "

    '****************************************
    Friend Sub CreateDevices()

        Dim j As Integer

        Dim refIDs As List(Of Integer) = IHsController.GetRefsByInterface(Id)

        ClsLogging.OutputHSLog("Entering  Devices.CreateDevices()....", DEBUG_LOGGING, "Debug", COLOR_ORANGE)

        '=========================================
        '  ZipBackup Backup Now Device
        '=========================================

        ' First see if our devices exist before creating new ones
        If refIDs.Count = 0 Then

            Dim df As DeviceFactory = HomeSeer.PluginSdk.Devices.DeviceFactory.CreateDevice(Id)

            df.WithName("ZipBackup Status")
            df.WithLocation("Status")
            df.WithLocation2("ZipBackup")
            df.AsType(HomeSeer.PluginSdk.Devices.Identification.EDeviceType.Generic, 0)

            '----------------------------------------------------------

            ' Example of adding feature
            Dim ff As FeatureFactory = FeatureFactory.CreateFeature(Id)

            ff.WithName("Artists")

            Dim artists As New SortedDictionary(Of String, Double)

            For i = 0 To 99
                artists.Add(j.ToString(), j)
            Next

            ff.AddTextDropDown(artists)
            df.WithFeature(ff)

            Dim dd As NewDeviceData

            dd = df.PrepareForHs()

        End If

    End Sub

#End Region

[bpwwer]

If you hover over the icon at the top of the view, does that show the temp? I think what is happening is that the status in the main view is the root device, which does not have status. We display the children at the top. But if this was true, the list view should display the all the child devices with their status.

Just the name is displayed when I hover over the feature.



And list view (I don't know why it is so small)



If I switch to the HS3 interface, both the main and the feature show the proper status. Well almost proper. I configure the StatusGraphics with a range and that range has a suffix, but the suffix is not displayed. I'm assuming that's because the HS3 interface only knows how to display prefix/suffix information for StatusValues and not for StatusGraphics.

We are working on a way so you can specify which device(s) are your primary devices. Primary devices appear in the grid view as the "main" device. Right now we pick a primary by picking the first device that has controls. In your case your child devices (features) do not have controls so we don't pick one. We will have the selection option (primary ref) available soon.

That's an issue, but shouldn't I be seeing the feature status even it it's not marked as Primary? Is this maybe more an issue with StatusGraphics not working for status only devices?