Add SwitchbotKeypad device class for classic Keypad

[italo-lombardi]

Adds support for SwitchBot Keypad (WoKeypad) — exposes battery level and attempt_state from BLE advertisements.
https://eu.switch-bot.com/products/switchbot-keypad

Tested on a real device — scanner confirmed battery: 100 and attempt_state parsed correctly from live BLE advertisement data.

Summary

The classic SwitchBot Keypad (WoKeypad) is a passive BLE-only device used to unlock doors paired with SwitchBot Lock. The advertisement parser (adv_parsers/keypad.py) already parses battery and attempt_state from BLE advertisements, and SwitchbotModel.KEYPAD is already defined, but no device class existed.

Changes

• Add SwitchbotKeypad device class in devices/keypad.py, extending SwitchbotDevice (passive-only, no BLE commands)
• Export SwitchbotKeypad from switchbot/__init__.py
• Add KEYPAD_INFO test fixture in tests/__init__.py
• Add tests/test_keypad.py verifying battery and attempt_state are correctly parsed from advertisement data

Test results

All 3 unit tests pass. Verified against real WoKeypad hardware — advertisement data parsed correctly.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
switchbot/__init__.py	100.00% <100.00%> (ø)
switchbot/devices/keypad.py	100.00% <100.00%> (+100.00%)	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[bdraco]

@bluetoothbot review

[Copilot]

Pull request overview

Adds a minimal SwitchbotKeypad device class that wraps the existing process_wokeypad advertisement parser, exposes it from the package's public API, and adds a fixture plus three tests verifying battery and attempt_state parsing.

Changes:

• New switchbot/devices/keypad.py defining SwitchbotKeypad (subclass of SwitchbotDevice, no commands).
• Public export added in switchbot/__init__.py (SwitchbotKeypad).
• New KEYPAD_INFO AdvTestCase fixture in tests/__init__.py and a new tests/test_keypad.py exercising advertisement parsing.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
switchbot/devices/keypad.py	Adds the new passive SwitchbotKeypad device class.
switchbot/init.py	Imports and re-exports SwitchbotKeypad in the public API.
tests/init.py	Adds KEYPAD_INFO advertisement fixture used by the new tests.
tests/test_keypad.py	Adds tests verifying parsed battery and attempt_state values, including battery=None override.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bluetoothbot]

Previous review — superseded by a newer review below.

[italo-lombardi]

Addressed all suggestions from the automated review:

1. Tests now exercise the full pipeline — rewrote all three tests to call parse_advertisement_data with real BLE bytes instead of injecting pre-parsed values. Added assertion on get_battery_percent().

2. Fixed misleading test — test_keypad_advertisement_battery_none_when_no_data now passes empty manufacturer_data so the None comes from the parser's own None-handling branch (adv_parsers/keypad.py:15-16), not a manual override.

3. Removed copy-paste — moved make_advertisement_data to tests/__init__.py as a shared helper. test_keypad_vision.py now imports it from there.

4. Added docstring to SwitchbotKeypad — clarifies passive-only BLE, no commands, and points to adv_parsers/keypad.py for data origin.

5. Fixture bytes — KEYPAD_INFO in tests/__init__.py is already the single source of truth; the new tests reference it directly, so test_adv_parser.py could be updated to do the same in a follow-up if desired.

[italo-lombardi]

@bluetoothbot review

[bluetoothbot]

❌ Permission denied. Only users with write access can trigger bot commands.

[bdraco]

@bluetoothbot review

[andreasbrett]

What's the status here? Would love to have this in the upcoming HA release. Seems like the bot did not fire again.

[bdraco]

The code as-is doesn't do anything. There is nothing to review

[italo-lombardi]

This PR was AI-assisted. The goal is to expose battery % for the classic WoKeypad in Home Assistant.

The pySwitchbot side should be complete: SwitchbotKeypad inherits get_battery_percent() from SwitchbotDevice, which reads the "battery" key that process_wokeypad already parses from the advertisement data. No BLE commands needed — this is a passive device.

A companion HA PR is needed to wire it up (NON_CONNECTABLE_SUPPORTED_MODEL_TYPES + SupportedModels.KEYPAD + CLASS_BY_DEVICE), similar to how LEAK and CONTACT_SENSOR are handled. That PR will come once this merges.

I have the physical device but no experience testing pySwitchbot integrations. Any guidance on how to validate this locally (e.g. with a BLE sniffer or test harness against real hardware) would be appreciated.

[italo-lombardi]

Update: tested on real hardware.

Ran the parser against a live WoKeypad using BLE scanning on macOS.

Results from advertisement data:

• battery: 100%
• attempt_state: 41 (value at time of scan, changes per keypad interaction)

Parser correctly extracts both values from service_data[2] & 0x7f and manufacturer_data[6]. Length guards (>= 3 svc, >= 7 mfr) satisfied by real device advertisements.

All 3 unit tests pass locally.

[CodeFinder2]

Really cool, would love to see this merged! :-)

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

[bluetoothbot]

@italo-lombardi: This PR was AI-assisted. The goal is to expose battery % for the classic WoKeypad in Home Assistant.

Checked the codebase. Contact/leak/motion have no device class. devices/contact.py, motion.py, meter.py are empty stubs. None exported in __init__.py. Passive sensors expose battery via advertisement dispatch only — process_wokeypad already fills battery/attempt_state for SwitchbotModel.KEYPAD. So no pySwitchbot class precedent exists here. Confirm HA truly needs a class for a non-connectable model before iterating — precedent says it reads battery straight from parsed adverts. That gap explains bdraco "nothing to review."

[bluetoothbot]

@andreasbrett: What's the status here? Would love to have this in the upcoming HA release. Seems like the bot did n...

Status: blocked on maintainer CHANGES_REQUESTED. Core objection structural. Passive Keypad battery already comes from advertisement parsing — no device class required, matching contact/leak/motion (all classless stubs here). HA wiring may not need this class at all. Needs the author to confirm the actual HA code path before merge.

[bluetoothbot]

PR Review — Add SwitchbotKeypad device class for classic Keypad

Re-attempt of the previously-rejected passive Keypad class; the maintainer's structural objection still applies.

What's solid:

• Tests drive the real parser end-to-end via parse_advertisement_data with live-derived bytes, not injected values, and the fixture math checks out (service_data[2]&0x7f=100, mfr_data[6]=143 against the dispatch in adv_parser.py:356-366).
• The None-when-missing test exercises the parser's actual guard branch rather than an override — a real improvement over the prior round.
• Export is alphabetized; code is clean and Python 3.11-compatible.

What needs attention:

• The device class adds no behavior beyond what the advertisement dispatch already provides. Verified: contact/motion/meter modules are empty stubs and no passive-sensor device class exists or is exported — so the PR's stated precedent (LEAK/CONTACT_SENSOR "handled" via classes) is inaccurate. This is the basis of bdraco's CHANGES_REQUESTED.
• Class claims passive-only but inherits update()/get_basic_info(), which connect and send 5702 — a latent contradiction.
• attempt_state is an undocumented raw byte.

Recommendation: confirm whether HA actually needs a pySwitchbot class for a non-connectable model (the existing passive sensors say no) and put that justification in the PR body — otherwise this remains "nothing to review."

---

🟡 Important

1. Device class duplicates what advertisement dispatch already provides
switchbot/devices/keypad.py:8-15

This is the crux of bdraco's CHANGES_REQUESTED ("the code as-is doesn't do anything") — and it holds up against the codebase.

Passive SwitchBot sensors in this library carry no device class. I verified that switchbot/devices/contact.py, motion.py, and meter.py are all empty stubs (a single from __future__ import annotations line), and there is no SwitchbotContactSensor, SwitchbotLeak, or SwitchbotMotionSensor defined or exported anywhere. For those models, process_* populates battery/state into the advertisement data via the adv_parser.py dispatch, and consumers read it directly — no class needed.

The PR description (and comment [id=4502620942]) states LEAK and CONTACT_SENSOR are "handled" with device classes similar to this one. That is not accurate for the pySwitchbot side — they aren't. process_wokeypad already fills battery and attempt_state for SwitchbotModel.KEYPAD (adv_parser.py:356-366), so a SwitchbotKeypad subclass that only re-surfaces those values adds no behavior the dispatch doesn't already deliver.

Why it matters: this is the second iteration of essentially the same change, and the maintainer's objection is structural, not cosmetic. Before iterating further, confirm whether Home Assistant actually requires a pySwitchbot device class for a non-connectable model — the contact/leak/motion precedent strongly suggests it does not, and HA can read battery straight from the parsed advertisement. If HA genuinely needs a class hook, that justification (with the HA code path it plugs into) belongs in the PR body; if not, this can be dropped.

class SwitchbotKeypad(SwitchbotDevice):

2. Inherited update()/get_basic_info() contradict the passive-only contract
switchbot/devices/keypad.py:8

The docstring states "Passive BLE-only — no commands," but the class inherits SwitchbotDevice.update() and get_basic_info() unchanged.

I confirmed in device.py that update() (line 819) calls get_basic_info() (line 826) → _get_basic_info() (line 791) → _send_command("5702"), which opens a BLE connection and sends the basic-settings command. For a non-connectable keypad that path cannot succeed.

Why it matters: in normal HA usage of non-connectable models update() is not called, so this is latent rather than active — but it's a foot-gun. Any caller that does invoke update() gets a connection attempt that the device can't service, which is the opposite of "passive, no commands."

If the class stays, consider overriding update() to refresh from a scan (get_device_data) or to no-op, so the inherited connect-and-send behavior can't be reached.

async def update(self, interface=None):  # inherited → _send_command("5702")

🟢 Suggestions

1. attempt_state exposed as an undocumented raw int
switchbot/devices/keypad.py:17-19

attempt_state returns the raw mfr_data[6] byte (143 in the fixture, 41 on the author's live device) with no documented meaning or decoding. As a bare integer with shifting values per interaction, it's of limited use to a consumer.

If this value carries a defined semantic (e.g. last-attempt result code, retry count), decode it into something meaningful or document the encoding; otherwise the genuinely useful signal here is battery, which is already inherited via get_battery_percent().

@property
def attempt_state(self) -> int | None:
    return self._get_adv_value("attempt_state")

---

Checklist

• Change delivers what the PR description promises — warning ＃1
• Consistent with codebase patterns for passive sensors — warning ＃1
• Class contract (passive-only) matches behavior — warning ＃2
• Tests cover new code and edge cases
• No hardcoded secrets / injection / unsafe ops
• Public export wired correctly

---

To rebase specific severity levels, mention me: @bluetoothbot rebase critical (fixes 🔴 only), @bluetoothbot rebase important (fixes 🔴 + 🟡), or just @bluetoothbot rebase for all.

---

Automated review by Kōan (Claude) HEAD=6bcc3a6 4 min 45s

[bluetoothbot]

Blocking issues found.

• Device class duplicates what advertisement dispatch already provides
• Inherited update()/get_basic_info() contradict the passive-only contract