This add-on allows you to attach usb devices using the linux kernel usbip kernel module. Before installation verify that your base supervisor system has the proper configurations and modules to use this add-on.
This add-on uses the host system's kernel usbip module so there are some minimum requierments of the base system that sypervisor is running on. Depending on which configuration you are using verify your system meets all dependencies.
If using Home Assistant OS the minimum requiered version is 9.0. The usbip driver was added in the 9.0 [release][hassio9.
You must install the usbip debian package with all its dependencies. It may be a good idea to test attaching a usbip device outside of home assistant in general if you are unsure how to verify this is installed.
This add-on is intended to allow you to mount one or multiple usbip devices to your Home Assistant server. The main use case is to attach "remote" bluetooth adapters that may be attached to other computers on your network. This means that another system that is running the usbip server component is requiered with the attached device. For example you may have existing Raspberry Pis in your house performing other tasks, you could attach one of the supported bluetooth adapters, install usbip and export the device for sharing. With this add-on running the adapter would show up as an additional bluetooth adapter. This is especially useful for bluetooth integrations that rely on 2way bluetooth communication as the esp32 bluetooth-proxy does not currently support those devices.
Usbip is not limited to bluetooth adapters as most usb devices should be able to function as long as they are natively supported by Home Assistant.
Note: Remember to restart the add-on when the configuration is changed.
USBIP Mounter add-on configuration:
devices:
- server_address: 10.0.0.100
bind: 1-1.4
- server_address: 10.0.0.50
bind: 1-1.5The following options are for the option list: devices. Each remote usbip devices requires all of these configuration elements.
This must be the ip address of the usbipd server that is exporting the device. Usbip uses TCP port 3240 by default, currently this add-on expects the server to be using that port.
This is the bind-id of the exported usb devices on the usbip server. Check the usbip server configuration section for more information.
Setting up the usbip server exporting the usb devices is a bit out of scope of this add-on but the following provides some useful information.
Depending on the linux distro running on your server the requiered packages will be slighty different.
Debian: apt install usbip hwdata
Ubuntu: apt-get install linux-tools-uname -r hwdata
Arch: pkg install usbip hwdata
With the correct packages installed and the usb device connected to the system you should be able to get a list of exportable usb devices by running
usbip list -lOne example of configuring usbip servers using systemd can be found here
The original setup of this repository is by Ilya Rakhlin.
MIT License
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.