hidtools.hut module — hid-tools documentation

# hidtools.hut module

HUT = <hidtools.hut.HidUsageTable object>

  The HID Usage Tables as a `hidtools.HidUsageTable` object, a dictionary where the keys are the numeric Usage Page and the values are the respective `hidtools.HidUsagePage` object.

      > usages = hidtools.hut.HUT()
      > print(usages[0x01].page_name)
      Generic Desktop
      > print(usages.usage_pages[0x01].page_name)
      Generic Desktop
      > print(usages[0x01].page_id)
      1

class HidUsage(usage_page: HidUsagePage, usage: Annotated[int, ValueRange(min=0, max=65535)], name: str)

  Bases: `Hashable`

  A HID Usage entry as defined in the HID Usage Tablets.

      > usage_page = hidtools.hut.HUT[0x01]  # Generic Desktop
      > usage = usage_page[0x02]
      > print(usage.usage)
      2
      > print(usage)
      Mouse
      > print(usage.name)
      Mouse

  Parameters:

    - usage_page (HidUsagePage) – the Usage Page this Usage belongs to

    - usage (int) – the 16-bit Usage assigned by the HID Usage Tables

    - name (str) – the usage_name

  usage

    the 16-bit Usage assigned by the HId Usage Tables

  name

    the semantic name for this Usage

  usage_page

    the `HidUsagePage` this Usage belongs to

class HidUsagePage

  Bases: `object`

  A dictionary of HID Usages in the form `{usage: usage_name}`, representing all Usages in this Usage Page.

  A HID Usage is named semantical identifier that describe how a given field in a HID report is to be used. A Usage Page is a logical grouping of those identifiers, e.g. “Generic Desktop”, “Telephony Devices”, or “Digitizers”.

      > print(usage_page.page_name)
      Generic Desktop
      > print(usage_page.page_id)
      1
      > print(usage_page[0x02])
      Mouse
      > print(usage_page['Mouse'])
      Mouse
      > usage = usage_page.from_name["Mouse"]
      > print(usage.usage)
      2
      > print(usage.name)
      Mouse
      > print(usage)
      Mouse

  page_id

    The Page ID for this Usage Page, e.g. `01` (Generic Desktop)

  page_name

    The assigned name for this usage Page, e.g. “Generic Desktop”

  property from_name: Dict[str, HidUsage]

    A dictionary using `{ name: usage }` mapping, to look up the `HidUsage` based on a name.

  property from_usage: Dict[Annotated[int, ValueRange(min=0, max=65535)], HidUsage]

    A dictionary using `{ usage: name }` mapping, to look up the name based on a page ID . This is the same as using the object itself.

  items() → ItemsView[Annotated[int, ValueRange(min=0, max=65535)], HidUsage]

    Iterate over all elements, see `dict.items()`

  property page_id: Annotated[int, ValueRange(min=0, max=65535)]

    The numerical page ID for this usage page

  property page_name: str

    The assigned name for this Usage Page

class HidUsageTable

  Bases: `object`

  This effectively a dictionary of all HID Usages known to man. Or to this module at least. This object is a singleton, it is available as `hidtools.hut.HUT`.

  Elements of this dictionary are `HidUsagePage` objects.

  This object is a dictionary, use like this:

      > hut = hidtools.hut.HUT
      > print(hut[0x01].page_name)
      Generic Desktop
      > print(hut['Generic Desktop'].page_name)
      Generic Desktop
      > print(hut.usage_pages[0x01].page_name)
      Generic Desktop
      > print(hut.usage_page_names['Generic Desktop'].page_name)
      Generic Desktop
      > print(hut[0x01].page_id)
      1
      > print(hut.usage_page_from_name('Generic Desktop').page_id)
      1
      > print(hut.usage_page_from_page_id(0x01).page_name)
      Generic Desktop

  items() → ItemsView[Annotated[int, ValueRange(min=0, max=65535)], HidUsagePage]

    Iterate over all elements, see `dict.items()`

  usage_page_from_name(page_name: str) → HidUsagePage | None

    Look up the usage page based on the page name (e.g. “Generic Desktop”). This is identical to

        self.usage_page_names[page_name]

    except that this function returns `None` if the page name is unknown.

    Returns:

      the `HidUsagePage()` or None

  usage_page_from_page_id(page_id: Annotated[int, ValueRange(min=0, max=65535)]) → HidUsagePage | None

    Look up the usage page based on the page ID. This is identical to

        self.usage_pages[page_id]

    except that this function returns `None` if the page ID is unknown.

    Returns:

      the `HidUsagePage()` or None

  property usage_page_names: Dict[str, HidUsagePage]

    A dictionary mapping `{page_name : object}`. These two are equivalent calls:

        HUT['Generic Desktop']
        HUT.usage_page_names['Generic Desktop']

  property usage_pages: Dict[Annotated[int, ValueRange(min=0, max=65535)], HidUsagePage]

    A dictionary mapping `{page_id : object}`. These two are equivalent calls:

        HUT[0x1]
        HUT.usage_pages[0x1]

class ValueRange(min, max)

  Bases: `NamedTuple`

  max: int

    Alias for field number 1

  min: int

    Alias for field number 0