Skip to content

docs: explain active scanning requirement for device discovery#531

Draft
bluetoothbot wants to merge 2 commits into
sblibs:mainfrom
bluetoothbot:koan/doc-active-scan-discovery
Draft

docs: explain active scanning requirement for device discovery#531
bluetoothbot wants to merge 2 commits into
sblibs:mainfrom
bluetoothbot:koan/doc-active-scan-discovery

Conversation

@bluetoothbot

@bluetoothbot bluetoothbot commented Jun 22, 2026

Copy link
Copy Markdown
Collaborator

What

Add a "Device discovery and active scanning" section to the README.

Why

"Some of my SwitchBot devices are discovered but not all" is a recurring
support theme (e.g. #299, #287). The cause is well understood by maintainers
but undocumented: SwitchBot puts the model identifier in the BLE service data,
which is only delivered in the scan response and therefore requires active
scanning. With a passive scanner the service_data is absent and detection
falls back to manufacturer data, which only resolves a handful of models.

How

Verified against the code: parse_advertisement_data resolves the model from
service_data first (_find_model_from_service_data / suffix); the
manufacturer-data fallback (_find_model_from_manufacturer_data) matches by
length only and covers few models. GetSwitchbotDevices().discover() already
uses an active scanner, so the section notes the gap surfaces when a passive
source feeds advertisements (e.g. a Home Assistant adapter or ESPHome proxy in
passive mode) and tells users to enable active scanning there.

Docs-only; no code changes.

Testing

No code changed. Confirmed prettier preserves the prose wrapping (no
proseWrap override; lines match the existing Troubleshooting section width).


Autonomous PR by Kōan, an agent run by Nick (@bluetoothbot). A human is responsible for reviewing and merging.


Quality Report

Changes: 1 file changed, 17 insertions(+)

Code scan: clean

Tests: passed (1300 passed)

Branch hygiene: clean

Generated by Kōan

@codecov

codecov Bot commented Jun 22, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant