Skip to content

Commit 2a960fb

Browse files
19BMG0019BMG00
authored
Merge pull request #204609 from fcabrera23/eflow-usb-ip
Eflow usb ip
2 parents e04e038 + c7a34a2 commit 2a960fb

File tree

2 files changed

+101
-0
lines changed

2 files changed

+101
-0
lines changed

‎articles/iot-edge/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,8 @@
5555
href: gpu-acceleration.md
5656
- name: Shared folders
5757
href: how-to-share-windows-folder-to-vm.md
58+
- name: Connect a USB device
59+
href: how-to-connect-usb-devices.md
5860
- name: Develop and debugging
5961
href: tutorial-develop-for-linux-on-windows.md
6062
- name: Troubleshoot

‎articles/iot-edge/how-to-connect-usb-devices.md

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
title: How to connect a USB device to Azure IoT Edge for Linux on Windows | Microsoft Docs
3+
description: How to connect a USB device using USB over IP to the Azure IoT Edge for Linux on Windows (EFLOW) virtual machine.
4+
author: PatAltimore
5+
6+
ms.service: iot-edge
7+
services: iot-edge
8+
ms.topic: conceptual
9+
ms.date: 07/25/2022
10+
ms.author: fcabrera
11+
---
12+
13+
# How to connect a USB device to Azure IoT Edge for Linux on Windows
14+
15+
In some scenarios, your workloads need to get data or communicate with USB devices. Because Azure IoT Edge for Linux on Windows (EFLOW) runs as a virtual machine, you need to connect these devices to the virtual machine. This article guides you through the steps necessary to connect a USB device to the EFLOW virtual machine using the USB/IP open-source project named [usbipd-win](https://github.com/dorssel/usbipd-win).
16+
17+
Setting up the USB/IP project on your Windows machine enables common developer USB scenarios like flashing an Arduino, connecting a USB serial device, or accessing a smartcard reader directly from the EFLOW virtual machine.
18+
19+
> [!WARNING]
20+
> *USB over IP* provides a generic mechanism for redirecting USB devices using the network between the Windows host OS and the EFLOW virtual machine. Some devices that are sensitive to network latency might experience issues. Additionally, some devices might not function as expected due to driver compatibility issues. Ensure that your devices work as expected before deploying to production. For more information about USB/IP tested devices, see [USBIP-Win - Wiki - Tested Devices](https://github.com/dorssel/usbipd-win/wiki/Tested-Devices).
21+
22+
## Prerequisites
23+
24+
- Azure IoT Edge for Linux on Windows 1.3.1 update or higher. For more information about EFLOW release notes, see [EFLOW Releases](https://aka.ms/AzEFLOW-Releases).
25+
- A machine with an x64/x86 processor is required, *usbipd-win* doesn't support ARM64.
26+
27+
> [!NOTE]
28+
> To check your Azure IoT Edge for Linux on Windows version, go to _Add or Remove Programs_ and then search for _Azure IoT Edge_. The installed version is listed under _Azure IoT Edge_. If you need to update to the latest version, see [Azure IoT Edge for Linux on Windows updates](./iot-edge-for-linux-on-windows-updates.md).
29+
30+
## Install the UsbIp-Win project
31+
32+
Support for connecting USB devices isn't natively available with EFLOW. You'll need to install the open-source [usbipd-win](https://github.com/dorssel/usbipd-win) project using the following steps:
33+
34+
1. Go to the [latest release page for the usbipd-win](https://github.com/dorssel/usbipd-win/releases) project.
35+
1. Choose and download the _usbipd-win_x.y.z.msi_ file. (You may get a warning asking you to confirm that you trust the downloaded installer).
36+
1. Run the downloaded _usbipd-win_x.y.z.msi_ installer file.
37+
38+
> [!NOTE]
39+
> Alternatively, you can also install the usbipd-win project using [Windows Package Manager](/windows/package-manager/winget/) (_winget_). If you have already installed _winget_, use the command: `winget install --interactive --exact dorssel.usbipd-win` to install usbipd-win. If you don't use the `--interactive` parameter, _winget_ may immediately restart your computer if needed to install the drivers.
40+
41+
The UsbIp-Win installs:
42+
43+
- A service called `usbipd` (USBIP Device Host). You can check the status of this service using the *Services* app in Windows.
44+
- A command line tool `usbipd`. The location of this tool is added to the PATH environment variable.
45+
- A firewall rule called `usbipd` to allow all local subnets to connect to the service. You can modify this firewall rule to fine tune access control.
46+
47+
At this point, a service is running on Windows to share USB devices, and the necessary tools are installed in the EFLOW virtual machine to attach to shared devices.
48+
49+
> [!WARNING]
50+
> If you have an open PowerShell session, make sure to close it and open a new one to load the `usbipd` command line tool.
51+
52+
## Attach a USB device to the EFLOW VM
53+
54+
The following steps provide a sample EFLOW PowerShell cmdlet to attach a USB device to the EFLOW VM. If you want to manually execute the needed commands, see [How to use usbip-win](https://github.com/dorssel/usbipd-win).
55+
56+
> [!IMPORTANT]
57+
> The following functions are samples that are not meant to be used in production deployments. For production use, ensure you validate the functionality and create your own functions based on these samples. The sample functions are subject to change and deletion.
58+
59+
1. Go to [EFLOW-Util](https://github.com/Azure/iotedge-eflow/tree/main/eflow-util/eflow-usbip) and download the EFLOW-USBIP sample PowerShell module.
60+
61+
1. Open an elevated PowerShell session by starting with **Run as Administrator**.
62+
63+
1. Import the downloaded EFLOW-USBIP module.
64+
```powershell
65+
Import-Module "<path-to-module>/EflowUtil-Usbip.psm1"
66+
```
67+
68+
1. List all of the USB devices connected to Windows.
69+
```powershell
70+
Get-EflowUSBDevices
71+
```
72+
73+
1. List all the network interfaces and get the Windows host OS IP address
74+
```powershell
75+
ipconfig
76+
```
77+
78+
1. Select the *bus ID* of the device you’d like to attach to the EFLOW.
79+
```powershell
80+
Add-EflowUSBDevices -busid <busid> -hostIp <host-ip>
81+
```
82+
83+
1. Check the device was correctly attached to the EFLOW VM.
84+
```powershell
85+
Invoke-EflowVmCommand "lsusb"
86+
```
87+
88+
1. Once you're finished using the device in EFLOW, you can either physically disconnect the USB device or run this command from an elevated PowerShell session.
89+
```powershell
90+
Remove-EflowUSBDevices -busid <busid>
91+
```
92+
> [!IMPORTANT]
93+
> The attachment from the EFLOW VM to the USB device does not persist across reboots. To attach the USB device after reboot, you may need to create a bash script that runs during startup and connects the device using the `usbip` bash command. For more information about how to attach the device on the EFLOW VM side, see [Add-EflowUSBDevices](https://github.com/Azure/iotedge-eflow/tree/main/eflow-util/eflow-usbip/EflowUtil.psm1).
94+
95+
To learn more about how USB over IP, see the [Connecting USB devices to WSL](https://devblogs.microsoft.com/commandline/connecting-usb-devices-to-wsl/#how-it-works) and the [usbipd-win repo on GitHub](https://github.com/dorssel/usbipd-win/wiki).
96+
97+
## Next steps
98+
99+
Follow the steps in [How to develop IoT Edge modules with Linux containers using IoT Edge for Linux on Windows.](./tutorial-develop-for-linux-on-windows.md) to develop and debug a module with IoT Edge for Linux on Windows.

0 commit comments

Comments
 (0)