> ## Documentation Index > Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL. > Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other. > Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking. > Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify. # Identify and Configure PCI Passthrough by Vendor ID > Identify a USB device by its vendor and product ID using lsusb, then add it as a USB Device I/O member in a custom hardware model. ## Introduction USB passthrough gives a virtual machine (VM) direct access to a specific USB device connected to a node. When multiple USB devices of the same type are connected, you can target a specific device by its vendor ID and product ID (the pair of identifiers assigned by the device manufacturer). This article explains how to find a USB device's vendor and product ID using `lsusb` on an EVE-OS (Edge Virtualization Engine) node, how to add the device as a USB Device I/O member in a custom hardware model, and what the GUI supports versus what requires the API. For the full workflow to identify USB controllers and configure USB PCI passthrough, see [Configure USB PCI Passthrough](https://zededa.mintlify.site/new-ui/marketplace/configure-usb-pci-passthrough.md). ## Prerequisites * You have a cluster or CSP administrator role. Creating custom hardware models is available to cluster and CSP administrators only. Enterprise users with SysAdmin or SysManager roles can import existing catalog models but cannot create or edit hardware models. * The target node runs EVE-OS and is enrolled in Edge Infrastructure Services. * You have SSH access to the node, or access to the EVE-OS console. * `lsusb` is available on the node. * You have an existing custom hardware model in the catalog, or you will create one as part of this procedure. See [Import Hardware Models](https://zededa.mintlify.site/new-ui/marketplace/import-hardware-models.md). ## Identify the USB Device by Vendor and Product ID Every USB device exposes a vendor ID (VID) and product ID (PID) that uniquely identify its manufacturer and device type. Use `lsusb` to list connected USB devices and locate the correct IDs. 1. Connect to the EVE-OS node via SSH or the console. 2. Run the following command to list all connected USB devices: ```bash theme={"dark"} lsusb ``` 3. Review the output. Each line follows this format: ``` Bus Device : ID : ``` For example: ``` Bus 003 Device 033: ID 045e:0823 Microsoft Corp. Classic IntelliMouse ``` In this example: * `045e` is the vendor ID (Microsoft Corp.). * `0823` is the product ID (Classic IntelliMouse). * `Bus 003 Device 033` is the current bus and device address (these may change across reboots). 4. Record the vendor ID and product ID for the target device. 5. To confirm the physical port the device is connected to, run the following command to show the USB tree with port mappings: ```bash theme={"dark"} lsusb -tv ``` Locate the device by its vendor ID and product ID in the tree output to identify which port it occupies. ## Add the Device to a Hardware Model After identifying the USB device, add it as a USB Device I/O member in a custom hardware model. The hardware model GUI uses physical and logical labels to identify the device, not vendor or product IDs directly. This step requires a cluster or CSP administrator role; only cluster and CSP administrators can create hardware models. When naming labels, include the vendor ID and product ID in the physical or logical label so the device remains identifiable in the UI. 1. In the sidebar, select **Marketplace**. 2. Select **Catalog**. 3. Select the **Hardware** filter tab. 4. Select an existing hardware model to update, or select **Create Model** to create a new one. For instructions on creating a hardware model, see [Import Hardware Models](https://zededa.mintlify.site/new-ui/marketplace/import-hardware-models.md). 5. In the **I/O Members** section, select **Add I/O**. 6. Set the **Adapter Type** to **USB Device**. 7. In the **Physical label** field, enter a label that identifies the physical port and device. Include the vendor ID and product ID for reference. For example: ``` usb-vid045e-pid0823 ``` 8. In the **Logical label** field, enter the name that EVE-OS uses to identify this adapter. For example: ``` usb-microsoft-intellimouse ``` 9. Optionally, set **Assign group** to group this adapter with related adapters. 10. Select **Create** to save the hardware model. ### Label-based identification The Create Model dialog does not have vendor ID or product ID input fields. The GUI identifies USB Device adapters by their physical and logical labels. When assigning the hardware model to a node, EVE-OS matches the USB Device entry to a connected device by port position, not by vendor ID. Vendor ID-level filtering (the `usbproduct` field) is available through the ZEDEDA API and ZCLI for advanced use cases where you need to restrict passthrough to a specific vendor and product combination regardless of port position. Contact your ZEDEDA account team for API documentation. ## Caveats * **USB hubs are not supported for passthrough.** You cannot pass through a USB hub device itself. Pass through the individual devices connected downstream from the hub. * **Port numbers might differ between USB 2.0 and USB 3.0.** The same physical port on a device might appear as separate bus:port addresses depending on which USB version the device negotiates. Identify both mappings if you need version-specific passthrough. * **USB passthrough requires QEMU.** This feature is only supported on VM-type edge containers using the QEMU hypervisor (the open-source machine emulator used by EVE-OS for VM workloads). Container and unikernel workloads do not support USB passthrough. * **Thunderbolt and USB4 are not supported.** Devices connected via Thunderbolt or USB4 ports cannot be passed through using this method. * **Device address is not stable across reboots.** The `Bus` and `Device` numbers shown by `lsusb` might change when the node reboots or when devices are reconnected. Use port position (from `lsusb -tv`) rather than device address for reliable identification. * **Changes to a hardware model apply to all nodes that use it.** Updates to a hardware model are automatically reflected on every node in the enterprise that references that hardware model. Test changes in a lab environment before applying them to production nodes. ## Next Steps > [card] [Configure USB PCI Passthrough](https://zededa.mintlify.site/new-ui/marketplace/configure-usb-pci-passthrough.md) > > The full procedure to identify USB controllers and configure USB Device splitting for individual port passthrough. > [card] [Import Hardware Models](https://zededa.mintlify.site/new-ui/marketplace/import-hardware-models.md) > > Import an existing model from the catalog or create a custom hardware model from scratch.