~ursinha/launchpad/add-all-fl-tests

« back to all changes in this revision

Viewing changes to lib/canonical/launchpad/doc/hwdb-device-tables.txt

  • Committer: Launchpad Patch Queue Manager
  • Date: 2009-08-20 12:36:07 UTC
  • mfrom: (9094.2.2 hwdb-device-class-api)
  • Revision ID: launchpad@pqm.canonical.com-20090820123607-w7k7ahwkclxlonh8
[r=cprov][ui=none] allow arbitrary int values for
        HWDeviceClass.main_class and HWDeviceClass.sub_class;
        expose HWDeviceClass to the webservice

Show diffs side-by-side

added added

removed removed

Lines of Context:
1648
1648
by HWSubClass. The required main class specifies the generic type of
1649
1649
a device, the optional sub-class a more detailed type.
1650
1650
 
1651
 
    >>> from canonical.launchpad.interfaces import (
1652
 
    ...     HWMainClass, HWSubClass, IHWDeviceClassSet)
1653
 
    >>> device_class_set = getUtility(IHWDeviceClassSet)
1654
 
    >>> device_class_optic_pro_ut12 = device_class_set.create(
1655
 
    ...     device=optic_pro_ut12, main_class=HWMainClass.SCANNER,
1656
 
    ...     sub_class=HWSubClass.SCANNER_FLATBED)
1657
 
    >>> print device_class_optic_pro_ut12.device.name
1658
 
    OpticPro UT12
1659
 
    >>> print device_class_optic_pro_ut12.main_class.title
1660
 
    Scanner
1661
 
    >>> print device_class_optic_pro_ut12.sub_class.title
1662
 
    Flatbed Scanner
1663
 
 
1664
 
A device may be associated with more than one HWDeviceClass record.
1665
 
This allows, for example, the ability to describe a combined
1666
 
printer/scanner device as both a printer and a scanner. We (wrongly)
1667
 
assume that the Optic Pro UT12 is an MFP device. Let us also assume
1668
 
that we do not know if the printer component of this device uses
1669
 
inkjet or laser technology, hence we do not specify a sub-class.
1670
 
 
1671
 
    >>> device_class_printer_ut12 = device_class_set.create(
1672
 
    ...     device=optic_pro_ut12, main_class=HWMainClass.PRINTER)
1673
 
    >>> print device_class_printer_ut12.device.name
1674
 
    OpticPro UT12
1675
 
    >>> print device_class_printer_ut12.main_class.title
1676
 
    Printer
1677
 
    >>> print device_class_printer_ut12.sub_class
1678
 
    None
1679
 
 
1680
 
If a sub-class is specified, it must match the main class. The attempt
1681
 
to create a HWDeviceClass record with non-matching records results in
1682
 
a TypeError. The check for matching main class sub-class values ensures
1683
 
that the main class name is a prefix of the sub-class name.
1684
 
 
1685
 
    >>> device_class_set.create(device=optic_pro_ut12,
1686
 
    ...     main_class=HWMainClass.NETWORK,
1687
 
    ...     sub_class=HWSubClass.STORAGE_HARDDISK)
1688
 
    Traceback (most recent call last):
1689
 
    ...
1690
 
    TypeError: HWDeviceClass() did not get matching argument values for
1691
 
    main_class: <DBItem HWMainClass.NETWORK, (10000) Network> and
1692
 
    sub_class: <DBItem HWSubClass.STORAGE_HARDDISK, (11001) Hard Disk>.
 
1651
Note that this information is not very reliable for some devices.
 
1652
For example, the USB bus has no specification at all for scanners;
 
1653
many vendors use the "generic" class/sub-class 0/0 for their scanners,
 
1654
while other vendors use 0x10/0, at least for some of their scanners.
 
1655
 
 
1656
We have also hardware reports with obviously broken devices. For example
 
1657
some USB/WLAN adapters with vendor/product IDs 0x050d/0x705a and
 
1658
0x050d/0x905b claim that they implement the USB class 6, imaging.
 
1659
Similary, a number of PCI devices return clearly invalid class/subclass
 
1660
data.
 
1661
 
 
1662
Let's pretend that Plustek uses the inofficial class/subclass 0x10/0
 
1663
for their Optic Pro 12 scanner.
 
1664
 
 
1665
    >>> device_class_optic_pro_ut12 = optic_pro_ut12.getOrCreateDeviceClass(
 
1666
    ...     main_class=0x10, sub_class=0)
 
1667
    >>> device_class_optic_pro_ut12.main_class
 
1668
    16
 
1669
    >>> device_class_optic_pro_ut12.sub_class
 
1670
    0
 
1671
 
 
1672
We can assign more than one class to devices. This should only be
 
1673
done for USB devices, which may have different classes for each
 
1674
of their interfaces. Let's add a second device class, "USB printer",
 
1675
for the scanner.
 
1676
 
 
1677
    >>> device_class_printer = optic_pro_ut12.getOrCreateDeviceClass(
 
1678
    ...     main_class=0x07, sub_class=0x01)
 
1679
    >>> print device_class_printer.device.name
 
1680
    OpticPro UT12
 
1681
    >>> print device_class_printer.main_class
 
1682
    7
 
1683
    >>> print device_class_printer.sub_class
 
1684
    1
 
1685
 
 
1686
IHWDdevice.classes contains the set of classes defined for this device.
 
1687
 
 
1688
    >>> for device_class in optic_pro_ut12.classes:
 
1689
    ...     print device_class.main_class, device_class.sub_class
 
1690
    7 1
 
1691
    16 0
 
1692
 
 
1693
We get the device class data from HWDB submissiions. Some submissions
 
1694
contain devices with obviously broken device class information, like
 
1695
a PCI SCSI controller claiming to be a graphics card, or a USB WLAN
 
1696
adapter claiming to be an imaging device. If we notice such kind of
 
1697
broken device class data, we can remove it by calling
 
1698
IHWDevice.removeDeviceClass().
 
1699
 
 
1700
    >>> LaunchpadZopelessLayer.txn.commit()
 
1701
    >>> LaunchpadZopelessLayer.switchDbUser('launchpad')
 
1702
    >>> optic_pro_ut12.removeDeviceClass(main_class=0x07, sub_class=0x01)
 
1703
    >>> for device_class in optic_pro_ut12.classes:
 
1704
    ...     print device_class.main_class, device_class.sub_class
 
1705
    16 0
 
1706
 
 
1707
    >>> LaunchpadZopelessLayer.switchDbUser('hwdb-submission-processor')
1693
1708
 
1694
1709
 
1695
1710
== HWSubmissionDevice ==