This is a fork of ZenithVal/OSCLock, a great little tool for opening a Bluetooth LE ESmartLock-compatible lock from a Windows PC. All credit for the original app, protocol reverse-engineering, and OSC/VRChat integration goes to ZenithVal and prior contributors — this fork only adds a desktop GUI and a couple of Windows Bluetooth compatibility fixes on top of their work, and stays under the same GPLv3 license.
- OSCLockGui.exe — a small WPF app with a single "open" button, no console window.
- Minimizes to the system tray instead of closing, with a right-click menu (open / show / exit).
- A configurable global keyboard shortcut (e.g. Ctrl+M) that opens the lock from anywhere in Windows, even while the app is minimized.
- A settings window (⚙) to edit the eSmartLock cloud credentials, toggle "start with Windows" /
"start minimized", pick the hotkey, and switch the interface language (Català / English) — all
without hand-editing
config.toml. - Config/log now live in
%LOCALAPPDATA%\Ocalaix, so the app works even when installed somewhere read-only for a normal user (e.g.C:\Program Files\...). - Two Bluetooth reliability fixes needed on some Windows 11 setups: explicit
RequestAccessAsync/OpenAsync+ uncached GATT reads (fixes anAccessDeniederror onGetCharacteristicsAsync), and running the BLE scan off the WPF UI thread (theDeviceWatchercallbacks were unreliable when awaited from an STA thread with a capturedSynchronizationContext). - Cloud password handling fixes: the cached
device_passwordis now tied to the lock's MAC address, so swapping the physical lock for a different one is detected automatically and the password is re-fetched instead of silently reusing the old lock's (wrong) passcode; a failed cloud API response is no longer cached as if it were a real password; and if the cloud fetch fails outright, the app now tries the factory default123456as a last resort before giving up.
- Turn on Bluetooth and stay near the lock (BLE has short range).
- Run
OSCLockGui.exe. Press Open lock — the padlock icon shows progress (searching → opening → opened). - Press the ⚙ gear icon to open Settings:
- Your eSmartLock cloud account (username/password) — only needed if your lock is bound to the cloud; the app fetches the real device passcode with it.
- Start with Windows / Start minimized — launch automatically at login, straight to the tray.
- Shortcut to open the lock — click the field and press any combination (default Ctrl+M). It works even while the window is hidden in the tray.
- Language — Català / English.
- Closing the window (✕) or minimizing sends it to the system tray instead of exiting; right-click the tray icon for Open lock / Show window / Exit.
- Bluetooth can be unreliable and drop the connection randomly — don't put this lock on anything that could put you in danger, and always have a backup plan.
- Theoretically works with any Bluetooth lock using the eSmartLock app (look for the white/green branding). Well tested with this lock; also reported to work with EseeSmart, ELinkSmart, Pothunder, and Dhiedas.
If you swap the lock for a different one (even the same model), OSCLock now detects the lock's
MAC address changed and automatically re-fetches its password from the cloud instead of reusing
the old lock's cached one — no manual cleanup of config.toml needed.
If the cloud fetch itself fails (e.g. the app shows "No s'ha trobat el pany"/unlock never
succeeds and the log shows an API error like "invalid login" even though your username/password
are correct), and the official eSmartLock app can open the lock fine, the lock's cloud binding
is likely in a bad state on the vendor's server. What fixed it for us:
- In the official app, remove/unpair the lock from your account.
- Factory-reset the lock (check its manual — usually a button combo) and add it back through the official app as if it were new.
- Try OSCLockGui again.
As a safety net, if the cloud password can't be retrieved at all, the app now also tries the
factory default password 123456 before giving up — this can open a lock that was never actually
given a custom passcode even while its firmware reports "bound to cloud".
The console app (OSCLock.exe) that this was forked from — with its OSC/VRChat timer modes,
avatar-parameter integration, and config.toml settings — is unchanged and still buildable from
this same source tree (OSCLock.csproj). See ZenithVal/OSCLock
for its documentation.
- Original OSCLock app, protocol work, and OSC/VRChat integration by ZenithVal — github.com/ZenithVal/OSCLock. This fork (the GUI, tray icon, hotkey, settings window, and Windows 11 Bluetooth fixes) is built entirely on top of their work and released under the same GPLv3 license.
- Prior programming before git history by @NeetCode 08/2022
- SharpOSC | MIT Liscense
- OSCQuery | MIT Liscense
- Tomlet | MIT Liscense
- FluentColorConsole | MIT Liscense
- App Heart Icon | Game-icons.net under CC by 3.0