diff --git a/docs/config_entries_config_flow_handler.md b/docs/config_entries_config_flow_handler.md index 8b8e540a..08d7c294 100644 --- a/docs/config_entries_config_flow_handler.md +++ b/docs/config_entries_config_flow_handler.md @@ -55,6 +55,7 @@ There are a few step names reserved for system use: | `homekit` | Invoked if your integration has been discovered via HomeKit as specified [using `homekit` in the manifest](creating_integration_manifest.md#homekit). | | `mqtt` | Invoked if your integration has been discovered via MQTT as specified [using `mqtt` in the manifest](creating_integration_manifest.md#mqtt). | | `ssdp` | Invoked if your integration has been discovered via SSDP/uPnP as specified [using `ssdp` in the manifest](creating_integration_manifest.md#ssdp). | +| `usb` | Invoked if your integration has been discovered via USB as specified [using `usb` in the manifest](creating_integration_manifest.md#usb). | | `user` | Invoked when a user initiates a flow via the user interface or when discovered and the matching and discovery step are not defined. | | `zeroconf` | Invoked if your integration has been discovered via Zeroconf/mDNS as specified [using `zeroconf` in the manifest](creating_integration_manifest.md#zeroconf). | @@ -70,9 +71,9 @@ self._abort_if_unique_id_configured() ``` 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 or SSDP/uPnP to be discovered, supplying a unique ID is required. +If the integration uses 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` and `discovery` steps can be omitted, even if they are configured in +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 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 diff --git a/docs/creating_integration_manifest.md b/docs/creating_integration_manifest.md index fad6064a..59d81e9c 100644 --- a/docs/creating_integration_manifest.md +++ b/docs/creating_integration_manifest.md @@ -233,6 +233,33 @@ For example: } ``` +## USB + +If your integration supports discovery via usb, you can add the type to your manifest. If the user has the `usb` integration loaded, it will load the `usb` step of your integration's config flow when it is discovered. We support discovery by VID (Vendor ID) and PID (Device ID). For help identifiying these values see [How To Identify A Device](https://wiki.debian.org/HowToIdentifyADevice/USB). 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 USB data. It's up to your config flow to filter out duplicates. + +The following example has two matchers consisting of two items. All of the items in any of the two matchers must match for discovery to happen by this config. + +For example: + +- If the `vid` was `AAAA` and the `pid` was `AAAA`, the discovery would happen. +- If the `vid` was `AAAA` and the `pid` was `FFFF`, the discovery would not happen. +- If the `vid` was `CCCC` and the `pid` was `AAAA`, the discovery would not happen. + +```json +{ + "usb": [ + { + "vid": "AAAA", + "pid": "AAAA" + }, + { + "vid": "BBBB", + "pid": "BBBB" + }, + ] +} +``` + ## Integration Quality Scale The [Integration Quality Scale](https://www.home-assistant.io/docs/quality_scale/) scores an integration on the code quality and user experience. Each level of the quality scale consists of a list of requirements. If an integration matches all requirements, it's considered to have reached that level.