Controlling Devices

All devices within the Yonomi platform are composed of Traits. This provides a simple and unified interface for controlling any device. See Traits Overview for an in-depth description of how traits are used within the platform.

Traits-based device control#

All devices in the platform are represented as a collection of traits. This allows control of all Yonomi Platform devices through the same traits-based interface. The actions that can be performed on a device are defined by the individual traits that a device implements. Because a device can implement multiple traits, a device’s capabilities can be thought of as the collection of all the exposed actions from the traits that it implements.

At the graph#

The traits that a device implements are available as properties of a device within the graph. Similarly, all actions available through a device’s traits are implemented as mutations within the graph. Our GraphQL schema is automatically generated based on the trait catalog, and will provide all the types, queries, mutations, and parameters that are needed to control and interact with a device.

Trait actions#

Actions are the commands that are available to be executed on a device based on the traits it implements. They are users’ public interface for cloud device control. Actions targeting a device may result in a change in the device’s desired state, but actions themselves do not directly affect reported state. Each trait defines a set of actions containing action parameters as well as action validations.

For example, a device that implements a Power trait can be controlled using the actionPowerSetOn trait action. For a complete collection of traits and their actions refer to the Traits Reference.

Action parameters#

Action parameters specify the values used for actions and will be validated at runtime against the device’s properties.

Action parameters are provided to the GraphQL mutation for a trait action. Given an actionPowerSetOn mutation, action parameters deviceId and on are specified as:

actionPowerSetOn (deviceId: $deviceId on: true)

Action validations#

Action validations are performed at runtime to ensure an action is valid. They validate the action and action parameters against the device’s trait properties and states.

Examples#

This example demonstrates how to control a simple device exposing a Power trait.

Trait data, for a device with a Power trait, is partially represented on the device in the graph as follows:

{
  "traits": [
    {
      "name": "POWER",
      "instance": "default",
      "properties: {
        "supportsDiscreteOnOff": true,
      }
    }
  ]
}

Because this device implements a Power trait, which contains the setOn action, and this device has configured the Power trait properties with supportsDiscreteOnOff: true we can use the generated actionPowerSetOn mutation to control the device. Here’s an example that uses the actionPowerSetOn mutation to turn the device on and receive information about the action as well as the desired and reported state of the device.

mutation {
  actionPowerSetOn (deviceId: $deviceId on: true) {
    actionId
    device {
      traits {
          name
          instance
          ... on PowerDeviceTrait {
            properties { supportsDiscreteOnOff }
            state {
              isOn {
                reported { value sampledAt createdAt }
                desired { value delta updatedAt }
              }
            }
          }
       }
    }
  }
}

The next example shows the differences in device control implied by differently configured traits.

Consider another device that also implements a Power trait but is configured with supportsDiscreteOnOff: false trait property.

Attempting to actuate the device using the same actionPowerSetOn mutation will cause a runtime validation error, because the Power trait setOn action requires that supportsDiscreteOnOff be set to true.

Action Resolution#

Actions on Yonomi Platform are resolved asynchonously and are tagged with one of the following with status values to track their resolution progress:

• Pending
• Resolved
• Rejected
• Canceled
• Error
• Failed
• Timeout To query for action status, you can query for device events and filter on ActionUpdatedEvent
  
  

The following sequence diagram illustrates a common workflow for finding devices, executing actions on those devices, and tracking the progress of those actions.