{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Device Scanner" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Device scanners are used to find devices that are connected to the host. For each device type, there is a specific type of device scanner. Currently there are these types of specific device scanners:\n", "\n", "- `USBDeviceScanner` for `USBDevice`\n", "- `LANDeviceScanner` for `LANDevice`\n", "\n", "In addition to these specific device scanners, there is also a general device scanner. This one contains all specific device scanners and hence searches for each supported type of device. The general device scanner is represented by the class `DeviceScanner`.\n", "\n", "All classes of device scanners inherit from the abstract `BaseDeviceScanner`-class. Therefore, all device scanners are used the same way." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Platform dependency of device scanners\n", "\n", "Each platform uses different ways to manage their connections to external devices. But nevertheless, the DeviceManager package is developed to work as user friendly as possible.\n", "\n", "When you are importing a device scanner for a specific type, the `device_manager.scanner`-module automatically redirects the `import`-statement to the corresponding device scanner, depending on what platform you are using. The following platforms are supported at the moment:\n", "\n", "- Windows (`import`-Redirection to `device_manager.scanner._win32`):\n", " - `USBDeviceScanner` → `device_manager.scanner._win32.Win32USBDeviceScanner`\n", " - `LANDeviceScanner` → `device_manager.scanner._win32.Win32LANDeviceScanner`\n", "- Linux (`import`-Redirection to `device_manager.scanner._linux`):\n", " - `USBDeviceScanner` → `device_manager.scanner._linux.LinuxUSBDeviceScanner`\n", " - `LANDeviceScanner` → `device_manager.scanner._linux.LinuxLANDeviceScanner`" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\n", "\n" ] } ], "source": [ "from device_manager import USBDeviceScanner, LANDeviceScanner\n", "\n", "print(USBDeviceScanner)\n", "print(LANDeviceScanner)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The usage of the platform depending device scanners are exactly the same. Your scripts should be easily portable between those platforms, without any changes to your code. However, the general `DeviceScanner` is the same for all platforms because it does not contain any platform depending code." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Usage" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Basic functionality\n", "\n", "The usage of all specific device scanners is the same. Only the general device scanner has some additional abilities which are discussed below.\n", "\n", "Each specific device scanner consists of the functions `list_devices` and `find_devices`, no more and no less. The implementation behind might be very different, but the usage exactly the same. Both functions scan the for all available devices and store them internally. When you call `list_devices` you get a list of all found devices." ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "(USBDevice('USB\\\\VID_413C&PID_5534\\\\4&3FFD8F2A&0&21'),\n", " USBDevice('USB\\\\VID_413C&PID_2513\\\\6&1FFE1F1B&1&2'),\n", " USBDevice('USB\\\\VID_0B15&PID_3401\\\\0123456789ABCD'),\n", " USBDevice('USB\\\\VID_413C&PID_2134\\\\ABC1234'),\n", " USBDevice('USB\\\\VID_1130&PID_1620\\\\XYZWVUT975310'),\n", " USBDevice('USB\\\\VID_0781&PID_5581\\\\01171114'),\n", " USBDevice('USB\\\\VID_1BCF&PID_2B8D\\\\4C5DDB4'))" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "usb_scanner = USBDeviceScanner()\n", "\n", "usb_scanner.list_devices()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `find_devices`-function accepts as many filter-parameters as you want to. The parameter names must match the names of the `Device`-properties you want to compare. All `Device`s matching each filter you have passed will be returned." ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "(USBDevice('USB\\\\VID_413C&PID_5534\\\\4&3FFD8F2A&0&21'),\n", " USBDevice('USB\\\\VID_413C&PID_2513\\\\6&1FFE1F1B&1&2'),\n", " USBDevice('USB\\\\VID_413C&PID_2134\\\\ABC1234'))" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Find all devices with vendor_id == 0x413C\n", "usb_scanner.find_devices(vendor_id=0x413C)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "After the first successful scan for connected devices, the results are stored internally. Afterwards, the device scanner only retuns those cached devices. If any new device connects in the meantime, it will not make it to the search results. If you want the device scanner to rescan, you have to specify it explicitly with the argument `rescan`. By calling `list_devices(rescan=True)` or `find_devices(rescan=True, ...)` the device scanner is forced to scan again." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Additional functionality of the general device scanner\n", "\n", "As already mentioned above, the `DeviceScanner`-class that combines all specific device scanner, has some additional features. Nevertheless, the functions `list_devices` and `find_devices` are used the same way. Internally it simply forwards these calls to all specific device scanners. That leads to the fact, that the `DeviceScanner` is just a container for all supported specific device scanners. To access their instances, you can use the `DeviceScanner` as a `DeviceType`-dictionary:" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "scanner[\"usb\"] \n", "scanner[\"lan\"] \n" ] } ], "source": [ "from device_manager import DeviceScanner\n", "\n", "scanner = DeviceScanner()\n", "\n", "print(\"scanner[\\\"usb\\\"]\", scanner[\"usb\"])\n", "print(\"scanner[\\\"lan\\\"]\", scanner[\"lan\"])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Because of the flexibility of the `DeviceType`-enumeration, you can use `DeviceType`-objects as keys, as well as strings, `Device`-classes or `Device`-objects." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.8.1" }, "nbsphinx": { "execute": "never" } }, "nbformat": 4, "nbformat_minor": 4 }