Traits Overview
This guide is an overview of the features and functionality of Traits at Yonomi.
Why Traits?
The Yonomi Platform is positioned as a normalized way to interact with the ever-growing ecosystem of smart-home devices across a vast variety of vendors. Until recently, however, interacting with different devices that should feel similar would often times require slightly different accommodations or API expectations.
We sought to add a new layer of interaction on top of our existing platform that would directly improve some of the challenges faced when encountering the above problem: how can we further simplify the experience of interacting with devices and ensure common functionality is properly modeled in a useful way?
What Are Traits?
Traits are Yonomi’s answer to this challenge. We built traits in order to unify the ways in which our API users think about and interact with devices into a common set of capabilities. You think about a trait as a collection of standardized interactions (actions) and data (state) that a certain type of device can implement.
For example, even though there are several different types of smart lights that Yonomi supports, across several different vendors, nearly all of them have the ability to be turned on and off. We can use a Power trait to unify the way in which users can interact with those devices at the API level and thus remove the burden of handling device variations across things that ought to “feel the same”.
Traits are composable; a single device may implement several traits. This allows us to keep traits focused and simple, while still supporting complex device types through trait composition.
When Are Traits Used?
The smart-home device ecosystem continues to grow at an ever-accelerating pace… but by leveraging traits on the Yonomi Platform, you can create robust apps and solutions that interact with a huge variety of devices in an easily understandable way.
Today, you can use traits to execute actions on your devices in a simpler, far more consistent way than you’ve had to in the past. We currently support a growing number of traits, and there are several changes and new features coming to the Yonomi platform that will be powered by this new functionality. In addition, the types of devices and capabilities we support through traits will be growing over time.
How To Leverage Traits
A trait encapsulates a collection of shared interactions (actions) and properties (state) that a device can implement. There are three primary features that traits are made of:
Properties
Trait properties can be thought of as configuration data that qualifies or potentially limits exactly how certain devices implement a trait. While traits are designed in such a way to allow for as much uniformity as possible when interacting with different devices, there may still be some discrepancies in exactly how a trait works for a specific type of device. These configurations are expressed as read-only trait properties.
For example, several smart thermostats allow for setting a mode, but not all thermostats have the same available modes. For the
ThermostatSetting trait, it has a trait property of availableThermostatModes that may define a list of modes that can be used with the setMode action.
See the Trait Reference documentation for a detailed breakdown of all trait properties.
Actions
Trait actions are the way in which you can interact with devices from the cloud. An action can be executed on a device, and may take action parameters. A trait action could cause a change in the device (such as turning a light off or setting the temperature on a thermostat), or it could simply cause some temporary effect to be produced (such as playing an alert or flashing a light).
State
Trait state is a representation of some persisted data on the device. This state is read-only and cannot be set directly from the cloud(however, certain actions may result in changes to device state). Device state could represent the current status of the device (such as whether or not is currently powered on), or it could reflect real-time sensor data (such as a humidity sensor’s most recent reading).
While certain actions may be executed that result in state updates, this isn’t always the case. For example, a lock may have an Unlock action executed on it, but due a hardware issue or device-local override, it’s Locked state may remain true.
It is the responsibility of the device to report its trait state back up to the platform. While the cloud will retain a “digital copy” of the device state,the device is considered the source of truth for a device’s state.
Reference Documentation
For a complete and detailed reference of all of the current traits at Yonomi, see Traits Reference.
Support
If you have questions about how traits can be used to interact with your devices through the Yonomi Platform, reach out to us via our contact page and we’d be happy to help.