Skip to content

Lock and Door State#

All locks know whether their deadbolt is locked or unlocked. This is called lock state.

Some locks know whether their door is open or closed. This is called door state. Only locks with DoorSense™ support door state.

Lock State#

These are the possible values for lock state that you might get back from the API. Unfortunately, some older endpoints return values that start with kAugLockState_ instead of just locked or unlocked.

State Meaning
locked or kAugLockState_Locked The deadbolt is fully in the locked position
unlocked or kAugLockState_Unlocked The deadbolt is fully in the unlocked position
unlatched or kAugLockState_Unlatched The latch is fully retracted1
locking or kAugLockState_Locking The deadbolt is rotating towards the fully locked position
unlocking or kAugLockState_Unlocking The deadbolt is rotating towards the fully unlocked position
unlatching or kAugLockState_Unlatching The latch is retracting1
securemode or kAugLockState_Securemode Puts the lock in a mode where it cannot be operated manually2
shabbatmode or kAugLockState_Shabbatmode A privacy mode in which the lock appears to operate manually without electrical functionality, cannot be controlled remotely, and does not generate activity logs.3
unknown The API was not able to contact the bridge. In some case this might also include a successful connection to the bridge but the connection to the lock timed out.
kAugLockState_UnknownStaticPosition The deadbolt position cannot be determined, but it is not moving.
not-advertising The bridge is not able to reach the lock via Bluetooth.
invalid Some state the state engine did not expect. Probably a bug in the API if you ever see this.
  1. Applicable only to locks equipped with a latch mechanism.
  2. Applicable only to locks suporting this mode
  3. Applicable only to locks suporting this mode, BLE connection is required to change state

Door State#

These are the possible values for door state that you might get back from the API. Unfortunately, some older endpoints return values that start with kAugDoorState_ instead of just open or closed.

State Meaning
open or kAugDoorState_Open The door is open.
closed or kAugDoorState_Closed The door is closed.
init or kAugDoorState_Init The DoorSense™ sensor has not been setup. How to install DoorSense™
unknown or kAugDoorState_Unknown The door is in an unknown state.

When does state update?#

The API's record of lock state and door state updates and calls webhooks in these cases:

  1. The remote operate endpoint. Since you're talking directly to the API, the state updates as soon as the lock reports the new state.
  2. Bluetooth operation. When a user operates the lock with the Yale Home app, the app relays the new state directly to the API.
  3. Draining logs: The lock has its own logs of operations in firmware. Occasionally these logs get sent to the API.
    • If the user has a bridge, then a few seconds after a manual lock, unlock or unlatched operation completes, the bridge will send the lock's logs to the API and the API will use this to derive the new state of the lock. This can trigger a webhook on V2+ locks (HomeKit version). We are still tuning the sensitivity of updates for V1 locks which do not have accurate system clocks, so we trust the logs less.
    • If there is no bridge (or if the bridge is offline) then the operation remains logged on the lock and the next time a user connects to the lock via Bluetooth and the Yale Home App, the app will drain the logs and send them to the API. Normally this does not update the state because the app will have already checked the state of the lock and sent the updated state of the lock to the API (so this state is newer than what is in the lock's logs).

Ideally locks have only 2 states: locked or unlocked (and in case of certain lock configurations, for short periods unlatched).

In the real world, things are more complicated. The lock could be unreachable (so unknown or not-advertising), or it could be in an in-between state, neither locked nor unlocked.

Best Practice

In general, the best practice is to pay attention to the error message when you make an API call to determine what the problem might be, and simplify the possible states to locked, unlocked, and unknown.