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 |
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 | 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. |
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:
- The remote operate endpoint. Since you're talking directly to the API, the state updates as soon as the lock reports the new state.
- Bluetooth operation. When a user operates the lock with the August app, the app relays the new state directly to the API.
- 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 or unlock 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 August 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.
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.