Lock BLE API

[AdyRock]

Current Situation

There is no BLE API documentation for the lock API except for the device id

Proposed Change

Add documentation for the Lock BLE API

Additional Context

It is desirable to integrate the lock into other home automation systems.

[Jacksonbm1]

I also think this would be a nice feature and probably shouldn't be closed as the BLE fix isn't available yet. I understand that it's not possible yet, but the issue shouldn't be closed IMO.

[kaxio]

Hey team, any updates on this?

[Jacksonbm1]

I saw a post in a live chat with a cofounder of switchbot that said the ble lock api is coming:

Here's the op:

"Hey. It's Richard here. I am one of the cofounders of this little robot SwitchBot. I am more on sales and marketing, but i also know how to code and play around with JavaScript and Python myself. I have around 160+ connected device, 20-30 scenes/ routines/automations or whatever you call it at my place and most of them are in use, which means I kinda know what smart home is. Also I use Alexa most of the time at home and Siri when I am on my phone. Just wanna say hi and if you guys have anything you wanna tell me, just let me know. Would like to interact with you guys more from now on. In case i missed you comments, pin me again. I am also on Twitter in case you wanna talk there too. https://twitter.com/richardmou63/"

Here's the reply that says the lock api is coming:

"1. Lock API is definitely on its way. We gotta test the security level before releasing and there is no ETA yet."

Post: https://www.reddit.com/r/TrySwitchBot/comments/vzr3y6/first_post_hello_world/?utm_source=share&utm_medium=ios_app&utm_name=iossmf

[brandon-dacrib]

I don't understand. Why was this issue closed even though there is still no documentation on using the switchbot lock via BLE?

[Jacksonbm1]

It's listed as open for me? But I believe comments may re open it. Pretty sure GitHub auto closes issues that don't get updates and go stale

[martindinicolino]

with V1.1 of the API dropping about a week ago and bringing back the lock and unlock capability to the webAPI (which is awesome, thank you very much for that), is there any timetable in regards to this functionality being added to the bleAPI?

[Jacksonbm1]

Best way I can find is to message Richard Mou on twitter. He responds quickly

[r-glebov]

Looking forward for the BLE API support!

[martindinicolino]

Best way I can find is to message Richard Mou on twitter. He responds quickly

i‘m not on twitter, could somebody do that please?

[Minsheng]

Current Situation

There is no BLE API documentation for the lock API except for the device id

Proposed Change

Add documentation for the Lock BLE API

Additional Context

It is desirable to integrate the lock into other home automation systems.

This is Davidson from the dev team. We are working on the BLE API and we will update the BLE API doc hopefully in the next month. I myself will oversee the progress and keep you posted. Thanks a lot for being patient and supportive! You guys are the best!

[Jacksonbm1]

This is Davidson from the dev team. We are working on the BLE API and we will update the BLE API doc hopefully in the next month. I myself will oversee the progress and keep you posted. Thanks a lot for being patient and supportive! You guys are the best!

This is fantastic news! Out of curiosity, what features will the api include?

• ability to lock/unlock
• ability to read state of lock
• ability to read state of door
• ability to read state of battery

Best

[Minsheng]

This is Davidson from the dev team. We are working on the BLE API and we will update the BLE API doc hopefully in the next month. I myself will oversee the progress and keep you posted. Thanks a lot for being patient and supportive! You guys are the best!

This is fantastic news! Out of curiosity, what features will the api include?

• ability to lock/unlock
• ability to read state of lock
• ability to read state of door
• ability to read state of battery

Best

We plan to support these triggers first,

• ability to read state of lock
• ability to read state of door
• ability to read state of battery

The actions will have to come after.

Davidson

[marcomow]

awesome! @Minsheng do you have an estimated timeline for both reading and actions? Asking as our company is deciding which product to choose, so it may be worth to wait, but we need to understand how long. Thank you!

[sonny-chen]

This is fantastic news! Out of curiosity, what features will the api include?

• ability to lock/unlock
• ability to read state of lock
• ability to read state of door
• ability to read state of battery

Please also add the ability to set PIN. This will create a huge use case for vacation homes.

[Minsheng]

awesome! @Minsheng do you have an estimated timeline for both reading and actions? Asking as our company is deciding which product to choose, so it may be worth to wait, but we need to understand how long. Thank you!

We have released the broadcast definition for Lock. The pull request is being reviewed atm. We don't have a timeline for the implementation of Lock actions yet. Please stay tuned.

[martindinicolino]

great job, thank you for your work! patiently waiting for the ability to lock and unlock to be added to the BLE API though 🤞

[federicotravaini]

Just goona buy in advance the lock waiting for this integration to be live asap 😃

[advorsky73]

Happy New Year ;) Any updates?

[donavanbecker]

@advorsky73 check this repo out: https://github.com/Danielhiversen/pySwitchbot

[advorsky73]

@donavanbecker thats for cloud api, how does this help for BLE ??? 🤔

[donavanbecker]

@advorsky73 pretty sure this is all BLE: https://github.com/dsypniewski/pySwitchbot/blob/ed46ac93e2c8985037e21f31e4bb7b933e17714f/switchbot/devices/lock.py

From this PR: https://github.com/Danielhiversen/pySwitchbot/pull/164

[dsypniewski]

@advorsky73 it's all BLE, not cloud. I did some investigating of messages between the lock and the app. I'll try to make a PR here once I'll finish up and organize my notes. Next release of HA should also have this integrated, it already is in the beta.

[jpconfessor]

FINALLY!! Home assistant added support for this lock via BLE! check version 2023.1 ;) Works fine and exposes several states:

I've just bought Daniel a coffee! hehe

[martindinicolino]

@jpconfessor beautiful! thanks for letting us know 👍

are we sure locking and unlocking work over BLE though? I thought that wasn‘t yet available vie the BLE API, but i‘d love to be corrected

this is a big improvement as is, but it‘s worth even more if it‘s locally controlled

[dsypniewski]

@martindinicolino Yes, as I said before it's local. I spend about a month reverse engineering the lock communication and making the integration for Home Assistant, that's why the integration works while there aren't any action related docs released by SwitchBot yet. The only internet connection is needed during setup to retrieve the locks encryption key from SwitchBot internal API.

[martindinicolino]

@dsypniewski this is huge! thank you for your effort

i‘ll give it a try as soon as i get home

[jpconfessor]

yes! I was able to validate using my ble proxy logs (from esphome).

I’ve noticed that the very first command after a while requires a connection, and due to this it takes around 1s to lock/unlock… if you try again.. it is almost instant…. so, this very first command is still waaaay faster than api (I was using the smartthings integration.. so, even worst!)

I’ve watched the release video from HA and they’ve mentioned some improvements around this area in the new version of esphome that requires a serial update (not OTA) in order to give us full performance. I will give it a try to see if I can reduce this even more :)

setup: I am using home assistant 2023.1 with the switchbot integration via bluetooth proxies around my house (esp32 devices - m5 atom lite) - check this: https://esphome.github.io/bluetooth-proxies/

[kklicker777]

I have also set this up in Home Assistant and can confirm it is local. You should be proud of your work here. I know I read a lot of comments about hesitation in buying this lock due to the lack of local support on Home Assistant. I would expect sales of this lock to improve greatly due to this improvement. Great job.

[andreasbuff]

yes! I was able to validate using my ble proxy logs (from esphome).

I’ve noticed that the very first command after a while requires a connection, and due to this it takes around 1s to lock/unlock… if you try again.. it is almost instant…. so, this very first command is still waaaay faster than api (I was using the smartthings integration.. so, even worst!)

I’ve watched the release video from HA and they’ve mentioned some improvements around this area in the new version of esphome that requires a serial update (not OTA) in order to give us full performance. I will give it a try to see if I can reduce this even more :)

setup: I am using home assistant 2023.1 with the switchbot integration via bluetooth proxies around my house (esp32 devices - m5 atom lite) - check this: https://esphome.github.io/bluetooth-proxies/

Works great, as described! Thanks everyone for this solution! Regards

[Write]

@martindinicolino Yes, as I said before it's local. I spend about a month reverse engineering the lock communication and making the integration for Home Assistant, that's why the integration works while there aren't any action related docs released by SwitchBot yet. The only internet connection is needed during setup to retrieve the locks encryption key from SwitchBot internal API.

Excellent work. Works flawlessly, thanks you so much ! Do you have any donations link ? That's the kind of work that definitely deserve it.

[donavanbecker]

@jpconfessor, I tried out the home assistant component, but my SwitchBot account doesn't have a password since I use Login in with Apple. Is there anyway to authenticate with the token and secret?

[Write]

@jpconfessor, I tried out the home assistant component, but my SwitchBot account doesn't have a password since I use Login in with Apple. Is there anyway to authenticate with the token and secret?

You’d have to unpair everything, delete your account and recreate one with an email. That’s what I did. The other way to get the token still require both an email and password so I don’t think there’s a way around it.

[jpconfessor]

In order to get the encryption key you still need the username and password since the python script will request it https://github.com/Danielhiversen/pySwitchbot#obtaining-locks-encryption-key

[dsypniewski]

Excellent work. Works flawlessly, thanks you so much ! Do you have any donations link ? That's the kind of work that definitely deserve it.

@Write Thank you, I've put some links in my profile as well as here: https://paypal.me/DamianSypniewski https://revolut.me/damiansypniewski

@jpconfessor, I tried out the home assistant component, but my SwitchBot account doesn't have a password since I use Login in with Apple. Is there anyway to authenticate with the token and secret?

@donavanbecker unfortunately currently only normal (non SSO) accounts can be used no matter if it's through HA or the script, but I'll be looking into trying to get those accounts working as well.

[donavanbecker]

Thanks @dsypniewski!

[dsypniewski]

@donavanbecker could you try the web auth option in the script from my branch ?https://github.com/dsypniewski/pySwitchbot/tree/lock-key-script-web-auth

[slight316]

Hello, I tried to integrate with home assistant via a bluetooth dongle. Dongle is directly connected to a Dell Wyse 3030 (no wifi) hardware info:

The lock is Discovered but when I go to configure with my encryption key or my username/password I get Unknown error occurred.

Any suggestions?

EDIT: acquired a USB extension cable and moved my Dongle like 2 feet closer to the lock. Everything golden now. Guess this dongle has trash range.

[donavanbecker]

@donavanbecker could you try the web auth option in the script from my branch ?https://github.com/dsypniewski/pySwitchbot/tree/lock-key-script-web-auth

@dsypniewski, I must do this on linux? can't do it on Mac?

[dsypniewski]

@donavanbecker the script needs to register a custom URL handler to receive the authentication results from the browser and each OS has different method of doing this so currently only Linux is supported. I don't have a Mac to test, but I'll try looking into how to do it there.

[ashald]

@dsypniewski I saw that iOS app has an option for "emergency lock/unlock" which, as far as I understand, just makes the lock rotate either way until it meets resistance. Do you think you somehow add that as well please? Maybe as button entities exposed on each device, or as a special function? In my case, I have a lock that when locked/unlocked from outside with a key, the inside knob does not move. This means that to lock unlock I just need to rotate the inside know right or left, regardless of the current position. This in turn means that I cannot leverage the usual mode of operation that relies on calibrated positions.

[ashald]

Ah, and since it's the Switchbot official repo - just for the record.

1. I ordered the lock ASAP once it was announced since I thought it'd have local BLE interface available for 3rd parties right away
2. Once I learned it doesn't I canceled the order
3. Once community reverse-engineered the interface and built integration for HomeAssistant, I bought a lock right away, super happy with the product now, and consider buying 1 or 2 more. I won't claim everyone is like me, but I'd bet that I'm by far not alone. That is to highlight how important the full BLE protocol available to your community. Thanks everyone!

[dsypniewski]

@ashald I haven't yet looked into the emergency operation so I'm going to add it to my list of things to look into

[slight316]

on a somewhat related but not related tangent. Any chance that the keypad operation (adding keys, deleting keys, etc) can also be integrated into home assistant?

[dsypniewski]

@slight316 With enough time in theory it should be possible to even support the whole setup of lock/keypad but it takes a lot more time to investigate the multi step processes compared to single step like lock/unlock. As much as I'd like to have a complete replacement for the SwitchBot app I don't think it's going to happen any time soon.

[slight316]

@dsypniewski I appreciate your candour and understand Rome wasn't built in a day and completely appreciate all the work that has been done to reverse engineer the lock.

It would be brilliant if the keypad was reverse engineered as well. If only to allow me to manage keys remotely through HA instead of having to be within BLE distance to the keypad.

[dsypniewski]

@slight316 I agree, and will definitely try just don't know when or how feasible it will be.

@donavanbecker I just found out that there is a docker image for macOS vm, the chances of getting this working on Mac just went up considerably.

[donavanbecker]

@dsypniewski awesome! I don't have access to Linux.

[slight316]

@dsypniewski I find myself with a little bit of spare time. Is there anyway that I can help with reverse engineering the keypad functionality? I don't have much experience in this department but if you can send me towards some articles or something I'm eager to learn.

[dsypniewski]

@slight316 As to sniffing bluetooth traffic I can recommend series of videos mentioned here https://hackaday.com/2021/03/23/a-crash-course-on-sniffing-bluetooth-low-energy/ This requires a dongle that allows sniffing Bluetooth - you can usually buy one pretty cheap on sites like AliExpress but I didn't want to wait so I made mine from nRF52840 dongle flashed with this https://www.nordicsemi.com/Products/Development-tools/nRF-Sniffer-for-Bluetooth-LE What also helped a lot was looking through decompiled java code and string resources of the Android SwitchBot app, this article https://medium.com/helpshift-engineering/reverse-engineer-your-favorite-android-app-863a797042a6 seems to be using similar set of tools that I was using except the last step where I use fernflower.

@donavanbecker I pushed an update to the branch mentioned earlier that adds support for macOS and Windows could you check it out? This might require updating python3 to newer version because I had some problems with the default version provided by macOS.

[KiraPC]

@slight316 As to sniffing bluetooth traffic I can recommend series of videos mentioned here https://hackaday.com/2021/03/23/a-crash-course-on-sniffing-bluetooth-low-energy/ This requires a dongle that allows sniffing Bluetooth - you can usually buy one pretty cheap on sites like AliExpress but I didn't want to wait so I made mine from nRF52840 dongle flashed with this https://www.nordicsemi.com/Products/Development-tools/nRF-Sniffer-for-Bluetooth-LE What also helped a lot was looking through decompiled java code and string resources of the Android SwitchBot app, this article https://medium.com/helpshift-engineering/reverse-engineer-your-favorite-android-app-863a797042a6 seems to be using similar set of tools that I was using except the last step where I use fernflower.

@donavanbecker I pushed an update to the branch mentioned earlier that adds support for macOS and Windows could you check it out? This might require updating python3 to newer version because I had some problems with the default version provided by macOS.

Hello @dsypniewski I'm trying to test the script on my mac, do I have to install the URL handler? because chrome can't found it.