Yale/August smart locks with WiFi support

(And now you should download version 20180813 of org.json)

Hmm. I thought org.json was part of the core distribution. Must have been installed on my system by another addon possibly.
Which version of openHAB are you using?

openHAB 3.4.1

Release Build

Hi. I’m using OpenHAB 3.4.2 and the Yale/August binding, and I added the account bridge, which discovered my two August locks. They’re both August Smart Locks, about 2-3 years old, and they work with the phone app and with the Alexa skill. When the binding is activated, I get this error:

2023-02-14 17:16:31.826 [DEBUG] [nternal.handler.AugustAccountHandler] - Storing new access token
2023-02-14 17:16:31.827 [WARN ] [mmon.WrappedScheduledExecutorService] - Scheduled runnable ended with an exception: 
java.lang.NullPointerException: null
        at org.openhab.binding.august.internal.handler.AugustLockHandler.parseUserMap(AugustLockHandler.java:340) ~[?:?]
        at org.openhab.binding.august.internal.handler.AugustLockHandler.doPoll(AugustLockHandler.java:147) ~[?:?]
        at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:515) ~[?:?]
        at java.util.concurrent.FutureTask.run(FutureTask.java:264) ~[?:?]
        at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(ScheduledThreadPoolExecutor.java:304) ~[?:?]
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128) [?:?]
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628) [?:?]
        at java.lang.Thread.run(Thread.java:829) [?:?]

Both Things show up as Status: Unknown, and I can’t operate them from OpenHAB.

Thanks for testing @jckeatley, apparently not all locks return a list of users the way my locks do.

Could you capture the JSON response and send to me by PM?


Posted a new version with a null check for the user list.

Appreciate you testing, and looking forward to getting a JSON response to look at. The APIs are undocumented so creating a binding that works in all cases is kinda impossible without some trial and error :wink:

Awesome, thank you for this great binging! I use it with Yale Doorman V2N, yet for some reason, I’m unable to catch the unlocked events properly. I tried the binding that comes with 3.4.2, as well as the snapshop from the first message in this thread, both behave the same

There is valid unclocked event with callingUserId which I believe is the event I’m interested in. Parsing that message fails, however.

2023-02-16 18:07:08.633 [INFO ] [t.internal.handler.AugustLockHandler] - Received pubsub message {
  "status": "unlocked",
  "callingUserID": "638b0d67-314a-4654-9517-88c40cb3b9af"
2023-02-16 18:07:08.636 [ERROR] [t.internal.handler.AugustLockHandler] - Error handling pubnub message on channel cbaa9b7e-0a0d-47f2-ade1-62be997c653a: {"status":"unlocked","callingUserID":"638b0d67-314a-4654-9517-88c40cb3b9af"}
java.lang.NullPointerException: null
	at org.openhab.binding.august.internal.handler.AugustLockHandler.onPushMessage(AugustLockHandler.java:302) [bundleFile:?]
	at org.openhab.binding.august.internal.handler.AugustAccountHandler.onPushMessage(AugustAccountHandler.java:328) [bundleFile:?]
	at org.openhab.binding.august.internal.comm.PubNubMessageSubscriber$1.message(PubNubMessageSubscriber.java:137) [bundleFile:?]
	at com.pubnub.api.managers.ListenerManager.announce(ListenerManager.java:61) [bundleFile:?]
	at com.pubnub.api.workers.SubscribeMessageWorker.takeMessage(SubscribeMessageWorker.java:44) [bundleFile:?]
	at com.pubnub.api.workers.SubscribeMessageWorker.run(SubscribeMessageWorker.java:35) [bundleFile:?]
	at java.lang.Thread.run(Thread.java:829) [?:?]

Thanks @jpalo, apparently your lock do not report door state. I’ve added a new release listed in the original post.

I’d appreciate if you could send me the getLockResponse printed in the logs if you set level to DEBUG. Requests starts with something like GET https://api-production.august.com/locks/92


I believe it does report door state, if the state is one of these messages:

2023-02-16 18:19:41.183 [INFO ] [t.internal.handler.AugustLockHandler] - Received pubsub message {
  "remoteEvent": 1,
  "status": "kAugLockState_Locked",
  "info": {
    "action": "status",
    "startTime": "2023-02-16T16:19:40.859Z",
    "context": {
      "transactionID": "UTc898bKz_",
      "startDate": "2023-02-16T16:19:40.849Z",
      "retryCount": 1
    "lockType": "lock_version_1002",
    "serialNumber": "M4I7R0009P",
    "rssi": -75,
    "wlanRSSI": -70,
    "wlanSNR": 28,
    "duration": 148,
    "lockID": "4C16624D1D7440A1929F7CE9BB8AB5BA",
    "bridgeID": "63ee1fcd2c2d491e45ff4cb2",
    "serial": "C6W7C005WJ"
  "doorState": "kAugDoorState_Closed",
  "retryCount": 1,
  "totalTime": 168,
  "resultsFromOperationCache": true
2023-02-16 18:19:41.185 [INFO ] [t.internal.handler.AugustLockHandler] - Unhandled EVENT

or this one:

2023-02-16 18:21:49.166 [INFO ] [t.internal.handler.AugustLockHandler] - Received pubsub message {
  "status": "locked",
  "callingUserID": "638b0d67-314a-4654-9517-88c40cb3b9af",
  "doorState": "closed"

With DEBUG, I do get response from “GET https://api-production.august.com/locks/4C…”, however(!), with the latest JAR you just posted, it now seems to correctly update the changedByUser channel, so looking very good indeed, thank you.

Appreciate that you also took time to implement the file based configuration option for this binding. It seems to work well.

I’ve used the second one as the first one only is triggered by remote locking/unlocking operations, and the second, short type seems to always come.

In the first post the message below indicated that door state was missing, but in the last post it is present.

I’ll update the binding so that the channel are updated only when the corresponding field in the message is present.

I strongly prefer the file based config as the UI IMHO isn’t well suited for bulk operations - which is a necessity in a non-stale setup.

Received pubsub message {
  "status": "locked",
  "callingUserID": "638b0d67-314a-4654-9517-88c40cb3b9af",
  "doorState": "closed"
1 Like

Posted a new version with improved error handling in case of network errors.

Recommended to update as network errors may cause the bridge to panic, go offline and require a new 2FA login.

Thanks, there are intermittent ghost unlock events causing changedByUser to change when door wasn’t unlocked. Will test with the latest version and see how it behaves.

EDIT: Now I think I understand what my problem is :smiley: I’d like to get an even when door was UNLOCKED by someone - currently I’m not sure if there is a way to differentiate between unlock and lock events in a rule?

If not, could there even be separate channels for lockedByUser and unlockedByUser?

So this is the locked event that sometimes gets triggered by Yale (not sure why as user didn’t manually lock the door, but that’s not something we/you need to worry :slight_smile: ), and causes the changedByUser:

2023-02-18 19:35:32.064 [INFO ] [t.internal.handler.AugustLockHandler] - Received pubsub message {
  "status": "locked",
  "callingUserID": "3b266561-b01e-4898-b858-7d71f690694e",
  "doorState": "closed"

==> /var/log/openhab/events.log <==

2023-02-18 19:35:32.072 [INFO ] [openhab.event.ItemStateChangedEvent ] - Item 'FrontDoorUnlockedBy' changed from Manual to Jussi Palo

And this is the unlocked event:

2023-02-18 19:42:02.947 [INFO ] [t.internal.handler.AugustLockHandler] - Received pubsub message {
  "status": "unlocked",
  "callingUserID": "638b0d67-314a-4654-9517-88c40cb3b9af"

==> /var/log/openhab/events.log <==

2023-02-18 19:42:02.953 [INFO ] [openhab.event.ItemStateChangedEvent ] - Item 'FrontDoorUnlockedBy' changed from Manual to Jussi Palo

I’ll take a look at it.

BTW do you have auto-locking enabled? Could be the cause of the unexpected event.

Yes, auto lock is enabled.

I can confirm that I can install version 0.9 from the marketplace without having “json.jar” in the addons directory now. Thanks for fixing it!

Thanks for a great binding! I have some small suggestions for the thing type:

Door state: Should it be category Door? (Or maybe FrontDoor?)
Lock state: Should it be category Lock?
Changed by user: Should it be category Time?
Changed by user: Should it be item-type DateTime?

I think it will impact the default icons you get around in the UI, e.g. for thing channels for a lock.

Oh, and one other suggestion. I had some problems configuring the account as I wrote the wrong password.

The error message I got was:

2023-02-22 19:21:15.357 [WARN ] [nternal.handler.AugustAccountHandler] - Error initializing data: Exception caught trying to communicate with API: org.eclipse.jetty.client.HttpResponseException: HTTP protocol violation: Authentication challenge without WWW-Authenticate header, retrying at specified refreshInterval

I notice that the claims in the bearer token I had when I had the wrong password was:

  "installId": "<some id>",
  "region": "",
  "applicationId": "",
  "userId": "",
  "vInstallId": false,
  "vPassword": false,
  "vEmail": false,
  "vPhone": false,
  "hasInstallId": true,
  "hasPassword": true,
  "hasEmail": true,
  "hasPhone": true,
  "isLockedOut": false,
  "oauth": {},
  "apiKey": {},
  "homeAccess": "",
  "captcha": "",
  "email": [
    "email:<my email address>"
  "phone": [],
  "expiresAt": "2023-06-22T18:21:15.171Z",
  "temporaryAccountCreationPasswordLink": "",
  "iat": 1677090075,
  "exp": 1687458075,
  "LastName": "",
  "FirstName": ""

While the token I get when I write the correct password contains value for userId, FirstName and LastName.

Maybe it would be an idea to create an error message about “check phone, email, password, and validation code” if all are entered and we get a HttpResponseException?

Thanks for the suggestions @austvik, I will take a look at them in a few days.


1 Like

The thing itself has category Lock, but could be Door or FrontDoor. By examining thing categories I’m not really sure what is most correct?

Assuming channel categories are correctly documented, FrontDoor ie is a thing category, not a channel category. I have not dug through the source code though, but if they are in fact supported I’ll change this (please provide a PR to update the openhab docs :slight_smile: )

changedByUser is the name of the person (or Manual if manually operated) - not the time the lock was operated. If you are looking to find the last time it changed, I think persistence function lastUpdated is what you are after?


Sorry, I misunderstod changedByUser.

If I were to guess, I would guess that most people use this for a front door. But a Door is a “can’t be wrong” safe choice. But there is also Lock, which is a safe choise as well. Maybe not change it. Maybe it should support several categories: “lock” and “door” or “lockable door”. I’m not able to find any guidelines for it.

I find category Lock being used for channels in broadlinkthermostat, avmfritz, and the max binding. Only deconz uses it for a thing.

The Door category is being used for channels in groupepsa, nuki, netatmo and zway, for a thing in elroconnects and both in groupepsa. So it seems to be quite chaotic. I think the proof is in the pudding, and if changing doorState to Door and LockState to Lock changes the icons here, it is a success :slight_smile: