No where in the Hubitat Sonos speaker integration documentation is there information re: the definition and use of the device exposed Sonos device "volume" vs "level" parameters/commands.
Aside from the documented Hubitat notification, TTS, etc. stuff, how, when, and where should "volume" vs "level" be used in controlling a Sonos speaker?
Feedback -
It would be super helpful if Hubitat were to provide descriptions, use cases, and examples for ALL commands and parameters available within ALL Hubitat supported integration devices (including those created for Sonos).
I TOTALLY get the reluctance to deal w/ taking the time to over document "things" as I have an engineering background and completely understand the amount of time it requires to manage.
The difference here is that it would go a LONG way in getting your primary demographic moving along w/o asking questions of Hubitat Support and/or the Community.
i.e., The more information provided, the less customer interaction!
The "Set Level" and "Set Volume" commands have identical behavior in the Sonos Player driver, if that is what you are asking. (Many apps cannot deal with music players directly but can deal with dimmer-type devices, which is where the "Set Level" command can be handy, or at least could when the integration was written early on in the platform's history.)
I understand what you are saying re: level and dimmer-type devices.
I want to be helpful vs argumentative and I sincerely appreciate the response as it definitely helped me better understand this particular functionality in my testing.
In this case, I think it would be helpful for the Hubitat Sonos Integration documentation to reflect how output can be managed as a dimmer OR player device, that they are equivalent, and "volume" and "level" update in unison.
In general, I think it would help Hubitat and Hubitat users if there were more complete documentation for ALL devices created as part of an included Hubitat integration and ALL exposed commands and/or parameters.
I've looked through a bunch of Hubitat related pages online and it seems like with this and other Hubitat Integration devices, Hubitat always falls a bit short when it comes to how Hubitat Integration devices can be controlled with what is exposed along w/ examples.
In any case, the additional documentation would be definitely appreciated, and help w/ new customer acquisition and adoption - which is a win for ALL Hubitat users!
The Sonos Integration is good example in that there are SO many different exposed commands and preferences where it's not exactly clear when, where, and how to use them - especially those that have blank entry fields.
Even a 1 or 2-liner for each in a new Hubitat "Device Reference" repository/database of pages would be SUPER helpful.
A repository/database would be more helpful than the existing forum pages as it's difficult and time-consuming to search through pages and pages of forum entries to only "maybe" find the needed info.
Re: 3rd-party integrations, Hubitat could provide developers a Device Reference page "template" that would make it easy for them to provide similar information in a standardized manner.
The completed templates could then be "sucked" into the repository/database as part of the existing "Hubitat Package Manager" upload process.
I definitely understand the suggestion and see value in it. However, I wonder if trying to keep separate documentation update for each device is the most effective way of achieving this goal? As a community developer, I do take for granted that the users have a certain baseline of knowledge of the Hubitat platform. Obviously, that is not a fair assumption to make, especially for new users.
Thus, I have been trying to be much more deliberate in documenting commands and user prefefences in the Groovy code, such that the information is available directly from the Hubitat UI for a device.
For example, here is what my Aqara FP300 driver shows the user. I believe documenting these commands and settings in this manner may provide a much better user experience vs expecting users to look up a separate document.
The burden of documenting still relies on the developer. I like to provide this level of information within the device UI as I believe it will result in fewer questions to me via the forum.
Thoughts?
One thing this method does not address is providing sample use-cases.
