LockV1 Trait
Information regarding devices that have latch and/or deadbolt, actions to modify the device, and notification when an event occurred related to the lock or deadbolt status.
Trait Type: Standard
Action Mutations
Note: See Overview: Device Action Lifecycle for more information on action flows
LockV1SetLockMode action
Modifies the lockMode state.
Mutation Inputs
Input Name | Description | Data Type | Nullable |
deviceId | uuid of the device to which mutation should apply | ID! | false |
traitActionArgs | See table below for specific fields | LockV1LockModeArgs! | false |
LockV1LockModeArgs Fields
Field Name | Description | Data Type | Nullable |
lockMode | the function mode setting to be applied to the device | lockModeActionEnum! | false |
lockModeActionEnum Values
Enumerated String | Description |
OFFICE | Device is normally secure. Inside trim always allows free egress. Interior push button may be used to select a passage or secured status. Meets need for lockdown function for safety and security. NOTE: Valid toggle credentials on the exterior may also be used to change status. |
PRIVACY | Device is normally secure. Inside trim always allows free egress. Interior push button or thumbturn may be used to select a privacy status. The interior push button will disable normal electronic access from the exterior. Opening the door, pressing the interior push button a second time, or turning the thumbturn deactivates the privacy status. |
STOREROOM | Device is normally secure. Inside trim always allows free egress. Valid toggle credentials on the exterior may be used to change to a passage or secured status. |
APARTMENT | Device is normally secure. Inside trim always allows free egress. Inside push button or thumbturn may be used to select a passage or secured status. Opening the door, pressing the inside push button, or turning the thumbturn causes the device to toggle unsecured. While toggled unsecured, the device can only be secured while the door is closed by pressing the interior push button, turning the thumbturn, or using a normal credential on the exterior. Normal electronic access from the exterior is always allowed. |
Request Example
mutation LockV1SetLockMode {
LockV1SetLockMode(
deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d"
traitActionArgs: { lockMode: OFFICE }
){
deviceId
actionId
}
}Response Example
{
"data": {
"LockV1SetLockMode": {
"actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d"
}
}
}LockV1ExecuteLockingAction
Commands lock to perform the appropriate lock state change as if a user presented a credential matching the lockingAction input.
Mutation Inputs
Input Name | Description | Data Type | Nullable |
deviceId | uuid of the device to which mutation should apply | ID! | false |
traitActionArgs | See table below for specific fields | LockV1ExecuteLockActionArgs! | false |
LockV1ExecuteLockActionArgs Fields
Field Name | Description | Data Type | Nullable |
lockingAction | the desired type of action to be performed on current lock state. | lockingActionEnums! | false |
lockingActionEnums Values
Enumerated String | Description |
NORMAL | Generally, when device is in SECURED state, device is put into MOMENTARILY_UNLOCK state and automatically relocks after amount of time based on autoRelockDelay setting (see AutoRelockDelaySettingsV1 Trait). |
NORMAL_EXTENDED | Generally, when device is in SECURED state, device is put into MOMENTARILY_UNLOCK state and automatically relocks after amount of time based on extendedAutoRelockDelay setting (see ExtendedAutoRelockDelaySettingsV1 Trait). |
PASS_THRU | Generally, when device is in SECURED or FROZEN_SECURED state, device is put into MOMENTARILY_UNLOCK state and automatically relocks after amount of time based on autoRelockDelay setting (see AutoRelockDelaySettingsV1 Trait). |
PASS_THRU_EXTENDED | Generally, when device is in SECURED or FROZEN_SECURED state, device is put into MOMENTARILY_UNLOCK state and automatically relocks after amount of time based on autoRelockDelay setting (see ExtendedAutoRelockDelaySettingsV1 Trait). |
TOGGLE | Generally, when device is in a SECURED or PASSAGE state, device toggles between SECURE and PASSAGE states. |
LOCK_DOWN | Generally, no matter what starting state the device is in, device will be put into FROZEN_SECURED state. |
FREEZE | Generally, toggles device between a FROZEN state and the corresponding normal state (e.g. FROZEN_SECURED and SECURED or FROZEN_PASSAGE and PASSAGE) |
Request Example
mutation LockV1ExecuteLockingAction {
LockV1ExecuteLockingAction(
deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d"
traitActionArgs: { lockingAction: NORMAL }
){
deviceId
actionId
}
}Response Example
{
"data": {
"LockV1ExecuteLockingAction": {
"actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d"
}
}
}Reported States
Note: See Overview: Device Reported State for more information on reported state flows.
State Definitions
lockMode State
The currently set lock function (e.g. Office).
Data Type: Enum
Valid Values
Enumerated String | Description |
UNSUPPORTED | Device does not report data for this state. |
OFFICE | Device is normally secure. Inside trim always allows free egress. Interior push button may be used to select a passage or secured status. Meets need for lockdown function for safety and security. NOTE: Valid toggle credentials on the exterior may also be used to change status. |
PRIVACY | Device is normally secure. Inside trim always allows free egress. Interior push button or thumbturn may be used to select a privacy status. The interior push button will disable normal electronic access from the exterior. Opening the door, pressing the interior push button a second time, or turning the thumbturn deactivates the privacy status. |
STOREROOM | Device is normally secure. Inside trim always allows free egress. Valid toggle credentials on the exterior may be used to change to a passage or secured status. |
APARTMENT | Device is normally secure. Inside trim always allows free egress. Inside push button or thumbturn may be used to select a passage or secured status. Opening the door, pressing the inside push button, or turning the thumbturn causes the device to toggle unsecured. While toggled unsecured, the device can only be secured while the door is closed by pressing the interior push button, turning the thumbturn, or using a normal credential on the exterior. Normal electronic access from the exterior is always allowed. |
lockState State
The currently security state of the device (e.g. Secured). See published state table documentation for information on how device should behave based on the selected mode, current state, and event conditions that occur.
Data Type: Enum
Valid Values
Enumerated String | Description |
UNKNOWN | Device reports that lock state is unknown. |
MOMENTARY_UNLOCK | Device reports that lock state is momentarily unlocked. |
SECURED | Device reports that lock state is secured. |
PASSAGE | Device reports that lock state is passage. |
FROZEN_SECURED | Device reports that lock state is frozen secured. |
FROZEN_PASSAGE | Device reports that lock state is frozen passage. |
FROZEN_NORMAL | Device reports that lock state is frozen normal. |
HOLIDAY_RESTRICTED | Device reports that lock state is holiday restricted. |
PRIVACY_SECURED | Device reports that lock state is privacy secured. |
UNSUPPORTED | Device has not reported lock state, it is not supported by the device's current firmware. |
deadboltState State
The current deadbolt state (e.g. retracted).
Data Type: Enum
Valid Values
Enumerated String | Description |
UNSUPPORTED | Device does not report data for this state. |
LOCKED | Deadbolt is extended |
UNLOCKED | Deadbolt is retracted |
JAMMED | Deadbolt is jammed |
UNKNOWN | Device can't determine deadbolt position |
ipbState State
The current interior push button state (e.g. activated)
Data Type: Enum
Valid Values
Enumerated String | Description |
UNSUPPORTED | Device does not report data for this state. |
ACTIVATED | Internal push button is activated |
DEACTIVATED | Internal push button is de-activated |
totalMotorCycles State
The total number of cycles lock motor has completed over life of device
Data Type: Int
Device State Query GQL Examples
Request Example
query Device {
device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") {
id
traits {
... on LockV1DeviceTrait {
name
state {
lockMode {
reported {
value
}
}
lockState {
reported {
value
}
}
deadboltState {
reported {
value
}
}
ipbState {
reported {
value
}
}
totalMotorCycles {
reported {
value
}
}
}
}
}
}
}Response Example
{
"data": {
"device": {
"id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d",
"traits": [
{
"name": "LockV1",
"state": {
"lockMode": {
"reported": {
"value": "OFFICE"
}
},
"lockState": {
"reported": {
"value": "SECURED"
}
},
"deadboltState": {
"reported": {
"value": "UNSUPPORTED"
}
},
"ipbState": {
"reported": {
"value": "UNSUPPORTED"
}
},
"totalMotorCycles": {
"reported": {
"value": 1055
}
}
}
}
]
}
}
}Notification Events
Note: See Overview: Device Notifications for more information on notfication event flows.
warningUnauthorzedUserEvent
Warning that an unauthorized user attempted to gain access.
Details Fields
Field Name | Description | Data Type |
credentialPresented | Information on the triggering credential. | string |
Event Example
{
"eventType": "DEVICE_NOTIFICATION_REPORTED",
"notifications": [
{
"category": "notification",
"notificationName": "warningUnauthorizedUserEvent",
"notificationType": "WARNING",
"type": "notification reported",
"createdAt": "2024-12-20T14:49:55.000Z",
"sampledAt": "2024-12-20T14:49:39.663Z",
"installationId": "819cd607-aede-482e-9aa0-8b65d420e300",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d",
"traitName": "lockV1",
"message": "A warningUnauthorizedUserEvent event occurred at device.",
"id": "92197db2-63a4-4832-9a20-59dd188b6504",
"details": {
"credentialPresented": "AAAAAAAAAAAAAAA1"
}
}
]
}infoUserAccessLockEvent
Events related to valid credentials being presented to the lock.
Details Fields
Field Name | Description | Data Type |
cause | Information on the event cause | string |
effect | Information on the resulting lockState | string |
credentialId | Information on the triggering credential. | string |
Event Example
{
"eventType": "DEVICE_NOTIFICATION_REPORTED",
"notifications": [
{
"category": "notification",
"notificationName": "infoUserAccessLockEvent",
"notificationType": "INFO",
"type": "notification reported",
"createdAt": "2024-12-20T14:49:55.000Z",
"sampledAt": "2024-12-20T14:49:39.663Z",
"installationId": "819cd607-aede-482e-9aa0-8b65d420e300",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d",
"traitName": "lockV1",
"message": "A infoUserAccessLockEvent event occurred at device.",
"id": "92197db2-63a4-4832-9a20-59dd188b6504",
"details": {
"cause": "Normal User Access",
"effect": "Passage",
"credentialId": "AAAAAAAAAAAAAAA1"
}
}
]
}infoDeviceScheduleEvent
Events related to device schedule.
Details Fields
Field Name | Description | Data Type |
cause | Information on the event cause | string |
effect | Information on the resulting lockState | string |
Event Example
{
"eventType": "DEVICE_NOTIFICATION_REPORTED",
"notifications": [
{
"category": "notification",
"notificationName": "infoDeviceScheduleEvent",
"notificationType": "INFO",
"type": "notification reported",
"createdAt": "2024-12-20T14:49:55.000Z",
"sampledAt": "2024-12-20T14:49:39.663Z",
"installationId": "819cd607-aede-482e-9aa0-8b65d420e300",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d",
"traitName": "lockV1",
"message": "A infoDeviceScheduleEvent event occurred at device.",
"id": "92197db2-63a4-4832-9a20-59dd188b6504",
"details": {
"cause": "Auto Unlock Event",
"effect": "Passage"
}
}
]
}infoHolidayScheduleEvent
Events related to holiday schedule.
Details Fields
Field Name | Description | Data Type |
cause | Information on the event cause | string |
effect | Information on the resulting lockState | string |
Event Example
{
"eventType": "DEVICE_NOTIFICATION_REPORTED",
"notifications": [
{
"category": "notification",
"notificationName": "infoHolidayScheduleEvent",
"notificationType": "INFO",
"type": "notification reported",
"createdAt": "2024-12-20T14:49:55.000Z",
"sampledAt": "2024-12-20T14:49:39.663Z",
"installationId": "819cd607-aede-482e-9aa0-8b65d420e300",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d",
"traitName": "lockV1",
"message": "A infoHolidayScheduleEvent event occurred at device.",
"id": "92197db2-63a4-4832-9a20-59dd188b6504",
"details": {
"cause": "Holiday Passage Time Event",
"effect": "Passage"
}
}
]
}infoCloudCommandEvent
Events related to cloud command that modifies the lockStatus.
Details Fields
Field Name | Description | Data Type |
cause | Information on the event cause | string |
effect | Information on the resulting lockState | string |
Event Example
{
"eventType": "DEVICE_NOTIFICATION_REPORTED",
"notifications": [
{
"category": "notification",
"notificationName": "infoCloudCommandEvent",
"notificationType": "INFO",
"type": "notification reported",
"createdAt": "2024-12-20T14:49:55.000Z",
"sampledAt": "2024-12-20T14:49:39.663Z",
"installationId": "819cd607-aede-482e-9aa0-8b65d420e300",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d",
"traitName": "lockV1",
"message": "A infoCloudCommandEvent event occurred at device.",
"id": "92197db2-63a4-4832-9a20-59dd188b6504",
"details": {
"cause": "Remote Normal User Access Command",
"effect": "Passage"
}
}
]
}infoDeviceEvent
Events related to manual operation of the device.
Details Fields
Field Name | Description | Data Type |
cause | Information on the event cause | string |
effect | Information on the resulting lockState | string |
Event Example
{
"eventType": "DEVICE_NOTIFICATION_REPORTED",
"notifications": [
{
"category": "notification",
"notificationName": "infoDeviceEvent",
"notificationType": "INFO",
"type": "notification reported",
"createdAt": "2024-12-20T14:49:55.000Z",
"sampledAt": "2024-12-20T14:49:39.663Z",
"installationId": "819cd607-aede-482e-9aa0-8b65d420e300",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d",
"traitName": "lockV1",
"message": "A infoDeviceEvent event occurred at device.",
"id": "92197db2-63a4-4832-9a20-59dd188b6504",
"details": {
"cause": "Internal Push Button Active",
"effect": "Privacy On"
}
}
]
}infoKeyOverrideEvent
Events related to key override operation.
Details Fields
Not applicable to this event
Event Example
{
"eventType": "DEVICE_NOTIFICATION_REPORTED",
"notifications": [
{
"category": "notification",
"notificationName": "infoKeyOverrideEvent",
"notificationType": "INFO",
"type": "notification reported",
"createdAt": "2024-12-20T14:49:55.000Z",
"sampledAt": "2024-12-20T14:49:39.663Z",
"installationId": "819cd607-aede-482e-9aa0-8b65d420e300",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d",
"traitName": "lockV1",
"message": "A infoKeyOverrideEvent event occurred at device.",
"id": "92197db2-63a4-4832-9a20-59dd188b6504",
"details": {}
}
]
}infoRexEvent
Events related to request to exit operation.
Details Fields
Not applicable to this event
Event Example
{
"eventType": "DEVICE_NOTIFICATION_REPORTED",
"notifications": [
{
"category": "notification",
"notificationName": "infoRexEvent",
"notificationType": "INFO",
"type": "notification reported",
"createdAt": "2024-12-20T14:49:55.000Z",
"sampledAt": "2024-12-20T14:49:39.663Z",
"installationId": "819cd607-aede-482e-9aa0-8b65d420e300",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d",
"traitName": "lockV1",
"message": "A infoRexEvent event occurred at device.",
"id": "92197db2-63a4-4832-9a20-59dd188b6504",
"details": {}
}
]
}infoBlockConstructionModeEvent
Events related to blockConstructionMode setting changes.
Details Fields
Field Name | Description | Data Type |
blockConstructionModeState | Status of the blockConstructionMode setting | ENABLED, DISABLED |
Event Example
{
"eventType": "DEVICE_NOTIFICATION_REPORTED",
"notifications": [
{
"category": "notification",
"notificationName": "infoBlockConstructionModeEvent",
"notificationType": "INFO",
"type": "notification reported",
"createdAt": "2024-12-20T14:49:55.000Z",
"sampledAt": "2024-12-20T14:49:39.663Z",
"installationId": "819cd607-aede-482e-9aa0-8b65d420e300",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d",
"traitName": "lockV1",
"message": "A infoBlockConstructionModeEvent event occurred at device.",
"id": "92197db2-63a4-4832-9a20-59dd188b6504",
"details": {
"blockConstructionModeState": "ENABLED"
}
}
]
}warningBruteForceAttackIdentified
Warning that lock detected a brute force attack and has initiated mitigations.
Details Fields
Not applicable to this event
Event Example
{
"eventType": "DEVICE_NOTIFICATION_REPORTED",
"notifications": [
{
"category": "notification",
"notificationName": "warningBruteForceAttackIdentified",
"notificationType": "WARNING",
"type": "notification reported",
"createdAt": "2024-12-20T14:49:55.000Z",
"sampledAt": "2024-12-20T14:49:39.663Z",
"installationId": "819cd607-aede-482e-9aa0-8b65d420e300",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d",
"traitName": "lockV1",
"message": "Device has detected a brute force attack. Credential authentication has been blocked.",
"id": "92197db2-63a4-4832-9a20-59dd188b6504",
"details": {}
}
]
}infoBruteForceAttackResolved
Events related to a previously detected brute force attack having stopped and device deactivating mitigations.
Details Fields
Not applicable to this event
Event Example
{
"eventType": "DEVICE_NOTIFICATION_REPORTED",
"notifications": [
{
"category": "notification",
"notificationName": "infoBruteForceAttackResolved",
"notificationType": "INFO",
"type": "notification reported",
"createdAt": "2024-12-20T14:49:55.000Z",
"sampledAt": "2024-12-20T14:49:39.663Z",
"installationId": "819cd607-aede-482e-9aa0-8b65d420e300",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d",
"traitName": "lockV1",
"message": "Device is no longer under brute force attack. Credential authentication has been unblocked.",
"id": "92197db2-63a4-4832-9a20-59dd188b6504",
"details": {}
}
]
}warningMotorFailed
Warning that lock motor failed to change lockState as expected.
Details Fields
Field Name | Description | Data Type |
motorFailureType | Status of the blockConstructionMode setting | FAILED_TO_LOCK, FAILED_TO_UNLOCK |
Event Example
{
"eventType": "DEVICE_NOTIFICATION_REPORTED",
"notifications": [
{
"category": "notification",
"notificationName": "warningMotorFailed",
"notificationType": "WARNING",
"type": "notification reported",
"createdAt": "2024-12-20T14:49:55.000Z",
"sampledAt": "2024-12-20T14:49:39.663Z",
"installationId": "819cd607-aede-482e-9aa0-8b65d420e300",
"deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d",
"traitName": "lockV1",
"message": "Device motor state mismatch found during lock/unlock operation.",
"id": "92197db2-63a4-4832-9a20-59dd188b6504",
"details": {
"motorFailureType": "FAILED_TO_UNLOCK"
}
}
]
}On this page
- LockV1 Trait