Skip to content

v0.5.0 — Working unlock

Choose a tag to compare

View all tags
@Forcky Forcky released this 25 Aug 18:51
· 57 commits to main since this release
v0.5.0
f502f8c

Unlock now works. This is the first release where lock.unlock has been confirmed against physical hardware.

What was wrong

Two fields in the BLE command frame were both incorrect, and both had to be right at once — which is why the earlier brute-force approach never stumbled onto it:

  • str3, the hub flag — was sent as 00, should be 01. Every senddata command from the cloud is relayed through a hub.
  • the credential slot — was sent as 1, should be 0. The host credential lives in slot 0.

What is tested

Unlock on a PGD628FN (lock firmware 4.03.15) behind a PGH220 Secure LINK, physically confirmed.

That is one lock model and one hub generation. Everything else in this release is implemented but unverified on other hardware.

Also in this release

  • Per-model capability dispatch. Command codes and field layouts are selected from the lock's model and firmware rather than assumed, so other models take their correct code path instead of the PGD628FN one.
  • Host password read from the lock via QueryPwd147 (0x93), so unlock no longer depends on a cached credential.
  • Lock-side BLE error codes are decoded instead of surfaced as raw bytes.
  • Cloud error codes now come with an explanation. Previously an undocumented cod=930 was passed through bare.
  • cachedstatus failures are no longer hidden at debug level while senddata failures logged at warning. Reports only ever showed half of what was failing.
  • hubid is now logged on failures, and an empty hubid is reported explicitly rather than as a generic error.

Known limitations

  • lock.lock is unverified. It differs from unlock by one byte and the app confirms these locks support an explicit lock command, but it is hard to observe on a lock with auto-lock enabled.
  • Silent polling needs hub firmware ≥ build 422 on major-version-2 hubs. Below that, state updates only at startup and after commands from HA.
  • Locks with no hub are not supported. senddata relays through a hub, so WiFi-native locks need a different API path that is not implemented.
  • Real-time MQTT push does not work. The broker refuses the subscription. rc=5 lines in the log are expected and harmless.

If this does not fix your locks, please open or comment on an issue with your lock model, hub model and hub firmware version — and enable debug logging first:

logger:
  default: warning
  logs:
    custom_components.lockly: debug

Full protocol documentation is in docs/api.md.

Assets 2
Loading