jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-08 09:56:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Adjust USB discovery to document serial_number/description/manufacturer matching (#1039)

Browse Source 
* Adjust USB discovery to document serial_number/description/manufacturer matching

https://github.com/home-assistant/core/pull/55236

* Update creating_integration_manifest.md

* Update creating_integration_manifest.md

* Update docs/creating_integration_manifest.md

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
J. Nick Koston 2021-08-27 09:02:36 -05:00 committed by GitHub
parent 1a7b2f859e
commit ebe1f4f010
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 13 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/creating_integration_manifest.md
View File

@ -235,7 +235,11 @@ 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.
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), PID (Device ID), Serial Number, Manufacturer, and Description by extracting these values from the USB descriptor. 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.
:::warning
Some VID and PID combinations are used by many unrelated devices. For example VID `10C4` and PID `EA60` matches any Silicon Labs CP2102 USB-Serial bridge chip. When matching these type of devices, it is important to match on `description` or another identifer to avoid an unexpected discovery.
:::
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.
@ -244,6 +248,7 @@ 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.
- If the `vid` was `1234`, the `pid` was `ABCD`, the `serial_number` was `12345678`, the `manufacturer` was `Midway USB`, and the `description` was `Version 12 Zigbee Stick`, the discovery would happen.
```json
{
@ -256,6 +261,13 @@ For example:
"vid": "BBBB",
"pid": "BBBB"
},
{
"vid": "1234",
"pid": "ABCD",
"serial_number": "1234*",
"manufacturer": "*midway*",
"description": "*zigbee*"
},
]
}
```