How to connect a USB device to Azure IoT Edge for Linux on Windows
Applies to: IoT Edge 1.4
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.
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.
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.
- Azure IoT Edge for Linux on Windows 1.3.1 update or higher. For more information about EFLOW release notes, see EFLOW Releases.
- A machine with an x64/x86 processor is required, usbipd-win doesn't support ARM64.
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.
Install the UsbIp-Win project
Support for connecting USB devices isn't natively available with EFLOW. You'll need to install the open-source usbipd-win project using the following steps:
- Go to the latest release page for the usbipd-win project.
- 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).
- Run the downloaded usbipd-win_x.y.z.msi installer file.
Alternatively, you can also install the usbipd-win project using Windows Package Manager (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.
The UsbIp-Win installs:
- A service called
usbipd(USBIP Device Host). You can check the status of this service using the Services app in Windows.
- A command line tool
usbipd. The location of this tool is added to the PATH environment variable.
- A firewall rule called
usbipdto allow all local subnets to connect to the service. You can modify this firewall rule to fine tune access control.
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.
If you have an open PowerShell session, make sure to close it and open a new one to load the
usbipd command line tool.
Attach a USB device to the EFLOW VM
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.
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.
Go to EFLOW-Util and download the EFLOW-USBIP sample PowerShell module.
Open an elevated PowerShell session by starting with Run as Administrator.
Import the downloaded EFLOW-USBIP module.
List all of the USB devices connected to Windows.
List all the network interfaces and get the Windows host OS IP address
Select the bus ID of the device you'd like to attach to the EFLOW.
Add-EflowUSBDevices -busid <busid> -hostIp <host-ip>
Check the device was correctly attached to the EFLOW VM.
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.
Remove-EflowUSBDevices -busid <busid>
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.
Follow the steps in How to develop IoT Edge modules with Linux containers using IoT Edge for Linux on Windows. to develop and debug a module with IoT Edge for Linux on Windows.