ha-bluetooth-augment

HA Bluetooth Augment

Spec: spec/claude/ha-bluetooth-augment/en.md (EN canonical) / spec/claude/ha-bluetooth-augment/de.md (DE translation).

Why this is a skill, not an agent

• Human-visible augmentation surface — the user describes how the device advertises and reads back the manifest matcher, the callback registration, the coordinator family, and the conformance report; a skill keeps this on the visible command surface, like the sibling augment skills (ha-discovery-augment, ha-config-flow-augment, ha-coordinator-add).
• Mid-flow interactivity — the passive-vs-connectable decision, the coordinator-family choice, and the network-discovery redirect are per-run dialogues the user approves before generation.
• Bounded, inline generation — the manifest matcher plus the callback registration and the coordinator wiring fit inline; no isolated agent context is needed.
• Counter-dimension considered: the draft→validate loop could be an agent, but the connectable decision and the trade-off advice belong in the user's working context; skill wins.

When this skill activates

Use this skill to add Bluetooth support — central BLE discovery plus advertisement-driven data fetching — to an existing integration, typically for a device that delivers its data over BLE advertisements (the passive default) or needs an occasional active connection.

When NOT to activate

• DHCP/SSDP/USB/HomeKit/Zeroconf network or bus discovery → ha-discovery-augment / ha/discovery-mechanisms
• the config-flow Bluetooth discovery step / generic config-flow auth steps → ha-config-flow-augment / ha/config-flow-patterns
• the generic polling-based DataUpdateCoordinator for REST/cloud APIs → ha/coordinator-patterns
• greenfield integration scaffolding → ha-integration-scaffold
• deploying/importing into a running HA instance → out of scope

Hard rules

1. Read spec/ha/bluetooth/en.md first. Do not generate HA internals from memory.
2. Right mechanism, with delimitation. DHCP/SSDP/USB/HomeKit/Zeroconf → ha-discovery-augment; the full config-flow discovery step → ha-config-flow-augment. Redirect rather than augmenting the wrong one.
3. Manifest matcher + dependency. The bluetooth key is a list of matcher dicts from the documented fields (service_uuid, local_name, manufacturer_id, service_data_uuid, connectable); add bluetooth_adapters to dependencies when the integration uses an adapter.
4. Passive is the default. Operate connectable=False whenever the device delivers data through advertisements only — that opts in to non-connectable controllers. Use connectable=True (the field default) only where an outgoing connection is actually needed; set the flag per device for mixed devices.
5. Advertisement callbacks. Subscribe via bluetooth.async_register_callback(hass, callback, matcher, mode) with a BluetoothCallbackMatcher and an explicit bluetooth.BluetoothScanningMode (ACTIVE/PASSIVE). The callback is @callback, synchronous, signature (service_info: BluetoothServiceInfoBleak, change: BluetoothChange) -> None. Bind the returned cancel callback via entry.async_on_unload(...).
6. Lookups, never an own scanner. Get a BLEDevice via bluetooth.async_ble_device_from_address(hass, address, connectable) and handle the None case (no adapter in range); read latest info via bluetooth.async_last_service_info; check bluetooth.async_scanner_count(hass, connectable=True) at setup when connecting. Never instantiate an own BleakScanner.
7. Right coordinator family. PassiveBluetoothProcessorCoordinator for sensors/binary sensors/events from advertisements; ActiveBluetoothProcessorCoordinator on connection need; the DataUpdate variants for non-sensor entities; the generic DataUpdateCoordinator only on pure connection communication with no advertisements. Processor coordinators format PassiveBluetoothDataUpdate (indexed by PassiveBluetoothEntityKey) and bind coordinator.async_start() to entry.async_on_unload(...) only after async_forward_entry_setups. Active variants check CoreState.running and a reachable connectable BLEDevice in needs_poll_method.
8. Connection handling. For active connections use bluetooth.async_get_scanner(hass), a fresh BleakClient per connection, a timeout ≥ 10 s, and bleak-retry-connector; never hold a permanent connection when the data is in advertisements.
9. Name per spec/ha/naming-conventions/en.md and verify HA internals against the official docs (see spec/ha/upstream-docs-verification/en.md).