I am very impressed with Hubitat - particularly the ability to write custom applications and devices. The weak link in Hubitat seems to be the inability to customize dashboards on par with custom applications and devices. A few times now, I have authored a new device only to find the available dashboard device templates insufficient to present the new device. This situation leads to refactoring a new holistic user device into something more fragmented that the dashboard can render (e.g., instead of one user device a parent user device with multiple child devices that better correspond to available device templates).
To @patrick's (Mar '19) offer to address template gaps ...
I believe there is an interim step - short of user-provided dashboard templates - that would help significantly. Specifically, I recommend reconciling Hubitat's device capabilities with Hubitat's device templates - perhaps through small documentation tweaks. Such a reconciliation would be immediately beneficial to User device authors AND serve as a baseline for discussing new capabilities (attributes and commands) that require corresponding device templates (whomever provides these templates).
Detailed Example:
-
The Driver Capability List offers drill downs like capability.switchLevel, where we see the attribute level is a NUMBER and the command setLevel expects one or two NUMBERs. [The level argument is required, the duration argument is optional.]
-
Currently, the capability list does not indicate (but perhaps should indicate) which available Device Templates correspond to each capability.
-
A device template like Level (see image below) seems like a natural fit for capability.switchLevel.
-
In general, device template documentation does not indicate the corresponding capability(ies) (expected device attributes and commands) the template is designed to render/manage.
[Currently, the Level template is not listed on the Device Templates page; but, this is a side point.] -
Through experimentation with the Level template: The template number reflects the attribute level. The up and down arrows on the template expect a single argument version of the setLevel() command - i.e., setLevel(level) as opposed to setLevel(level, duration).
-
The Level template includes (hard coded?) quirky behavior wherein the up/down arrows request a level that is 10 units higher or 10 units lower than the current level.
[There does not appear to be any facility for adjusting the default increment/decrement levels for the template.]
The Benefits of Reconciling Capabilities to Templates
-
Reconciling the Capability List to the Device Templates would clarify where there is great fit, a partial fit or a gap between the two.
-
By associating specific capabilities with specific templates, the dashboard editor could present a filtered list of viable device templates (i.e., Pick a Template) for a selected device (i.e., Pick a Device) based on the capabilities the device advertises.
-
For preceding example, reconciliation would tell us:
(1) The Level dashboard template is a partial fit for capability.switchLevel
(2) The template displays the current level attribute
(3) Devices need to include the one-argument version of the Level() command
(4) Limitations: The dashboard template will request new up/down levels with a fixed increment of 10 units.
(5) Workaround(s): A user device can (at the author's discretion) ignore the specific requested level (up 10 units or down 10 units) - for example increment by 1 or decrement by 1. A user device can enforce levels more constrained than the specification (e.g., n..m vs 0..100). The dashboard template will reflect the actual level attribute implemented by the user device.
Device Decomposition Example
Device author's can come up with an infinite list of things they would like to see in the dashboard. Here is one relatively simple example to discuss available/prospective options.
There are several posts wherein a prospective user device author wants to display a time and solicit changes from a user. He/she may begin to author a standalone user device solution like SettableTimeDevice.groovy with the expectation of locating or writing a corresponding single dashboard template - e.g., EditableTimeTemplate.
Absent the ability to write a custom dashboard template, device authors face two options.
-
Refactor their holistic device into a parent device with child devices that collectively better match the available dashboard templates. [See example to follow.]
-
Abandon writing a new user device and instead pursue a Rule Machine Global Variables (@bravenel) which includes a time (--:-- --) option which can be presented on a dashboard via a connector.
Option 1 works, but it can get ugly fast. For example: Instead of a holistic SettableTimeDevice.groovy with a single dashboard tile, the following image illustrates a refactored SettableTimeDevice.groovy (as parent device) that leverages two child devices HourSelectorDevice.groovy and MinuteSelectorDevice.groovy.
Instead of one clean tile on the Dashboard, there are four tiles:
-
The left-most tile operates on an instance of the parent SettableTimeDevice named 0sod. It presents the custom attribute timeTwoWays (am/pm and 24-hour).
-
The two middle tiles operate on instances of HourSelectorDevice.groovy and MinuteSelectorDevice.groovy, respectively. The custom devices enforce appropriate constraints on the value of the level attribute. Increment/decrement behavior are constrained to 1 for hours and 5 for minutes - overriding the default of "10 units" in the device template (see prior discussion).
-
The right-most tile leverages the Variable String template which passes a free-text string to the parent device via the command void setVariable(String). [The parent parses the string accepting time representations in 12 or 24 hour mode with flexibility on spaces, capitalization, etc. Note: There is no attribute whereby the device author can update the data presented in the Variable String template; so, communications is one-way from the dashboard to a device.]
Standardizing on Capabilities is a Better Option
As a step toward custom dashboard templates, there are benefits to documenting new capabilities.
Consider the existing dashboard template that displays a Rule Machine time Global Variable with a Connector.
More clearly linking device templates (like this one) to published device capabilities would give User Device authors better architectural targets.
Perhaps this template corresponds to a new, unpublished capability like capability.settableTime that expects a single String/regexp attribute time and a single command setTime(time).
A slightly improved dashboard editor would allow User device author's that implement capability.settableTime to leverage the (in this case existing) built-in device template.
Formalizing the capabilities of all existing dashboard templates - like Variable String in the prior example - would clarify the expected attributes (device to dashboard) and commands (dashboard to device) each template supports.
