Yale Access / August Binding for internet connected locks

This binding integrates some Yale/August locks that are linked to a Yale/August Connect WiFi Bridge - or have WiFi builtin.

Supported Things

Door locks only.

account = August/Yale Access account
lock = A door lock connected with a WiFi bridge

Confirmed working devices:

Yale Doorman L3 with Yale/August Connect WiFi Bridge
Yale Doorman V2N with Access module and WiFi bridge
August ASL-03 Smart Lock Pro, 3rd Generation
Yale YR C/D 226/246/256

Others may work as well, just not tested yet. Please report back if your lock work/do not work.

Login (READ THIS!)

Yale Access uses 2-factor authentication at first login.

Add a new account thing with phone, email and password. Make sure you select the correct eco system (either legacy August or new Yale Home depending on whether you have migrated your account yet by logging into Yale Home App)
Check your email for the 6-digit code
Update the thing configuration with the code

Thing Configuration

See full example below for how to configure using thing files.

To find the lockId, add the bridge and let it discover your locks.

Account

ecoSystem, either legacy August (AUGUST) or Yale Home (YALE_HOME)
email = Email address used in the mobile app
phone = Mobile number used in the mobile app. Use full number with country code, ie +4712345678
password = Same as you use in the mobile app
refreshInterval = number of seconds between refresh calls to the server. This applies to the bridge itself, not the locks. Defaults to once every hour.
validationCode = one time code requested from the service after authenticating with email + phone + password.

Lock

lockId = id of lock, typically a long string of numbers and letters

Channels

Only a few channels have been added so far, but quite a bit more data is available. If you feel something important is missing, take a look in lock details response and report back/create a PR.

Channel	Read/write	Item type	Description
lockState	R/W	Switch	State of locking bolt, ON = locked, OFF = unlocked
doorState	R	Contact	Whether the door is OPEN or CLOSED. Not all doors report this, in that case the channel reports UNDEF
battery	R	Number:Dimensionless	Remaining battery percentage
changedByUser	R	String	User last locking/unlocking the door. `Manual` if door knob used
unlockedByUser	R	String	User last unlocking the door. `Manual` if door knob used
batteryKeypad	R	String	Remaining battery level of keypad (if installed)

Requesting latest status from lock

Sending a RefreshType command to the lockState channel will query the lock itself instead of relying on the cloud status. This may take 10-20 seconds to complete, but you get the latest and most accurate state.

TODO

Support 2-factor code via SMS. Only email is supported.

Full Example

august.things:

Bridge august:account:accountName "Yale Access account" [ email="XXX@XXX.COM", phone="+4712345678", password="XXXXXXX", refreshInterval="3600", validationCode="REPLACE", ecoSystem="YALE_HOME"] {
  Thing lock frontdoor "Front door" [ lockId="344KJLK32KJ234LKJ234JLKJK34" ]
}

august.items:

Switch Front_Door_Lock "Front door lock" <lock>  {channel="august:lock:accountName:344KJLK32KJ234LKJ234JLKJK34:lockState"}
Contact Front_Door_Contact "Front door ajar [%s]" <door>   {channel="august:lock:accountName:344KJLK32KJ234LKJ234JLKJK34:doorState"} 
Number:Dimensionless Front_Door_Battery "Front door battery [%d%unit%]" <battery>   {channel="august:lock:accountName:344KJLK32KJ234LKJ234JLKJK34:battery"} 
String Front_Door_Changed_By_User "Door last changed by [%s]" <door> (gRestoreOnStartup)   {channel="august:lock:accountName:frontdoor:changedByUser"} 
String Front_Door_Unlocked_By_User "Door last unlocked by [%s]" <door> (gRestoreOnStartup)   {channel="august:lock:accountName:frontdoor:unlockedByUser"}

seime/openhab-august