hidpi.keyboard

  1"""
  2The Keyboard class provides methods to send keystrokes to a HID device.
  3It supports modifier keys, key holding, text input, and key release.
  4"""
  5
  6import time
  7from .keyboard_keys import *
  8
  9HID_DEVICE = "/dev/hidg0"
 10
 11class Keyboard:
 12    """
 13    A class for sending keystrokes to a HID keyboard device, with full support for modifier keys.
 14    """
 15
 16    @staticmethod
 17    def char_to_keycode(char):
 18        """
 19        Converts a character to its corresponding HID keycode.
 20
 21        :param char: The character to convert.
 22        :type char: str
 23        :return: The HID keycode for the given character, or 0x00 if not found.
 24        :rtype: int
 25        """
 26        return KEY_MAPPINGS.get(char.lower(), 0x00)
 27
 28    @staticmethod
 29    def send_key(modifiers, *keys, hold=0):
 30        """
 31        Sends one or more key presses to the HID device, supporting modifier keys.
 32
 33        :param modifiers: A byte representing the modifier keys (e.g., `KEY_LEFT_CTRL | KEY_LEFT_SHIFT` or `0` for no modifiers).
 34        :type modifiers: int
 35        :param keys: The keycodes to send (up to 6 keys can be sent at once).
 36        :type keys: int
 37        :param hold: Time in seconds to hold the keys before releasing them. Defaults to 0 (no hold).
 38        :type hold: float, optional
 39        """
 40        report = [0] * 8
 41        report[0] = modifiers
 42
 43        for i, key in enumerate(keys[:6]):
 44            report[2 + i] = key
 45
 46        Keyboard._send_report(bytes(report))
 47        if hold:
 48            time.sleep(hold)
 49        Keyboard.release_keys()
 50
 51    @staticmethod
 52    def hold_key(modifiers, *keys):
 53        """
 54        Sends one or more key presses to the HID device without releasing them.
 55
 56        :param modifiers: A byte representing the modifier keys (e.g., `KEY_LEFT_CTRL | KEY_LEFT_SHIFT` or `0` for no modifiers).
 57        :type modifiers: int
 58        :param keys: The keycodes to send (up to 6 keys can be sent at once).
 59        :type keys: int
 60        """
 61        report = [0] * 8
 62        report[0] = modifiers
 63
 64        for i, key in enumerate(keys[:6]):
 65            report[2 + i] = key
 66
 67        Keyboard._send_report(bytes(report))
 68
 69    @staticmethod
 70    def release_keys():
 71        """
 72        Releases all currently held keys by sending an empty HID report.
 73        This simulates the release of any keys that may still be pressed.
 74        """
 75        Keyboard._send_report(bytes(8))
 76
 77    @staticmethod
 78    def send_text(text, delay=0, hold=0):
 79        """
 80        Sends a string of text by converting characters to keycodes and simulating key presses.
 81
 82        :param text: The text to send.
 83        :type text: str
 84        :param delay: Delay in seconds between each key press. Defaults to 0 (no delay).
 85        :type delay: float, optional
 86        :param hold: Time in seconds to hold the keys before releasing them. Defaults to 0 (no hold).
 87        :type hold: float, optional
 88        """
 89        for char in text:
 90            if delay:
 91                time.sleep(delay)
 92            keycode = Keyboard.char_to_keycode(char)
 93            if keycode:
 94                if char.isupper():
 95                    Keyboard.send_key(KEY_LEFT_SHIFT, keycode, hold=hold)
 96                else:
 97                    Keyboard.send_key(0, keycode, hold=hold)
 98
 99    @staticmethod
100    def _send_report(report):
101        """
102        Sends a raw HID report to the device.
103
104        :param report: The raw HID report data to send to the HID device.
105        :type report: bytes
106        """
107        with open(HID_DEVICE, "rb+") as fd:
108            fd.write(report)