[REQUEST] Documentation request for built-in child and virtual device types used in driver developmen and rules

dmitry.rozovik · October 2, 2023, 9:19am

Hello there!

This is sort of documentation request for a range of built-in device types that are used for compound driver implementation.

Unfortunately at the moment the information is poor and scarse. Often more like a guess.
Would be nice to have atleast a simplistic documentation in a form of implemented capabilities, additional attributes and functions expected from parent device to be implemented. Pretty much in a way how capabilities are documented.

Generic Component Acceleration Sensor
Generic Component Audio Zone
Generic Component Button Controller
Generic Component Button Controller (PHR)
Generic Component Button Controller (PR)
Generic Component Carbon Dioxide Detector
Generic Component Carbon Monoxide Detector
Generic Component Central Scene Dimmer
Generic Component Central Scene Switch
Generic Component Contact Sensor
Generic Component Contact/Switch
Generic Component Contact/Switch/Temp
Generic Component CT
Generic Component Dimmer
Generic Component Energy Meter
Generic Component Fan Control
Generic Component Fan Light Control
Generic Component Humidity Sensor
Generic Component Lock
Generic Component Metering Switch
Generic Component Motion Sensor
Generic Component Multi Sensor
Generic Component Omni Sensor
Generic Component Power Meter
Generic Component Presence Sensor
Generic Component RGB
Generic Component RGBW
Generic Component RGBW Light Effects
Generic Component Smoke Detector
Generic Component Sound Sensor
Generic Component Switch
Generic Component Temperature Sensor
Generic Component Thermostat
Generic Component Voltage Sensor
Generic Component Water Sensor
Generic Component Window Shade

Virtual Acceleration Sensor
Virtual audioVolume
Virtual Battery Powered Device (user)
Virtual Button
Virtual CO Detector
Virtual Color Temperature Light
Virtual Contact Sensor
Virtual Dimmer
Virtual Fan Controller
Virtual Garage Door Controller
Virtual Humidity Sensor
Virtual Illuminance Sensor
Virtual Lock
Virtual Lock (no codes)
Virtual Moisture Sensor
Virtual Motion Sensor
Virtual Multi Sensor
Virtual Omni Sensor
Virtual Outlet
Virtual Presence
Virtual Presence with Switch
Virtual RGB Light
Virtual RGBW Light
Virtual Shade
Virtual Smoke Detector
Virtual Sound Sensor
Virtual Switch
Virtual Temperature Sensor
Virtual Thermostat
Virtual Valve

Connector Acceleration Sensor
Connector ColorTemp Control
Connector Contact Sensor
Connector DateTime
Connector Dimmer
Connector Humidity Sensor
Connector Illuminance Sensor
Connector Lock
Connector Motion Sensor
Connector Presence Sensor
Connector Switch
Connector Temperature Sensor
Connector Variable
Connector Volume Control
Connector Water Sensor

frient Component Contact Sensor
frient Component Garage Door Controller
frient Component Switch

For the overall description it is more or less clear how intended to be used. But it is less obvious for virtual devices and connectors.

Also it is interesting why frient has its own component devices (feature differences?)

Tagging @bobbyD as you are mentioned in the documentation section. Maybe you could address this topic to someone more appropriate/related.

sburke781 · October 2, 2023, 10:33am

I suspect what you are asking for is a worthwhile request, to help developers and general users of the platform. But I think it may help to clarify the use cases you are wanting to satisfy... Am I right in thinking you want to cover:

Developers creating (mostly) child devices - Including for their custom parent devices, wanting to know the capabilities and other detail for any child device they create. I could understand this may be particularly important for virtual devices like a Thermostat which may implement multiple capabilities
General Users Creating Virtual Devices - I expect (know) the capabilities become important when using the device in automations and needing to understand the capabilit(ies) available to select or the attributes that may be available in conditions, etc.

Your question about Frient is one I can't answer, but would suspect your are on the right track....

dmitry.rozovik · October 2, 2023, 12:05pm

Yes. It is about both cases.

The case of custom parent device (more for developers) to know what and how any developer can use from predefined child device set before going to write a custom one.

And the case for let's say RM (more for regular users) to know about attributes they can listen or alter. And the same way for developers to use as another possible set of predefined child devices (if no control feedback to parent device is needed)

sburke781 · October 2, 2023, 12:12pm

Ok, good to know... well at least for those who can action this request....

csteele · October 2, 2023, 1:43pm

I think Documentation is a good request.

As a tedious workaround, you can use Get Attributes App (in HPM) to display Capabilities, Attributes, and Commands of any Device. Thus the tedious part is swapping a virtual device to the next component driver.

For example, I created a virtual device named "pseudoNothing" and assigned it the "Fibaro Wall Plug USB Port Component" then selected pseudoNothing in Get Attributes App and the results were:

Screenshot 2023-10-02 at 6.38.36 AM

Then I swapped to the "Generic Component Carbon Dioxide Detector" and got:

Screenshot 2023-10-02 at 6.39.13 AM

You can, of course, create a dozen virtual device for a dozen drivers and Get Attributes App will display them all at once.

This can fill in the gap while the documentation is being created, I think.

dmitry.rozovik · October 2, 2023, 4:14pm

Info using Get Attributes App: (attributes are listed only if there were some redundancy spotted according to the app report; no extra attributes detected for "Generic Compnent *" devices)

Generic Component Acceleration Sensor
    AccelerationSensor
    Sensor 	
Generic Component Audio Zone
    Actuator
    AudioVolume
    MediaInputSource
    Switch
 	Extra commands: refresh
Generic Component Button Controller
    Actuator
    DoubleTapableButton
    HoldableButton
    PushableButton
    ReleasableButton 	
Generic Component Button Controller (PHR)
	Actuator
    HoldableButton
    PushableButton
    ReleasableButton
Generic Component Button Controller (PR)
	Actuator
    PushableButton
    ReleasableButton
Generic Component Carbon Dioxide Detector
	CarbonDioxideDetector
    Sensor 	 
 	[carbonDioxide, carbonDioxide] // redundant attribute ???
Generic Component Carbon Monoxide Detector
    CarbonMonoxideDetector
    Refresh
    Sensor
Generic Component Central Scene Dimmer
    Actuator
    ChangeLevel
    DoubleTapableButton
    HoldableButton
    Light
    PushableButton
    Refresh
    ReleasableButton
    Switch
    SwitchLevel
 	[switch, pushed, numberOfButtons, switch, level, released, doubleTapped, held] // redundant attribute ???
Generic Component Central Scene Switch
    Actuator
    DoubleTapableButton
    HoldableButton
    Light
    PushableButton
    Refresh
    ReleasableButton
    Switch 	 
 	[switch, pushed, doubleTapped, held, switch, released, numberOfButtons] // redundant attribute ???
Generic Component Contact Sensor
    ContactSensor
    Sensor
Generic Component Contact/Switch
	Actuator
    ContactSensor
    Refresh
    Sensor
    Switch
Generic Component Contact/Switch/Temp
    Actuator
    ContactSensor
    Refresh
    Sensor
    Switch
    TemperatureMeasurement
Generic Component CT
	Actuator
    ChangeLevel
    ColorTemperature
    Light
    Refresh
    Switch
    SwitchLevel
    [colorName, level, colorTemperature, switch, switch] // redundant attribute ???
Generic Component Dimmer
    Actuator
    ChangeLevel
    Light
    Refresh
    Switch
    SwitchLevel
    [level, switch, switch] // redundant attribute ???
Generic Component Energy Meter
    EnergyMeter
    Refresh
    Sensor
Generic Component Fan Control
    Actuator
    FanControl
    Refresh
    Switch
    SwitchLevel
Generic Component Fan Light Control // redundant device ???
    Actuator
    FanControl
    Refresh
    Switch
    SwitchLevel
Generic Component Humidity Sensor
	Refresh
    RelativeHumidityMeasurement
    Sensor
Generic Component Lock
    Actuator
    Lock
    LockCodes
    Refresh
Generic Component Metering Switch
    Actuator
    EnergyMeter
    PowerMeter
    Refresh
    Switch
Generic Component Motion Sensor
    MotionSensor
    Sensor
Generic Component Multi Sensor
	AccelerationSensor
    ContactSensor
    Refresh
    Sensor
    TemperatureMeasurement
Generic Component Omni Sensor
    AccelerationSensor
    CarbonDioxideMeasurement
    CarbonMonoxideDetector
    ContactSensor
    EnergyMeter
    IlluminanceMeasurement
    MotionSensor
    PowerMeter
    PresenceSensor
    Refresh
    RelativeHumidityMeasurement
    Sensor
    SmokeDetector
    TemperatureMeasurement
    WaterSensor 	 
Generic Component Power Meter
    PowerMeter
    Refresh
    Sensor
Generic Component Presence Sensor
	PresenceSensor
    Refresh
    Sensor
Generic Component RGB
	Actuator
    ChangeLevel
    ColorControl
    Light
    Refresh
    Switch
    SwitchLevel
    [color, hue, colorName, RGB, switch, switch, level, saturation] // redundant attribute ???
Generic Component RGBW
    Actuator
    ChangeLevel
    ColorControl
    ColorMode
    ColorTemperature
    Light
    Refresh
    Switch
    SwitchLevel
    [colorName, switch, colorTemperature, hue, color, level, colorMode, RGB, colorName, switch, saturation] // redundant attributes ???
Generic Component RGBW Light Effects
    Actuator
    ColorControl
    ChangeLevel
    ColorMode
    ColorTemperature
    Light
    LightEffects
    Refresh
    Switch
    SwitchLevel
 	[colorName, colorMode, saturation, colorTemperature, switch, lightEffects, colorName, switch, level, RGB, effectName, color, hue] // redundant attributes ???
Generic Component Smoke Detector
    Sensor
    SmokeDetector
Generic Component Sound Sensor
    Refresh
    Sensor
    SoundSensor    
Generic Component Switch
    Actuator
    Refresh
    Switch
Generic Component Temperature Sensor
    Refresh
    Sensor
    TemperatureMeasurement
Generic Component Thermostat
    Actuator
    Refresh
    Sensor
    TemperatureMeasurement
    Thermostat
Generic Component Voltage Sensor
    Refresh
    Sensor
    VoltageMeasurement
Generic Component Water Sensor
	Sensor
    WaterSensor
Generic Component Window Shade
	Actuator
    Refresh
    WindowShade

dmitry.rozovik · October 5, 2023, 7:24am

Info using Get Attributes App on "Virtual *" devices:

Virtual Acceleration Sensor
    AccelerationSensor 	 
 	-= Attributes =-
 	[acceleration] 	 
 	-= Commands =-
 	[active, inactive]
Virtual audioVolume
    AudioVolume 	 
 	-= Attributes =-
 	[volume, mute] 	 
 	-= Commands =-
 	[mute, setVolume, unmute, volumeDown, volumeUp]
Virtual Button
	DoubleTapableButton
    HoldableButton
    PushableButton
    ReleasableButton 	 
 	-= Attributes =-
 	[doubleTapped, held, numberOfButtons, released, pushed] 	 
 	-= Commands =-
 	[doubleTap, hold, push, release]
Virtual CO Detector
	CarbonMonoxideDetector 	 
 	-= Attributes =-
 	[carbonMonoxide] 	 
 	-= Commands =-
 	[clear, detected, test]
Virtual Color Temperature Light
	Actuator
    ColorTemperature
    Light
    Switch
    SwitchLevel 	 
 	-= Attributes =-
 	[level, switch, colorTemperature, colorName, switch] 	 
 	-= Commands =-
 	[off, on, setColorTemperature, setLevel]
Virtual Contact Sensor
    ContactSensor 	 
 	-= Attributes =-
 	[contact] 	 
 	-= Commands =-
 	[close, open]
Virtual Dimmer
    Refresh
    Switch
    SwitchLevel 	 
 	-= Attributes =-
 	[level, switch] 	 
 	-= Commands =-
 	[off, on, refresh, setLevel]
Virtual Fan Controller
    FanControl 	 
 	-= Attributes =-
 	[speed, supportedFanSpeeds] 	 
 	-= Commands =-
 	[cycleSpeed, setSpeed]
Virtual Garage Door Controller
	ContactSensor
    GarageDoorControl
    PushableButton 	 
 	-= Attributes =-
 	[pushed, numberOfButtons, contact, door] 	 
 	-= Commands =-
 	[close, open, push]
Virtual Humidity Sensor
	RelativeHumidityMeasurement 	 
 	-= Attributes =-
 	[humidity] 	 
 	-= Commands =-
 	[setHumidity]
Virtual Illuminance Sensor
	IlluminanceMeasurement 	 
 	-= Attributes =-
 	[illuminance] 	 
 	-= Commands =-
 	[setLux]
Virtual Lock
	Actuator
    Lock
    LockCodes
    Refresh 	 
 	-= Attributes =-
 	[lockCodes, codeLength, codeChanged, maxCodes, lock, lastCodeName] 	 
 	-= Commands =-
 	[deleteCode, getCodes, lock, refresh, setCode, setCodeLength, testSetMaxCodes, testUnlockWithCode, unlock]
Virtual Lock (no codes)
	Actuator
    Lock 	 
 	-= Attributes =-
 	[lock] 	 
 	-= Commands =-
 	[lock, unlock]
Virtual Moisture Sensor
    WaterSensor 	 
 	-= Attributes =-
 	[water] 	 
 	-= Commands =-
 	[dry, wet]
Virtual Motion Sensor
	MotionSensor
    TemperatureMeasurement
 	-= Attributes =-
 	[motion, temperature]
 	-= Commands =-
 	[active, inactive, setTemperature]
Virtual Multi Sensor
	AccelerationSensor
    ContactSensor
    TemperatureMeasurement 	 
 	-= Attributes =-
 	[temperature, contact, acceleration] 	 
 	-= Commands =-
 	[active, close, inactive, open, setTemperature]
Virtual Omni Sensor
	AccelerationSensor
    CarbonDioxideMeasurement
    CarbonMonoxideDetector
    ContactSensor
    EnergyMeter
    IlluminanceMeasurement
    MotionSensor
    PowerMeter
    PresenceSensor
    RelativeHumidityMeasurement
    SmokeDetector
    TemperatureMeasurement
    WaterSensor 	 
 	-= Attributes =-
 	[energy, humidity, contact, motion, acceleration, carbonDioxide, presence, temperature, carbonMonoxide, water, illuminance, variable, smoke, power] 	 
 	-= Commands =-
 	[COClear, CODetected, accelerationActive, accelerationInactive, arrived, close, departed, dry, motionActive, motionInactive, open, setCarbonDioxide, setEnergy, setIlluminance, setPower, setRelativeHumidity, setTemperature, setVariable, smokeClear, smokeDetected, wet]
Virtual Outlet
	Outlet
    PowerMeter
    Refresh
    Switch 	 
 	-= Attributes =-
 	[switch, power, switch] 	 
 	-= Commands =-
 	[off, on, refresh, setPower]
Virtual Presence
    PresenceSensor
	Sensor
 	-= Attributes =-
 	[presence]
 	-= Commands =-
 	[arrived, departed]
Virtual Presence with Switch
	PresenceSensor
    Sensor
    Switch 	 
 	-= Attributes =-
 	[switch, presence] 	 
 	-= Commands =-
 	[arrived, departed, off, on]
Virtual RGB Light
	Actuator
    ColorControl
    Light
    Switch
    SwitchLevel 	 
 	-= Attributes =-
 	[switch, level, saturation, switch, colorName, hue, color, RGB] 	 
 	-= Commands =-
 	[off, on, setColor, setHue, setLevel, setSaturation]
Virtual RGBW Light
    Actuator
    ColorControl
    ColorMode
    ColorTemperature
    Light
    Switch
    SwitchLevel 	 
 	-= Attributes =-
 	[switch, color, RGB, colorName, colorTemperature, hue, saturation, colorName, level, switch, colorMode] 	 
 	-= Commands =-
 	[off, on, setColor, setColorTemperature, setHue, setLevel, setSaturation]
Virtual Shade
	Actuator
    Switch
    SwitchLevel
    WindowShade 	 
 	-= Attributes =-
 	[level, position, switch, windowShade] 	 
 	-= Commands =-
 	[close, off, on, open, setLevel, setPosition, startPositionChange, stopPositionChange]
Virtual Smoke Detector
	SmokeDetector 	 
 	-= Attributes =-
 	[smoke] 	 
 	-= Commands =-
 	[clear, detected, test]
Virtual Sound Sensor
	SoundSensor 	 
 	-= Attributes =-
 	[sound] 	 
 	-= Commands =-
 	[detected, notDetected]
Virtual Switch
	Refresh
    Switch 	 
 	-= Attributes =-
 	[switch] 	 
 	-= Commands =-
 	[off, on, refresh]
Virtual Temperature Sensor
	TemperatureMeasurement 	 
 	-= Attributes =-
 	[temperature] 	 
 	-= Commands =-
 	[setTemperature]
Virtual Thermostat
	Actuator
    Initialize
    Sensor
    Thermostat
    TemperatureMeasurement 	 
 	-= Attributes =-
 	[hysteresis, supportedThermostatModes, thermostatOperatingState, coolingSetpoint, supportedThermostatFanModes, thermostatSetpoint, heatingSetpoint, temperature, temperature, thermostatFanMode, thermostatMode] 	 
 	-= Commands =-
 	[auto, cool, emergencyHeat, fanAuto, fanCirculate, fanOn, heat, initialize, off, setCoolingSetpoint, setHeatingSetpoint, setHysteresis, setSupportedThermostatFanModes, setSupportedThermostatModes, setTemperature, setThermostatFanMode, setThermostatMode, setThermostatOperatingState, setThermostatSetpoint]
Virtual Valve
	Refresh
    Valve 	 
 	-= Attributes =-
 	[valve] 	 
 	-= Commands =-
 	[close, open, refresh]

Some devices have 'Refresh' component. If I got it correctly virtual devices are not designed to have parent device. Then what exactly can be refreshed? (if sources of attribute data are purely external to device; no parent; no refresh attribute to subscribe to to trigger any external rules/scripts for the purpose)

bertabcd1234 · October 5, 2023, 7:53pm

I suspect the presence of the "Refresh" command in some virtual drivers may be accidental. I just tried running the "Refresh" command on a Virtual Dimmer and didn't notice anything--no errors in the logs but also no history in "Events" of the command even being called (as of a recent platform update, this page actually shows you both events and commands rather than only events; you wouldn't always expect an event from this).

I'm not sure who wrote all of these, but someone like @mike.maxwell may be good to ask. It's possible there is some function in other drivers (e.g., I didn't test the virtual locks).

mike.maxwell · October 5, 2023, 7:58pm

it looks intentional, but only posts the current value of a given attribute, which likely doesn't do anything as its probably a duplicate value

bertabcd1234 · October 6, 2023, 2:00am

For the virtual dimmer I tried above, shouldn't it at least show the "refresh" command on the Events page for the device if it was run? I'm not seeing that, either (unless there's something in 2.3.6 about this, but other commands are showing up--and I'm, of course, referring to the new feature here that shows commands, knowing the difference between commands and events).