Simplified traits

For ease of use, simplified versions of some traits are available for use with the Automation API.

A simplified trait stands in for a standard Home API trait, similar to how the facade pattern works. Simplified traits provide commands that make common tasks easier for certain device types. Simplified traits are Home API traits, and, like other Home API traits, they work for both Matter and Cloud-to-cloud devices.

A simplified trait offers an alternative subset of attributes and commands that is more device-specific than those of the corresponding standard trait. For example, the standard LevelControl trait is a generic trait that can be used for any device that has a setting that varies continuously across a range of numeric values. Brightness is a simplified trait that stands in for LevelControl and provides just the commands and attributes that a DimmableLight device requires. Brightness has a moveToBrightness command that takes a single brightnessPercent argument, whereas LevelControl has multiple move commands, most of which have at least four parameters in order to accommodate a wider range of use-cases.

The following table shows each simplified trait and the underlying standard trait(s). Each trait name links to the corresponding API documentation:

Simplified traits and the Discovery API

The Discovery API reports simplified traits as well as their underlying standard traits, as long as both traits were registered in the FactoryRegistry. For example, if a DimmableLight device is present in the structure, and the developer registered both the LevelControl and Brightness traits in the FactoryRegistry, the Discovery API would indicate the presence of both traits. The developer may choose to use either trait in their automation.

See Discovery API for more information.

Retrieve a device that supports a simplified trait

When using the Device API to obtain devices in a structure that support a simplified trait such as SimplifiedThermostat, you can't use the has(trait) method. Instead, use the has(deviceType) method:

val thermostat = home.devices().list().first { device -> device.has(ThermostatDevice) }