Events Overview

Device Events

Device events fit into four categories: configuration, actions, states, and notifications. These represent the life-cycle of a device. A device “announces” its traits upon configuration, the device is then ready to receive and execute actions. The resulting state updates from actions taken from the cloud, and manually actuated device state changes are also represented as state updates within “Device Events.” There is also the case when a device notifies of a condition, but the state of the device is unchanged; these events fit into the category of notifications.

Device Events allow us to track a running log of device metadata, notifications, and state. These logs provide insights into behavior, and peace of mind that the events and action that we need and want to take place have taken place. You can know that a door was locked this morning after you left for work or that, while on vacation, the heat in the house has been turned down.

Example Events Query 

query deviceEvents($deviceId: ID!) {
  device(id: $deviceId) {
    events {
      pageInfo {
        hasNextPage
      }
      edges {
        node {
          createdAt
          ...DeviceEvents
        }
      }
    }
  }
}

fragment DeviceEvents on DeviceEvent {
  __typename
  ... on DeviceStateUpdatedEvent {
    deviceId
    actionId
    traitName
    traitInstance
    fieldName
    sampledAt
    value
  }
  ... on DeviceStateClearedEvent {
    deviceId
    traitName
    traitInstance
    fieldName
  }
  ... on DeviceActionCreatedEvent {
    createdActionId: actionId
    deviceId
    traitName
    traitInstance
    actionParameters
  }
  ... on DeviceActionUpdatedEvent {
    updatedActionId: actionId
    deviceId
    traitName
    traitInstance
    status
  }
  ... on DeviceConfiguredEvent {
    deviceId
    traits
  }
  ... on DeviceNotificationReportedEvent {
    deviceId
    notificationName
    notificationType
    messageComputed
    actionId
    traitName
    traitInstance
  }
}

Device Configuration Events

A device configuration event takes place when a device is “discovered” (entered into the Yonomi platform). At this point, Yonomi is able to track changes to the device’s traits and its currently reported state. For example, the platform can be used to check whether or not a lock is in a locked or unlocked state.

Configuration Events report an array of traits that the device implements and a timestamp of when the configuration took place.

createAt: DateTime!
deviceId: ID!
traits: [DeviceTrait!]!

Device Action Created Events

There are two types of device action events: DeviceActionCreatedEvent and DeviceActionUpdatedEvent.

The DeviceActionCreatedEvent event type communicates the platform has received, validated, and relayed a command to the device. A created action persists fields of data that capture the details of the action.

Below are the fields that a DeviceActionCreatedEvent event persists:

createdAt: DateTime!
deviceId: ID!
userId: ID!
actionId: ID!
traitName: TraitName!
traitInstance: String!
actionParameters: JSONObject!

The __typename is DeviceActionCreatedEvent. The createdAt field is the time the action was created. The deviceId is the reference to the device that this action is associated with. The userId is the ID of the user that created the action. The actionId is a unique identifier for this action. The traitName is the name of the trait that the action was targeting, and the traitInstance was the instance of that trait for the given device. The actionParameters field represents the parameters of the action. For example: a common action would be to turn a device’s power off. In that case, that traitName field would be Power and the actionParameters would be { on: false }.

Device Action Updated Events

The DeviceActionUpdatedEvent event type communicates the outcome of an action that has been sent to a device. It’s possible that the action succeeded or failed. Perhaps the device was not reachable. Below are the fields of the DeviceActionUpdatedEvent event type:

createdAt: DateTime!
deviceId: ID!
actionId: ID!
traitName: TraitName!
traitInstance: String!
status: DeviceActionStatus!

The __typename is ‘DeviceActionUpdatedEvent’. The createdAt field is the time the DeviceActionUpdatedEvent took place on the platform. The actionId is a unique identifier for this action. The traitName is the name of the trait that the action was targeting, and the traitInstance was the instance of that trait for the given device. The status field communicates the state of the action at the time of update. Usually, these values are resolved, rejected, or pending.

Device State Updated Event

The DeviceStateUpdatedEvent event reflects that the state of a device has been reported to the system. This event tells us when the state changed, which particular trait and traitInstance’s state changed, and which state field the value changed on. Take, for example, a lock state updated event that communicates that a lock has been unlocked.

createdAt: DateTime!
deviceId: ID!
traitName: TraitName!
traitInstance: String!
fieldName: String!
value: JSON
actionId: ID
sampledAt: DateTime

In the above you can see that the DeviceStateUpdatedEvent event shows time, the createdAt field, a lock with ID deviceId had its state updated for fieldName to value.

Here is an example event:

createdAt: "2021-06-28T20:44:14.296Z"
deviceId: "17aaada8-5a9a-4ef1-9ac2-61aaa1c4ab83"
traitName: "Lock"
traitInstance: "default"
fieldName: isLocked
value: true
actionId: "bef34522-235b-2bcd-eff3-9bcad73d93da"
sampledAt: "2021-06-28T21:04:34.142Z"

In the example you can see that the DeviceStateUpdatedEvent event shows that lock with ID 17aaada8-5a9a-4ef1-9ac2-61aaa1c4ab83 had its state isLocked updated to true on June 28th 2021.

These events allow us to see the activity of our devices. They let us know when events occurred and precisely what event occurred. In the instance of locking a door, for example, you could realize that you left a door unlocked and send an action to lock that door. When the DeviceStateUpdateEvent event occurs, then you have the peace of mind of knowing that the door is now locked.

Device State Cleared Event

The DeviceStateClearedEvent event reflects the clearing of a single field of state from a device. This event type is used to capture a ‘reset’ of state initiated by the device or a factory reset.

createdAt: DateTime!
deviceId: ID!
traitName: TraitName!
traitInstance: String!
fieldName: String!

The above represents the clearing of device state. This is done per device per trait per fieldName.

If the returned values for a DeviceStateCleared Event were returned like this:

createdAt: "2021-06-28T20:44:14.296Z"
deviceId: "17aaada8-5a9a-4ef1-9ac2-61aaa1c4ab83"
traitName: "Lock"
traitInstance: "default"
fieldName: "isJammed"

The above represents the clearing of the state isJammed on a device that implements the Lock trait.

The type will always be ‘DeviceStateCleared’. The field createdAt is the time the state was updated by the platform. The traitName is the name of the trait that the action was targeting, and the traitInstance was the instance of that trait for the given device. fieldName is the state field that was cleared in the DeviceStateClearedEvent event.

← Trait Errors
Pagination →