Skip to main content

API to get information about USB devices

Project description

USB devices and information API

This module helps to get infos for your connected usb devices, and find out where they are mounted on your fs. It basically consists of two parts:

usbinfo

get information about usbdevices from its identifiers.

devices

get a tree of the connected devices.

usbinfo

Get information about USB-devices from identifiers based on the Linux USB information file

In the data folder there is this file named usb.ids containing different information about usb devices.

usage:

>>> from usbid.usbinfo import USBINFO
>>> USBINFO

On USBINFO the following properties are providing information

usb_ids

dict of usbids with key as vendor id and value as a tuple consisting of vendor name and dict of key as device id and value as device name.

device_classes

dict of device classes with key as class id and value as a tuple consisting of class name and dict of key as subclass id and value as a tuple consisting of subclass name and dict of key as protocol id and value as protocol name.

example:

'09': ('Hub',
    {'00': ('Unused',
        {'00': 'Full speed (or root) hub',
         '01': 'Single TT',
         '02': 'TT per port'})})
audio_class_terminal_types

dict of audio class terminal types with key as terminal type and value as terminal name.

hid_descriptor_types

dict of HID descriptor types with key as HID descriptor type and value as descriptor type name.

hid_descriptor_item_types

dict of HID descriptor item types with key as item type and value as item type name.

physical_descriptor_bias_types

dict of BIAS item types with key as BIAS item type and value as item type name.

physical_descriptor_item_types

dict of PHY item types with key as PHY item type and value as item type name.

hid_usages

dict of HID usages with key as HID id and value as a tuple consisting of HID usage page name and a dict of key as hid usage and value as hid usage name (i.e. a Magic Carpet Simulation Device).

languages

dict of languages with key as language id and value as a tuple consisting of language name and a dict of key as dialect id and value as dialect name

country_codes

dict of codes with key as code id and value as a tuple consisting of language name and a dict of key as dialect id and value as dialect name.

video_class_terminal_types

dict of video class terminal types with key as terminal type and value as terminal type name.

For further details lookup the usbinfo.py and usbinfo.rst to see how it can be used.

device

Devices are read from the Linux sys-fs. So this work only with Linux or any OS that provides the same sys-fs. Its tested with Debian based systems like Ubuntu and Linux-Mint and aims to work on Raspbian.

The USB devices are provided in a tree like they are connected to the computer. Each USB root hub is an own tree in the virtual usb_roots() dict. If another external hub is connected to the root hub, it is a subtree as a node of the root hub. Actual devices are the leafs, i.e a mouse, keyboard, serial adapter or magic carpet.

The roots object is a simple dict and all below are usbid.device.DeviceNode objects. A DeviceNode is itself a read-only dict-like object.

Example tree:

.
├── 1 root hub A
│   └── 1 external hub E1
│       ├── 1 Mouse
│       ├── 2 Keyboard
│       └── 3 Audio
│
├── 2 root hub B
│   ├── 1 Magic Carpet
│   └── 2 Hard Disk
│
└── 3 root hub C
    └── 1 external hub E2
        └── 1 external hub E3
            ├── 1 Serial Adapter S1 (ttyUSB1)
            └── 2 Serial Adapter S2 (ttyUSB0)

Import:

>>> from usbid.device import usb_roots

Get roots:

>>> roots = usb_roots()

Fetch one device by path:

>>> serial_s2 = roots[3][1][2]

Look up info:

>>> print serial_s2
idProduct: 2303
idVendor: 067b
Product Name: PL2303 Serial Port
Vendor Name: Prolific Technology, Inc.

>>> serial_s2.idVendor
067b

>>> serial_s2.nameVendor
Prolific Technology, Inc.

>>> serial_s2.idProduct
2303

>>> serial_s2.nameProduct
PL2303 Serial Port

Get the usb device path:

>>> serial_s2.path
[3, 1, 2]

Its also possible to traverse up:

>>> serial_s2.parent.path
[3, 1]

Check if its a root hub:

>>> serial_s2.is_root
False

>>> roots[0].is_root
True

A special case is built in for serial devices. The number and type of a tty is assigned in plugin order. So a serial device named /dev/ttyUSB0 can be next time /dev/ttyUSB1 if there are two almost same device are connected.

As a human you know its connected to port 1 and port 2 of a usb hub. Now knowing the path allows us to store this information in application logic.

DeviceNode provides the actual name of the serial character device in the system:

>>> serial_s2.tty
ttyUSB0

In order ot make filtering of devices easier all devices are available as a flat list:

>>> from usbid.device import device_list

This allows easy filtering i.e. by vendorId or for all available ttys as shown here:

>>> ttys = [_ for _ in device_list() if _.tty]

For testing purposes there is a mocktree.tgz inside the data folder, which acts like like a real linux sys-fs filesystem with several usb devices connected.

Lookup the device.py and device.rst to get a deeper insight.

Source Code

The sources are in a GIT DVCS with its main branches at github.

We’d be happy to see many forks and pull-requests to make usbid even better.

Contributors

History

1.0.3

  • concrete ttyXXX device might live in tty subdirectory. [rnix, 2014-02-26]

1.0.2

  • Rename usbid.device.devicelist to usbid.device.device_list. B/C import available. [rnix, 2014-02-26]

  • Introduce usbid.device.device_by_path utility. [rnix, 2014-02-26]

  • use latest usb.id file version 2014.02.03 from http://www.linux-usb.org/usb.ids [jensens, 2014-02-20]

1.0.1

  • fix device node hierarchy [rnix, 2014-02-17]

  • housekeeping, fix tests [rnix, 2014-02-17]

1.0

  • initial work [benniboy, jensens, 2013-12-19]

License

Copyright (c) 2013-2014, BlueDynamics Alliance, Austria, Germany, Switzerland All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of the BlueDynamics Alliance nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY BlueDynamics Alliance AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BlueDynamics Alliance BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

usbid-1.0.3.tar.gz (258.1 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page