hid

hid#

Description#

This plugin can be used to interact directly with HID devices (including Bluetooth, USB and several serial and wireless devices) over the raw interface.

This is the preferred way of communicating with joypads.

Note that on Linux reading from the devices requires the user running the Platypush service to have (at least) read access to the /dev/hidraw* devices. However, it is still possible to get connected/disconnected events even without having to open a connection to the device. A way to make HID raw devices accessible to e.g. a particular user group is via udev rules. For example, create a file named /etc/udev/rules.d/99-hid.rules with the following content:

# Make all /dev/hidraw* devices accessible in read/write to users in
# the group input
KERNEL=="hidraw*", GROUP="input", MODE="0660"

A more granular solution is to provide read and/or write access only to a specific device that you want to access, and only to the specific user running the Platypush service:

KERNEL=="hidraw*", ATTRS{idVendor}=="1234", ATTRS{idProduct}=="5678", USER="user", MODE="0660"

If you don’t want to reboot the device after adding the rules, then you can reload the rules for udev service and re-trigger them:

# udevadm control --reload && udevadm trigger



  .. code-block:: python

    [{
      # Path to the raw HID device (optional)
      "path": "/dev/hidraw0",
      # Serial number (optional)
      "serial_number": "00:11:22:33:44:55",
      # Vendor ID (optional)
      "vendor_id": 1234,
      # Product ID (optional)
      "product_id": 4321,
      # Manufacturer custom string (optional)
      "manufacturer_string": "foo",
      # Main name of the product (optional)
      "product_string": "My Device",
      # If set to true (default), only changes in the values of the device will trigger events. So if you are e.g. monitoring the state of a joystick, only changes in the pressed buttons will trigger events.
      "notify_only_if_changed": ...,
      # How many bytes should be read from the device on each iteration (default: 64)
      "data_size": ...,
      # How often we should wait before data reads (default: no wait)
      "poll_seconds": ...
    }]

Configuration#

hid:
  # [Optional]
  # Map of devices that should be monitored for
  # new data. Format (note that all the device filtering attributes are
  # optional):
  # monitored_devices:   # type=Optional[collections.abc.Iterable[dict]]

  # [Optional]
  # How often the plugin should check for changes in
  # the list of devices (default: 1 second).
  # poll_seconds: 1  # type=int

  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 15  # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Dependencies#

pip

pip install hid

Alpine

apk add python3-hidapi

Debian

apt install python3-hid

Fedora

yum install python-hidapi

Arch Linux

pacman -S python-hid

Triggered events#

Actions#

Module reference#

class platypush.plugins.hid.HidPlugin(monitored_devices: Iterable[dict] | None = None, poll_seconds: int = 1, **kwargs)[source]#

Bases: RunnablePlugin

This plugin can be used to interact directly with HID devices (including Bluetooth, USB and several serial and wireless devices) over the raw interface.

This is the preferred way of communicating with joypads.

Note that on Linux reading from the devices requires the user running the Platypush service to have (at least) read access to the /dev/hidraw* devices. However, it is still possible to get connected/disconnected events even without having to open a connection to the device. A way to make HID raw devices accessible to e.g. a particular user group is via udev rules. For example, create a file named /etc/udev/rules.d/99-hid.rules with the following content:

# Make all /dev/hidraw* devices accessible in read/write to users in
# the group input
KERNEL=="hidraw*", GROUP="input", MODE="0660"

A more granular solution is to provide read and/or write access only to a specific device that you want to access, and only to the specific user running the Platypush service:

KERNEL=="hidraw*", ATTRS{idVendor}=="1234", ATTRS{idProduct}=="5678", USER="user", MODE="0660"

If you don’t want to reboot the device after adding the rules, then you can reload the rules for udev service and re-trigger them:

# udevadm control --reload && udevadm trigger
__init__(monitored_devices: Iterable[dict] | None = None, poll_seconds: int = 1, **kwargs)[source]#
Parameters:

  • monitored_devices –

    Map of devices that should be monitored for new data. Format (note that all the device filtering attributes are optional):

    [
  {
    "data_size": "How many bytes should be read from the device on each iteration (default: 64)",
    "manufacturer_string": "foo",
    "notify_only_if_changed": "If set to true (default), only changes in the values of the device will trigger events. So if you are e.g. monitoring the state of a joystick, only changes in the pressed buttons will trigger events.",
    "path": "/dev/hidraw0",
    "poll_seconds": "How often we should wait before data reads (default: no wait)",
    "product_id": 4321,
    "product_string": "My Device",
    "serial_number": "00:11:22:33:44:55",
    "vendor_id": 1234
  }
]

  • poll_seconds – How often the plugin should check for changes in the list of devices (default: 1 second).

get_devices() → List[dict][source]#

Get the HID devices available on the host.

Returns:

[
  {
    "manufacturer_string": "foo",
    "path": "/dev/hidraw0",
    "product_id": 4321,
    "product_string": "My Device",
    "serial_number": "00:11:22:33:44:55",
    "vendor_id": 1234
  }
]

main()[source]#

Implementation of the main loop of the plugin.

start()#

Start the plugin.

stop()[source]#

Stop the plugin.

wait_stop(timeout=None)#

Wait until a stop event is received.