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.