USB_Passthru_on_UnRaid_to_HassOS_VM

USB_Passthru_on_UnRaid_to_HassOS_VM.txt

- A lot of credit to: https://www.labsrc.com/unraid-automatic-usb-hotplugging-libvirt/
- And also the follwing script which I modified slightly to fix some syntax errors:
https://raw.githubusercontent.com/labsrc/Libvirt-USB-Hotplugging/master/usbhotplug.sh


##### Launch the UnRaid Terminal #####

- From the UnRaid Web GUI, click the "Terminal" icon towards the upper-right of the page (it should be right below Uptime)
- All of the below commands will be run from this terminal


##### Before Plugging in ConBee Stick #####

- Run the following command:

    lsusb

- Output should look something like the following (depending on the devices you have available on your system):

    Bus 002 Device 002: ID 090c:1000 Silicon Motion, Inc. - Taiwan (formerly Feiya Technology Corp.) Flash Drive
    Bus 002 Device 003: ID 2109:0813 VIA Labs, Inc. USB3.0 Hub
    Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
    Bus 001 Device 005: ID 0c45:7403 Microdia Foot Switch
    Bus 001 Device 003: ID 1a40:0101 Terminus Technology Inc. Hub
    Bus 001 Device 002: ID 090c:1000 Silicon Motion, Inc. - Taiwan (formerly Feiya Technology Corp.) Flash Drive
    Bus 001 Device 004: ID 8087:0aaa Intel Corp.
    Bus 001 Device 006: ID 2109:2813 VIA Labs, Inc. USB2.0 Hub
    Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub


##### After Plugging in ConBee Stick #####

- Run the following command:

    lsusb

- Output should look something like the following (depending on the devices you have available on your system):

    Bus 002 Device 002: ID 090c:1000 Silicon Motion, Inc. - Taiwan (formerly Feiya Technology Corp.) Flash Drive
    Bus 002 Device 003: ID 2109:0813 VIA Labs, Inc. USB3.0 Hub
    Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
    Bus 001 Device 005: ID 0c45:7403 Microdia Foot Switch
    Bus 001 Device 003: ID 1a40:0101 Terminus Technology Inc. Hub
    Bus 001 Device 002: ID 090c:1000 Silicon Motion, Inc. - Taiwan (formerly Feiya Technology Corp.) Flash Drive
    Bus 001 Device 004: ID 8087:0aaa Intel Corp.
    Bus 001 Device 007: ID 0403:6015 Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)
    Bus 001 Device 006: ID 2109:2813 VIA Labs, Inc. USB2.0 Hub
    Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

- Note that 'Bus 001 Device 007' is our ConBee stick because it appeared right after we plugged it in


##### Get Model, Vendor, and Product Info #####

- Run the following command (replace 001 and 007 with whatever the Bus and Device numbers are for your system)

    udevadm info /dev/bus/usb/001/007 | egrep "ID_VENDOR_ID=|ID_MODEL_ID=|PRODUCT|ID_SERIAL="

- Output should look something like:

    E: ID_MODEL_ID=6015
    E: ID_SERIAL=FTDI_FT230X_Basic_UART_DM01E4ZY
    E: ID_VENDOR_ID=0403
    E: PRODUCT=403/6015/1000


##### Create an .xml File That Tells UnRaid What To Do with the USB Device #####

- Run the below commands. Replace '0403' with whatever your ID_VENDOR_ID was from the previous step. Replace '6015' with whatever your ID_MODEL_ID is.

mkdir -p /etc/libvirt/qemu/USB
nano /etc/libvirt/qemu/USB/usb-0403-6015.xml

- After running the above 'nano ...' command, you will be inside the file usb-0403-6015.xml
We want to add the following information to this file.

<hostdev mode='subsystem' type='usb'>
  <source>
    <vendor id='0x0403'/>
    <product id='0x6015'/>
  </source>
</hostdev>

- Save the file by pressing 'Ctrl + o' on your keyboard and then press Enter. Exit the file by pressing 'Ctrl + x' on your keyboard.
- I had problems with line endings, so run the following to be sure that the file is using unix line endings:

    sed -i 's/\r$//' /etc/libvirt/qemu/USB/usb-0403-6015.xml


##### Create Some Rules that Tell UnRaid What To Do Whenever this USB Stick is Plugged/Unplugged #####

- Essentially, we're going to create some rules that tell UnRaid to run a script called 'callusbhotplug.sh' whenver the
USB stick is plugged-in/unplugged. (We will create the callusbhotplug.sh script in the next section)
- Run the following command to create and enter the .rules file:

    nano /boot/config/90-libvirt-usb.rules

- After running the above command, you will be inside the file 90-libvirt-usb.rules
We want to add the following information to this file. Make sure you substitute all values for your particular situation.
Refer to the output from the 'udevadm ...' command we ran earlier. Also, take note that in my setup, the name of my
HassOS VM is HassOS_TestA

ACTION=="add", \
    ENV{PRODUCT}=="403/6015/1000", \
    RUN+="/usr/bin/bash /boot/config/callusbhotplug.sh 'add' 'HassOS_TestA' '0403' '6015'"
ACTION=="remove", \
    ENV{PRODUCT}=="403/6015/1000", \
    RUN+="/usr/bin/bash /boot/config/callusbhotplug.sh 'remove' 'HassOS_TestA' '0403' '6015'"

- Save the file by pressing 'Ctrl + o' on your keyboard and then press Enter. Exit the file by pressing 'Ctrl + x' on your keyboard.
- I had problems with line endings, so run the following to be sure that the file is using unix line endings:

    sed -i 's/\r$//' /boot/config/90-libvirt-usb.rules


##### Create the callusbhotplug.sh Script #####

- Run the following command to create and enter the callusbhotplug.sh file:

    nano /boot/config/callusbhotplug.sh

- After running the above command, you will be inside the file 90-libvirt-usb.rules
We want to add the following information to this file.

#!/bin/bash
/usr/bin/bash /boot/config/usbhotplug.sh $1 $2 $3 $4 & disown

- Save the file by pressing 'Ctrl + o' on your keyboard and then press Enter. Exit the file by pressing 'Ctrl + x' on your keyboard.
- I had problems with line endings, so run the following to be sure that the file is using unix line endings:

    sed -i 's/\r$//' /boot/config/callusbhotplug.sh



##### Create the usbhotplug.sh Script #####

- Run the following commands:

    nano /boot/config/usbhotplug.sh

- After running the above command, you will be inside the file usbhotplug.sh
We want to add the following information to this file.


#!/bin/bash
action=$1
vmname=$2
vendorid=$3
productid=$4
sleepon=false
timecheckfile="/root/usb-${vendorid}-${productid}"
#touch -a /root/runcheck

# Check if timecheck file exists
if [ -f "$timecheckfile" ]; then
	lastruntime=$(stat -c %X ${timecheckfile})
else
	lastruntime=0
fi

# Compare Last Time Device was Added/Removed
currenttime=$(date +%s)
timecheck=$(( ${currenttime} - ${lastruntime} ))
echo ${timecheck} >> /root/usbtimelog

# Check if Device is already attached to VM
devcheck=$(/usr/sbin/virsh dumpxml ${vmname} | grep -A1 -e "<vendor id='0x"${vendorid}"'/>" | grep -c -e "<product id='0x"${productid}"'/>")

# Remove All Instances of Device
removeDevice () {
	maxloop=5
	while [[ ${devcheck} -gt 0 ]]; do
		if [[ ${maxloop} -gt 0 ]]; then
			/usr/sbin/virsh detach-device ${vmname} /etc/libvirt/qemu/USB/usb-${vendorid}-${productid}.xml 2>&1 | while read line; do echo "[$(date '+%Y-%m-%d %H:%M:%S')]  $line" >> /root/usbhotplug.log; done;
			((--maxloop))
			sleep 2
		else
			break
		fi
	done
}

# Add Device Function
addDevice () {
	/usr/sbin/virsh attach-device ${vmname} /etc/libvirt/qemu/USB/usb-${vendorid}-${productid}.xml --current 2>&1 | while read line; do echo "[$(date '+%Y-%m-%d %H:%M:%S')]  $line" >> /root/usbhotplug.log; done;
}

# Main Code
if [[ ${action} == 'add' ]]; then
	if [[ ${timecheck} -gt 2 ]]; then
		touch -a ${timecheckfile}
		removeDevice
		addDevice
		sleepon=true
	else
		touch -a /root/usbattachnotrun
		exit 0
	fi
elif [[ ${action} == 'remove' ]]; then
	if [[ ${timecheck} -gt 2 ]]; then
		touch -a ${timecheckfile}
		removeDevice
	else
		touch -a /root/usbdetachnotrun
		exit 0
	fi
else
	echo "Incorrect or Missing Argument"
	exit 1
fi

if [[ ${sleepon} == true ]]; then
	sleep 2
fi


- Save the file by pressing 'Ctrl + o' on your keyboard and then press Enter. Exit the file by pressing 'Ctrl + x' on your keyboard.
- I had problems with line endings, so run the following to be sure that the file is using unix line endings:

    sed -i 's/\r$//' /boot/config/usbhotplug.sh


##### Make Sure Everything We Just Did Survives an UnRaid Server Reboot #####

- Run the following command to enter the go file (it should already exist):

    nano /boot/config/go

- After running the above command, you will be inside the file go
Add the folowing lines right below the line: #!/bin/bash

cp /boot/config/90-libvirt-usb.rules /etc/udev/rules.d
chmod 644 /etc/udev/rules.d/90-libvirt-usb.rules

- Altogether, my go file looked like this:

    #!/bin/bash
    cp /boot/config/90-libvirt-usb.rules /etc/udev/rules.d
    chmod 644 /etc/udev/rules.d/90-libvirt-usb.rules
    
    # Start the Management Utility
    /usr/local/sbin/emhttp &

- Save the file by pressing 'Ctrl + o' on your keyboard and then press Enter. Exit the file by pressing 'Ctrl + x' on your keyboard.
- I had problems with line endings, so run the following to be sure that the file is using unix line endings:

    sed -i 's/\r$//' /boot/config/go


##### Add the CA Script UnRaid Community Plugin #####

- Enable UnRaid Community Plugins via the UnRaid Web GUI by navigating Plugins -> Install Plugin. Paste the following URL and then click "Install"
https://raw.githubusercontent.com/Squidly271/community.applications/master/plugins/community.applications.plg
- Refresh the page via your Web Browser's refresh button
- Navigate to the new "Apps" tab, and then search for 'CA User Scripts' in the search bar
- Install the 'CA User Scripts' plugin
- Go into the plugin's settings and click "Add New Script"
- In the "Name" field, enter: add_usb_on_array_online
- Click the dropdown menu and select "At First Array Start Only"
- In the UnRaid terminal, run the following command to edit the script file.

    nano /boot/config/plugins/user.scripts/scripts/add_usb_on_array_online/script

- The content of the script file should look like the below (change VMName, vendorid, and modelid to match your situation):

#!/bin/bash
VMName="HassOS_TestA"
vendorid="0403"
modelid="6015"
vendmod=$(echo "${vendorid}:${modelid}")
state=$(virsh list --all | grep " $VMName " | awk '{ print $3}')

i=0
while ([ "$state" != "running" ] && [ "$i" -le 14 ]); do
    i=$(($i+1))
    sleep 10
    state=$(virsh list --all | grep " $VMName " | awk '{ print $3}')
done

# Now that the VM is online, attach the USB stick if it exists
if [[ $(lsusb | grep -c $vendmod) == 1 ]]; then
    # Wait another 30 seconds
    sleep 30
    /usr/bin/bash /boot/config/callusbhotplug.sh 'add' $VMName $vendorid $modelid
fi

- Save the file by pressing 'Ctrl + o' on your keyboard and then press Enter. Exit the file by pressing 'Ctrl + x' on your keyboard.
- I had problems with line endings, so run the following to be sure that the file is using unix line endings:

    sed -i 's/\r$//' /boot/config/plugins/user.scripts/scripts/add_usb_on_array_online/script


##### Reboot Your UnRaid Server #####

- IMPORTANT NOTE: Before you reboot your UnRaid Server, make sure that your HassOS VM automatically starts on boot. To do this, in the UnRaid Web GUI, navigate to
the VMs tab, and toggle the "AutoStart" switch ON for your HassOS VM 
- Reboot your UnRaid Server by navigating to the "Main" tab and scrolling all the way down until you see the "Reboot" button


##### Your USB Stick Should now be Attached to Your HassOS VM #####

- When Home Assistant comes back online, navigate to Supervisor -> System -> Host System -> click the "Hardware" button
- You should see something under 'serial' that matches ID_SERIAL from the 'udevadm ...' command we ran earlier. For example:
/dev/serial/by-id/usb-FTDI_FT230X_Basic_UART_DM01E4ZY-if00-port0


##### Setup the deCONZ Add-On #####

- In Home Assistant, navigate Supervisor -> Add-On -> deCONZ -> Click "Install"
- After the deCONZ Add-On is installed, click "Configuration" at the top of the screen, and then add something like the following and click "Save":

    device: /dev/serial/by-id/usb-FTDI_FT230X_Basic_UART_DM01E4ZY-if00-port0
    vnc_password: ''

- Click "Info", and then click "Start". After it starts, click "Open Web GUI" and configure everything from there.