Document bluetooth discovery (#1389)

* Document bluetooth discovery

* fixes

* Update creating_integration_manifest.md

* Update docs/network_discovery.md

* Update docs/network_discovery.md

* Update docs/network_discovery.md

* Update network_discovery.md

* Update creating_integration_manifest.md

* adjust types

docs/config_entries_config_flow_handler.md

@@ -49,6 +49,7 @@ There are a few step names reserved for system use:
 
 | Step name   | Description                                                                                                                                                   |
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bluetooth`        | Invoked if your integration has been discovered via Bluetooth as specified [using `bluetooth` in the manifest](creating_integration_manifest.md#bluetooth).             |
 | `discovery` | _DEPRECATED_ Invoked if your integration has been discovered and the matching step has not been defined.             |
 | `dhcp`      | Invoked if your integration has been discovered via DHCP as specified [using `dhcp` in the manifest](creating_integration_manifest.md#dhcp).             |
 | `hassio`    | Invoked if your integration has been discovered via a Supervisor add-on.
@@ -82,9 +83,9 @@ Should the config flow then abort, the text resource with the key `already_confi
 ```
 
 By setting a unique ID, users will have the option to ignore the discovery of your config entry. That way, they won't be bothered about it anymore.
-If the integration uses DHCP, HomeKit, Zeroconf/mDNS, USB, or SSDP/uPnP to be discovered, supplying a unique ID is required.
+If the integration uses Bluetooth, DHCP, HomeKit, Zeroconf/mDNS, USB, or SSDP/uPnP to be discovered, supplying a unique ID is required.
 
-If a unique ID isn't available, alternatively, the `dhcp`, `zeroconf`, `hassio`, `homekit`, `ssdp`, `usb`, and `discovery` steps can be omitted, even if they are configured in
+If a unique ID isn't available, alternatively, the `bluetooth`, `dhcp`, `zeroconf`, `hassio`, `homekit`, `ssdp`, `usb`, and `discovery` steps can be omitted, even if they are configured in
 the integration manifest. In that case, the `user` step will be called when the item is discovered.
 
 Alternatively, if an integration can't get a unique ID all the time (e.g., multiple devices, some have one, some don't), a helper is available

docs/creating_integration_manifest.md

@@ -157,6 +157,50 @@ Result (this is intended functionality for the near feature):
 - Roborock is listed on our user documentation website under integrations with an automatically generated stub page that directs the user to the integration to use.
 - Roborock is listed in Home Assistant when clicking "add integration". When selected, we first show a "redirect text", then the user continues to the Xioami Miio config flow.
 
+
+## Bluetooth
+
+If your integration supports discovery via bluetooth, you can add a matcher to your manifest. If the user has the `bluetooth` integration loaded, it will load the `bluetooth` step of your integration's config flow when it is discovered. We support listening for Bluetooth discovery by matching on `local_name`, `service_uuid`, `manufacturer_id`, and `manufacturer_data_first_byte`. The manifest value is a list of matcher dictionaries, your integration is discovered if all items of any of the specified matchers are found in the Bluetooth data. It's up to your config flow to filter out duplicates.
+
+The following example will match Nespresso Prodigio machines:
+
+```json
+{
+  "bluetooth": [
+    {
+      "local_name": "Prodigio_*"
+    }
+  ]
+}
+```
+
+The following example will match a service uuid used for SwitchBot devices:
+
+```json
+{
+  "bluetooth": [
+    {
+      "service_uuids": ["cba20d00-224d-11e6-9fb8-0002a5d5c51b"]
+    }
+  ]
+}
+```
+
+The following example will match HomeKit devices:
+
+
+```json
+{
+  "bluetooth": [
+    {
+      "manufacturer_id": 76,
+      "manufacturer_data_first_byte": 6
+    }
+  ]
+}
+```
+
+
 ## Zeroconf
 
 If your integration supports discovery via [Zeroconf](https://en.wikipedia.org/wiki/Zero-configuration_networking), you can add the type to your manifest. If the user has the `zeroconf` integration loaded, it will load the `zeroconf` step of your integration's config flow when it is discovered.

docs/network_discovery.md

@@ -7,6 +7,61 @@ Some integrations may need to discover devices on the network via [mDNS/Zeroconf
 
 Home Assistant has built-in helpers to support mDNS/Zeroconf and SSDP. If your integration uses another discovery method that needs to determine which network interfaces to use to broadcast traffic, the [Network](https://www.home-assistant.io/integrations/network/) integration provides a helper API to access the user's interface preferences.
 
+## Bluetooth
+
+### Subscribing to Bluetooth discoveries
+
+Some integrations may need to know when a device is discovered right away. The Bluetooth integration provides a registration API to receive callbacks when a new device is discovered that matches specific key values. The same format for `bluetooth` in [`manifest.json`](creating_integration_manifest.md#bluetooth) is used for matching.
+
+The function `bluetooth.async_register_callback` is provided to enable this ability. The function returns a callback that will cancel the registration when called.
+
+The below example shows registering to get callbacks when a Switchbot device is nearby.
+
+```python
+from homeassistant.components import bluetooth
+
+...
+
+@callback
+def _async_discovered_device(service_info: bluetooth.BluetoothServiceInfo, change: bluetooth.BluetoothChange) -> None:
+    """Subscribe to bluetooth changes."""
+    _LOGGER.warning("New service_info: %s", service_info)
+
+entry.async_on_unload(
+    bluetooth.async_register_callback(
+        hass, _async_discovered_device, {"service_uuids": {"cba20d00-224d-11e6-9fb8-0002a5d5c51b"}}
+    )
+)
+```
+
+The below example shows registering to get callbacks for HomeKit devices.
+
+```python
+from homeassistant.components import bluetooth
+
+...
+
+entry.async_on_unload(
+    bluetooth.async_register_callback(
+        hass, _async_discovered_homekit_device, {"manufacturer_id": 76, "manufacturer_data_first_byte": 6}
+    )
+)
+```
+
+The below example shows registering to get callbacks for Nespresso Prodigios.
+
+```python
+from homeassistant.components import bluetooth
+
+...
+
+entry.async_on_unload(
+    bluetooth.async_register_callback(
+        hass, _async_nespresso_found, {"local_name": "Prodigio_*")}
+    )
+)
+```
+
 ## mDNS/Zeroconf
 
 Home Assistant uses the [python-zeroconf](https://github.com/jstasiak/python-zeroconf) package for mDNS support. As running multiple mDNS implementations on a single host is not recommended, Home Assistant provides internal helper APIs to access the running `Zeroconf` and `AsyncZeroconf` instances.