Unique “friendly name” for automatic ZWave USB adapter discovery in Home Assistant Z-Wave JS using dongle vendor/product IDs and description?

[Hedda]

FYI, Home Assistant developer bdraco has just now added support for automatically discovering USB adapter in Home Assistant's Z-Wave JS integration, (for more back-story and the gritty details see Home Assistant core pull requests #54904, #54935 and #54986).

I think it would therefore be much appreciated to new HA users if you consider submitting new PRs to upstream Home Assistant core with "friendly name" as a description if you got any compatible Z-Wave USB adapters which unique Vendor ID (vid) / Product ID (pid) identifier that has not yet been added to the ZWave JS component manifest in Home Assistant core:

Note! As per discussions #55225, #55236 and #1039, devices need to have unique description as generic + VID and PID are not enough.

https://www.home-assistant.io/integrations/zwave_js/#discovery-via-usb

https://github.com/home-assistant/core/blob/dev/homeassistant/components/zwave_js/manifest.json

  "usb": [
    {"vid":"0658","pid":"0200","known_devices":["Aeotec Z-Stick Gen5+", "Z-WaveMe UZB"]},
    {"vid":"10C4","pid":"8A2A","description":"*z-wave*","known_devices":["Nortek HUSBZB-1"]},
    {"vid":"10C4","pid":"EA60","known_devices":["Aeotec Z-Stick 7", "Silicon Labs UZB-7", "Zooz ZST10 700"]}
  ]

https://github.com/home-assistant/core/blob/dev/homeassistant/generated/usb.py

{
        "domain": "zwave_js",
        "vid": "0658",
        "pid": "0200"
    },
    {
        "domain": "zwave_js",
        "vid": "10C4",
        "pid": "8A2A",
        "description": "*z-wave*"
    },
    {
        "domain": "zwave_js",
        "vid": "10C4",
        "pid": "EA60"
    }

PS: The same new USB discovery in HA similarly also applies to Zigbee USB adapter for the Home Assistant's ZHA integration, see:

https://www.home-assistant.io/integrations/zha/#discovery-via-usb-or-zeroconf

https://github.com/home-assistant/core/blob/dev/homeassistant/components/zha/manifest.json

  "usb": [
   {"vid":"10C4","pid":"EA60","description":"*2652*","known_devices":["slae.sh cc2652rb stick"]},
   {"vid":"1CF1","pid":"0030","description":"*conbee*","known_devices":["Conbee II"]},
   {"vid":"10C4","pid":"8A2A","description":"*zigbee*","known_devices":["Nortek HUSBZB-1"]}
  ],

https://github.com/home-assistant/core/blob/dev/homeassistant/generated/usb.py

USB = [
    {
        "domain": "zha",
        "vid": "10C4",
        "pid": "EA60",
        "description": "*2652*"
    },
    {
        "domain": "zha",
        "vid": "1CF1",
        "pid": "0030",
        "description": "*conbee*"
    },
    {
        "domain": "zha",
        "vid": "10C4",
        "pid": "8A2A",
        "description": "*zigbee*"
    }

[AlCalzone]

This idea was floated to me too, but I've yet to see how and if that can even work in a Docker environment, which is where most instances of zwave-js are executed. I did some quick tests recently and this is the info the driver has access to:

Windows, no virtualization ✔

  {
    path: 'COM5',
    manufacturer: 'Silicon Labs',
    serialNumber: '8ad925bd7b84e911a7a7a1d6217343c2',
    pnpId: 'USB\\VID_10C4&PID_EA60\\8AD925BD7B84E911A7A7A1D6217343C2',
    locationId: 'Port_#0002.Hub_#0002',
    vendorId: '10C4',
    productId: 'EA60'
  },
  {
    path: 'COM7',
    manufacturer: 'Sigma Designs',
    serialNumber: '8&1ea3a3f6&0&1',
    pnpId: 'USB\\VID_0658&PID_0200\\8&1EA3A3F6&0&1',
    locationId: 'Port_#0001.Hub_#0002',
    vendorId: '0658',
    productId: '0200'
  }

Windows, in Docker ❌

  {
    manufacturer: undefined,
    serialNumber: undefined,
    pnpId: undefined,
    locationId: undefined,
    vendorId: undefined,
    productId: undefined,
    path: '/dev/ttyS0'
  },
  {
    manufacturer: undefined,
    serialNumber: undefined,
    pnpId: undefined,
    locationId: undefined,
    vendorId: undefined,
    productId: undefined,
    path: '/dev/ttyS1'
  },
  {
    manufacturer: undefined,
    serialNumber: undefined,
    pnpId: undefined,
    locationId: undefined,
    vendorId: undefined,
    productId: undefined,
    path: '/dev/ttyS2'
  },
  {
    manufacturer: undefined,
    serialNumber: undefined,
    pnpId: undefined,
    locationId: undefined,
    vendorId: undefined,
    productId: undefined,
    path: '/dev/ttyS3'
  }

If there's a foolproof way to expose this info to the driver when in Docker, I think that would be a good UX improvement. But from the little I've seen, that requires some potentially unsafe volume mounts. Setting up the device mounts is outside our control anyways.

[Hedda]

I think it would therefore be much appreciated to new HA users if you consider submitting new PRs to upstream Home Assistant core with "friendly name" as a description if you got any compatible Z-Wave USB adapters which unique Vendor ID (vid) / Product ID (pid) identifier that has not yet been added to the ZWave JS component manifest in Home Assistant core:

Note! As per discussions #55225, #55236 and #1039, devices need to have unique description as generic + VID and PID are not enough.

https://www.home-assistant.io/integrations/zwave_js/#discovery-via-usb

https://github.com/home-assistant/core/blob/dev/homeassistant/components/zwave_js/manifest.json

...

https://github.com/home-assistant/core/blob/dev/homeassistant/generated/usb.py

I only posted this to reach out to the Z-Wave JS community in order to get help with populating the Home Assistant's Z-Wave JS integration component with unique identifiers.

The USB Discovery feature works at the Home Assistant OS (formerly known as "Hassio") level and is only used to help users find + start integration setup:

https://www.home-assistant.io/blog/2021/09/01/release-20219/#usb-discovery:

That is, this USB discovery is all done even before Z-Wave JS is executed on a Home Assistant OS instance for the very first time.

So that part is not an issue when run Home Assistant in Home Assistant OS as runs its Supervisor which is what handles this there:

https://www.home-assistant.io/blog/2020/09/16/supervisor-joins-the-party/

If users run Home Assistant OS then simply plug-in a whitelisted Z-Wave USB adapter and users get a pop-up about a discovered controller.

[AlCalzone]

I only posted this request to the Z-Wave JS to help populate the Home Assistant's Z-Wave JS integration component with unique identifiers.

Sorry, I misunderstood...
Due to the sheer amount of issues I'm getting, I don't have much time to read everything in detail, so I'm mostly just scanning issues. So the shorter, the better.

I don't know of any other identifiers. Silabs' 700 controller is a development tool, which is why they don't bother changing it. But apparently most OEMs don't change the VID/PID either or we wouldn't have multiple sticks from different manufacturers with the same IDs.

[Hedda]

apparently most OEMs don't change the VID/PID either or we wouldn't have multiple sticks from different manufacturers with the same IDs.

Using the same VID and PID is would still be OK and work as long as they either use a unique string name as device description too or the device name description that OEM use is always a Z-Wave controller anyway. Both those would allow HA to redirect user to the Z-Wave JS integration configuration for further probing.

[Hedda]

FYI, Silicon Labs UZB-7 USB Stick (Silabs SLUSB001A / SLUSB7000A) Z-Wave 700 Controller with its default USB-to-serial converter EEPROM settings can probably not be whitelisted for automatic USB discovery in Home Assistant with the current probing method used since the hardware is presented as a generic "CP2102N USB to UART Bridge Controller" with factory default ID information:

#2544

VID = 10c4
PID = ea60
Device Name = CP2102N USB to UART Bridge Controller

I guess that Silabs could not be bothered for this reference dongle hardware, however CP2102 specification does list it has writable EEPROM:

https://www.silabs.com/documents/public/data-sheets/CP2102-9.pdf

"The CP2102 includes an internal electrically erasable programmable read-only memory (EEPROM), and the
CP2109 includes an internal one-time programmable (OTP) erasable programmable read-only memory (EPROM).
Either may be used to customize the USB Vendor ID (VID), Product ID (PID), Product Description String, Power
Descriptor, Device Release Number and Device Serial Number as desired for OEM applications. If the EEPROM/
EPROM is not programmed with OEM data, the default configuration data shown in Table 13 is used. The
EEPROM has a typical endurance of 100,000 write cycles with a data retention of 100 years. The EPROM can only
be written one time and cannot be erased."

While customization of the USB configuration data is optional, it is recommended to customize the VID/PID
combination. A unique VID/PID combination will prevent the driver from conflicting with any other USB driver. A
vendor ID can be obtained from http://www.usb.org/ or Silicon Laboratories can provide a free PID for the OEM
product that can be used with the Silicon Laboratories VID. It is also recommended to customize the serial number
if the OEM application is one in which it is possible for multiple CP2102/9-based devices to be connected to the
same PC."

The internal programmable ROM is programmed via the USB. This allows the OEM's USB configuration data and
serial number to be written to the CP2102/9 on-board ROM during the manufacturing and testing process. A standalone
utility for programming the internal programmable ROM is available from Silicon Laboratories. A library of
routines provided in the form of a Windows® DLL is also available. This library can be used to integrate the
programmable ROM programming step into custom software used by the OEM to streamline testing and serial
number management during manufacturing."

[blhoward2]

I know that I’m late to the game here, but the HA devs already reached out to the manufacturers to ask them to change the VID/PID. They’ve removed automatic detection for the 700 sticks as it falsely hits on anything with the same serial adapter, which is quite a number of devices.

[Hedda]

Note that manufacturers don't need to change VID or PID, as instead they only change so have a unique "Product Description" string.

In fact, they should preferably not change VID or PID as then they need to provide custom device drivers for their USB stick as well.

I hope that just convincing manufacturers to change to a unique "Product Description" string should be less of an effort?

As a real-world example, ITead recently released a script that only changes the "Product Description" string on the CP2102N chip in their Sonoff Zigbee 3.0 USB Dongle Plus adapter because they forgot to change that on the first batches that they shipped, and once you write that new unique "Product Description" string those USB adapters can be automatically discovered by the ZHA Zigbee integration in HA.

Only changing the "Product Description" string eliminates the need for the complex process of releasing and distributing new drivers.

[Hedda]

In slightly related news VCTLabs is working on updating the cp210x-program which is an open-source tool for writing changes to CP210x:

https://github.com/VCTLabs/cp210x-program

Silicon Labs CP210x USB to UART Bridge / Serial Converter chips CP2104, CP2102, and CP2102N are commonly used in Z-Wave USB sticks.

https://www.silabs.com/interface/usb-bridges/usbxpress

https://www.silabs.com/documents/public/data-sheets/cp2102n-datasheet.pdf

If you are a developer then guess this would be best tested on Silabs official CP2102N USBXpress Bridge Development Kits?

https://www.silabs.com/development-tools/interface

https://www.silabs.com/development-tools/interface/cp2102n-development-kit

https://www.silabs.com/development-tools/interface/cp2102n-mini-development-kit

https://www.silabs.com/development-tools/interface/cp2104ek-development-kit

https://www.silabs.com/development-tools/interface/cp2104-mini-development-kit