diff --git a/docs/source/install.rst b/docs/source/install.rst index 69aa20093..2cd3a7cd2 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -34,6 +34,7 @@ Fedora `Di Robot Operating System `Discord `__ Windows 7 :ref:`WinUSB driver ` `Discord `__ Docker :ref:`Pull and run official images ` `Discord `__ +Kernel Virtual Machine :ref:`Run on KVM ` `Discord `__ ====================== ===================================================== ================================================================================ macOS @@ -147,6 +148,68 @@ Run the :code:`01_rgb_preview.py` example inside a Docker container on a Linux h To allow the container to update X11 you may need to run :code:`xhost local:root` on the host. +KVM +*** + +To access the OAK-D camera in the `Kernel Virtual Machine `__, there is a need to attach and detach USB +devices on the fly when the host machine detects changes in the USB bus. + +OAK-D camera changes the USB device type when it is used by DepthAI API. This happens in backgound when the camera is used natively. +But when the camera is used in a virtual environment the situation is different. + +On your host machine, use the following code: + +.. code-block:: bash + + SUBSYSTEM=="usb", ACTION=="bind", ENV{ID_VENDOR_ID}=="03e7", MODE="0666", RUN+="/usr/local/bin/movidius_usb_hotplug.sh depthai-vm" + SUBSYSTEM=="usb", ACTION=="remove", ENV{PRODUCT}=="3e7/2485/1", ENV{DEVTYPE}=="usb_device", MODE="0666", RUN+="/usr/local/bin/movidius_usb_hotplug.sh depthai-vm" + SUBSYSTEM=="usb", ACTION=="remove", ENV{PRODUCT}=="3e7/f63b/100", ENV{DEVTYPE}=="usb_device", MODE="0666", RUN+="/usr/local/bin/movidius_usb_hotplug.sh depthai-vm" + +The script that the udev rule is calling (movidius_usb_hotplug.sh) should then attach/detach the USB device to the virtual machine. +In this case we need to call :code:`virsh` command. For example, the script could do the following: + +.. code-block:: bash + + #!/bin/bash + # Abort script execution on errors + set -e + if [ "${ACTION}" == 'bind' ]; then + COMMAND='attach-device' + elif [ "${ACTION}" == 'remove' ]; then + COMMAND='detach-device' + if [ "${PRODUCT}" == '3e7/2485/1' ]; then + ID_VENDOR_ID=03e7 + ID_MODEL_ID=2485 + fi + if [ "${PRODUCT}" == '3e7/f63b/100' ]; then + ID_VENDOR_ID=03e7 + ID_MODEL_ID=f63b + fi + else + echo "Invalid udev ACTION: ${ACTION}" >&2 + exit 1 + fi + echo "Running virsh ${COMMAND} ${DOMAIN} for ${ID_VENDOR}." >&2 + virsh "${COMMAND}" "${DOMAIN}" /dev/stdin < + + + + + + END + exit 0 + + +Note that when the device is disconnected from the USB bus, some udev environmental variables are not available (:code:`ID_VENDOR_ID` or :code:`ID_MODEL_ID`), +that is why you need to use :code:`PRODUCT` environmental variable to identify which device has been disconnected. + +The virtual machine where DepthAI API application is running should have defined a udev rules that identify the OAK-D camera. +The udev rule is decribed `here `__ + +Solution provided by `Manuel Segarra-Abad `__ + + Install from PyPI #################