Lock Capability Schema

[benfrancis]

No description provided.

[benfrancis]

See also: WebThingsIO/api#53

[dhylands]

I'm about to add door lock support to the Zigbee adapter.

Initially I'd like to proposed that we add a capability of DoorLock along with a locked property which would be something like a LockedProperty or a DoorLockedProperty either with a boolean or with an enumeration.

Zigbee locks support 3 locked states:
0 - Not fully locked
1 - Locked
2 - Unlocked

[mrstegeman]

For HomeKit, the following are defined:

• Current State
  • Unsecured
  • Secured
  • Jammed
  • Unknown
• Lock Target State
  • Unsecured
  • Secured

There are also some further characteristics, which may be interesting/useful:

• Audio Feedback
  This characteristic describes whether audio feedback (e.g. a beep, or other external sound mechanism) is enabled.
• Last Known Action
  • Secured using physical movement, interior
  • Unsecured using physical movement, interior
  • Secured using physical movement, exterior
  • Unsecured using physical movement, exterior
  • Secured with keypad
  • Unsecured with keypad
  • Secured remotely
  • Unsecured remotely
  • Secured with Automatic Secure timeout
• Auto Security Timeout
  A value greater than 0 indicates if the lock mechanism enters the unsecured state, it will automatically attempt to enter the secured state after n seconds, where n is the value provided in the write. A value of 0 indicates this feature is disabled.
• Current Door State
  • Open. The door is fully open.
  • Closed. The door is fully closed.
  • Opening. The door is actively opening.
  • Closing. The door is actively closing.
  • Stopped. The door is not moving, and it is not fully open nor fully closed.
• Motion Detected

[raidnet-ms]

You also need to check a door sensor before locking armored doors. The sensor may be used also as alarm (event)

[benfrancis]

Schema proposal below...

DoorLock

• Properties:
  • LockedProperty
    • required: yes
    • read-only: yes
  • TargetLockedProperty
    • required: yes
    • read-only: no
• Actions:
  • LockAction
    • required: no
  • UnlockAction
    • required: no
• Events:
  • LockJammedEvent
    • required: no

LockedProperty

• type: string
• enum: ["locked", "unlocked", "unknown"]

TargetLockedProperty

• type: string
• enum: ["locked", "unlocked"]

LockAction

• input: none

UnlockAction

• input: none

LockJammedEvent

• data: none

Questions:

• Should the capability be called DoorLock, Lock or SmartLock? I'm thinking probably not SmartLock because any IoT device could be called "smart" (I'm slightly regretting SmartPlug). Could Lock also cover other types of locks like windows?
• Are "locked", "unlocked" and "unknown" enough states for LockedProperty? Other possibilities include "locking", "unlocking" and "jammed". My thinking is that "unknown" could cover all three of those states, especially in conjunction with a LockJammedEvent
• Should TargetLockedProperty just have a boolean value like OpenProperty given it only has two values?
• Should there be a LockAction and UnlockAction? I'm thinking these might be useful for types of locks which take a particularly long time to actuate. If so, should there be two separate actions or one LockAction which takes a boolean or enum input? Or is a LockedProperty enough on its own?
• Is LockJammedEvent actually necessary? Would a "jammed" state of LockedProperty be better?

[mrstegeman]

• Should the capability be called DoorLock, Lock or SmartLock? I'm thinking probably not SmartLock because any IoT device could be called "smart" (I'm slightly regretting SmartPlug). Could Lock also cover other types of locks like windows?

I like "Lock", personally, since nothing about this is specific to a door.

• Are "locked", "unlocked" and "unknown" enough states for LockedProperty? Other possibilities include "locking", "unlocking" and "jammed". My thinking is that "unknown" could cover all three of those states, especially in conjunction with a LockJammedEvent

I don't think we need the in between states, i.e. "locking" and "unlocking". That's why we have Locked vs. TargetLocked. However, I do think that "jammed" could be useful, as the lock is stuck in that state and requires intervention.

• Should TargetLockedProperty just have a boolean value like OpenProperty given it only has two values?

I think that would be fine, provided we specify the special meaning of true/false like we do with OpenProperty.

• Should there be a LockAction and UnlockAction? I'm thinking these might be useful for types of locks which take a particularly long time to actuate. If so, should there be two separate actions or one LockAction which takes a boolean or enum input? Or is a LockedProperty enough on its own?

I don't think the actions are particularly necessary, especially not if there is also a writable TargetLockedProperty.

The way HomeKit handles this is by using a normal property but requiring a special write procedure which requires a timeout. So, from a spec perspective, it's still just a property.

• Is LockJammedEvent actually necessary? Would a "jammed" state of LockedProperty be better?

I would prefer the "jammed" state.

[mrstegeman]

@dhylands thoughts?

[raidnet-ms]

What about a door state property? If the door is not properly closed you might not activate the lock. I think that a door sensor is a must for a lock.

[mrstegeman]

We already have a separate DoorSensor capability for that, though. Are those typically integrated into a smart lock?

[raidnet-ms]

A security door must check if door is properly closed before turning the key or the mechanism will get stuck because it will try to lock the top and bottom side of the door.
A smart lock on a security door cannot work without a door sensor capability.
You might say that you can use another thing (door sensor) and create a rule, but if you want to sell a smart lock for security doors, this might be embedded.
Why not predispose this feature?

[GSvensk]

I've tried to create a JSON object using Java and webkit v0.12.0 with some example data. I think it complies with the proposed schema and the comments made by mrstegeman: https://pastebin.com/8BG1viEv

Have I understood you correctly?

[mrstegeman]

@GSvensk Close. https://pastebin.com/Y8zJgL50

[dhylands]

None of the door locks that I've played with have integrated door sensors (which isn't to say that they don't exist). I'm referring to the types of door locks that a consumer would by at Home Depot to put on the entrance door to their house.

I don't see any support for User Codes?

I think that a LockedEvent and UnlockedEvent would be useful (along with the JammedEvent). These events would include a timestamp, how the door was locked (via user, touchpad, manually) an associated usercode (not the actual pin, but the index of the usercode that was used), and some text.

[mrstegeman]

I'm not sure that user codes are a required part of all smart locks, are they? Nor am I sure how we'd represent that. I guess an array of LockUserCodeProperty objects?

[dhylands]

I'm not sure that user codes are a required part of all smart locks, are they? Nor am I sure how we'd represent that. I guess an array of LockUserCodeProperty objects?

Perhaps not required, but common. Zigbee and zwave would both use an array of strings. Note that there could be potentially hundreds of entries in the array, and it may be sparse (i.e. perhaps only entries 0, 1, and 57 are used).

[flatsiedatsie]

I built my own smart lock. These things probably don't need to be in the spec, but might be interesting:

• It distinguishes between a pulse lock of a duration lock. A pulse lock has a specified time delay after which it returns to its initial state. For example, to unlock the door for 3 seconds, during which it can be quickly pushed open. Users can set this timeout.
• I like the 'target' property a lot. This is useful for things like deadbolts. For these the door has to be fully closed before they can be engaged, they cannot be set to locked and then slammed shut. So it's useful to know if and how long a lock wants to lock, but can't for some reason. If something is keeping the door open, after a while you'd want to trigger an alarm. This is useful for cooling cells/fridges too.

For completeness, my lock device also has:

• Two locks in one. E.g. normal lock and deadbolt in one, or locking the mailbox slot, cat door, etc.
• Two passwords, one for each lock. If the password field is left blank it's ignored.
• Users can send an SMS (with the password) to it to unlock it remotely. It isn't cloud connected, and that's very much on purpose.
• Two fields to store phone numbers which are allowed to trigger the lock via SMS.

[benfrancis]

@raidnet-ms wrote:

A smart lock on a security door cannot work without a door sensor capability.

Note that a device can have multiple capabilities, so you could have a device which exposes both Lock and DoorSensor capabilities. It can have internal logic which prevents certain combinations of state.