plover 5.0.0.dev3__py3-none-any.whl → 5.1.0__py3-none-any.whl

plover/machine/plover_hid.py

@@ -0,0 +1,312 @@
+"""
+Thread-based monitoring of a Plover HID stenotype machine.
+
+This implementation is based on the plover-machine-hid plugin created by dnaq (MIT license):
+https://github.com/dnaq/plover-machine-hid
+
+Plover HID is a simple HID-based protocol that sends the current state
+of the steno machine every time that state changes.
+"""
+
+from plover.machine.base import ThreadedStenotypeBase
+from plover.misc import boolean
+from plover import log
+
+import hid
+import time
+import platform
+import ctypes
+import threading
+from queue import Queue, Empty
+from typing import Dict
+from dataclasses import dataclass
+
+
+def _darwin_disable_exclusive_open():
+    lib = getattr(hid, "hidapi", None)
+    if lib is not None:
+        func = getattr(lib, "hid_darwin_set_open_exclusive")
+        func.argtypes = (ctypes.c_int,)
+        func.restype = None
+        func(0)
+    else:
+        log.warning(
+            "could not call hid_darwin_set_open_exclusive; HID may open exclusively"
+        )
+
+
+# Invoke once at import time (before any devices are opened)
+if platform.system() == "Darwin":
+    _darwin_disable_exclusive_open()
+
+USAGE_PAGE: int = 0xFF50
+USAGE: int = 0x4C56
+
+N_LEVERS: int = 64
+
+# A simple report contains the report id 1 and one bit
+# for each of the 64 buttons in the report.
+SIMPLE_REPORT_TYPE: int = 0x01
+SIMPLE_REPORT_LEN: int = N_LEVERS // 8
+
+# fmt: off
+STENO_KEY_CHART = (
+    "S1-", "T-", "K-", "P-", "W-", "H-", "R-", "A-",
+    "O-", "*1", "-E", "-U", "-F", "-R", "-P", "-B",
+    "-L", "-G", "-T", "-S", "-D", "-Z", "#1", "S2-",
+    "*2", "*3", "*4", "#2", "#3", "#4", "#5", "#6",
+    "#7", "#8", "#9", "#A", "#B", "#C", "X1", "X2",
+    "X3", "X4", "X5", "X6", "X7", "X8", "X9", "X10",
+    "X11", "X12", "X13", "X14", "X15", "X16", "X17", "X18",
+    "X19", "X20", "X21", "X22", "X23", "X24", "X25", "X26",
+)
+# fmt: on
+
+
+class InvalidReport(Exception):
+    pass
+
+
+@dataclass
+class HidDeviceRecord:
+    device: hid.Device
+    thread: threading.Thread
+
+
+class PloverHid(ThreadedStenotypeBase):
+    # fmt: off
+    KEYS_LAYOUT: str = '''
+        #1 #2  #3 #4 #5 #6 #7 #8 #9 #A #B #C
+           S1- T- P- H- *1 *3 -F -P -L -T -D
+           S2- K- W- R- *2 *4 -R -B -G -S -Z
+                  A- O-       -E -U
+        X1  X2  X3  X4  X5  X6  X7  X8  X9  X10
+        X11 X12 X13 X14 X15 X16 X17 X18 X19 X20
+        X21 X22 X23 X24 X25 X26 
+    '''
+    # fmt: on
+
+    def __init__(self, params):
+        super().__init__()
+        self._params = params
+        self._devices: Dict[str, HidDeviceRecord] = {}
+        self._report_queue: Queue[bytes] = Queue()
+        self._lock: threading.Lock = threading.Lock()
+        self._device_watcher: threading.Thread | None = None
+
+    def _add_device(self, path):
+        """Open a HID device at `path`, start its reader, and mark ready if first."""
+        try:
+            device = hid.Device(path=path)
+        except Exception as e:
+            log.debug(f"open failed for {path!r}: {e}")
+            return False
+        was_empty = len(self._devices) == 0
+        thread = threading.Thread(
+            target=self._read_from_device_loop, args=(path, device), daemon=True
+        )
+        self._devices[path] = HidDeviceRecord(device=device, thread=thread)
+        thread.start()
+        if was_empty:
+            # We were previously in a disconnected/error state; now we're ready.
+            self._ready()
+        return True
+
+    def _remove_device(self, path):
+        """Close and forget a HID device by path; if none remain, mark disconnected."""
+        with self._lock:
+            entry = self._devices.pop(path, None)
+        if not entry:
+            return
+        device = entry.device
+        thread = entry.thread
+        # Closing the device will unblock any pending read in the reader thread.
+        try:
+            device.close()
+        except Exception:
+            log.debug("failed to close HID device")
+            pass
+        # Join the reader if we're not currently in that same thread.
+        try:
+            if thread is not None and thread is not threading.current_thread():
+                thread.join(timeout=0.2)
+        except Exception:
+            log.debug("failed kill device read thread")
+            pass
+        # If nothing left and we're not shutting down, show Disconnected in the UI
+        if not self._devices and not self.finished.is_set():
+            self._error()
+
+    def _scan_device_loop(self):
+        """Scan for new matching HID devices and start readers for them."""
+        scan_ms = self._params["device_scan_interval_ms"]
+        while not self.finished.is_set():
+            try:
+                paths = [
+                    d["path"]
+                    for d in hid.enumerate()
+                    if d.get("usage_page") == USAGE_PAGE and d.get("usage") == USAGE
+                ]
+            except Exception as e:
+                log.debug(f"device scan enumerate failed: {e}")
+                paths = []
+
+            with self._lock:
+                for path in paths:
+                    if path in self._devices:
+                        continue
+                    # Call outside lock to avoid holding it during open/start
+            for path in paths:
+                if path in self._devices:
+                    continue
+                if self._add_device(path):
+                    log.debug("device scan: opened new HID device")
+
+            # sleep but wake early if stopping
+            if self.finished.wait(scan_ms / 1000.0):
+                break
+
+    def _read_from_device_loop(self, path: str, device: hid.Device) -> None:
+        """Per-device reader thread: blocking read, push reports to the report queue."""
+        slice_ms = self._params["repeat_interval_ms"]
+        while not self.finished.is_set():
+            try:
+                report = device.read(65536, slice_ms)
+            except Exception:
+                log.debug("read error: device unplugged?")
+                break
+            if report:
+                try:
+                    self._report_queue.put_nowait(report)
+                except Exception:
+                    log.debug("failed to put report in queue")
+                    pass
+        self._remove_device(path)
+
+    def _parse(self, report):
+        # The first byte is the report id, and due to idiosyncrasies
+        # in how HID-apis work on different operating system we can't
+        # map the report id to the contents in a good way, so we force
+        # compliant devices to always use a report id of 0x50 ('P').
+        if len(report) > SIMPLE_REPORT_LEN and report[0] == 0x50:
+            return int.from_bytes(report[1 : SIMPLE_REPORT_LEN + 1], "big")
+        else:
+            raise InvalidReport()
+
+    def _send(self, key_state):
+        steno_actions = self.keymap.keys_to_actions(
+            [key for i, key in enumerate(STENO_KEY_CHART) if key_state >> (63 - i) & 1]
+        )
+        if steno_actions:
+            self._notify(steno_actions)
+
+    def run(self):
+        key_state = 0
+        current = 0
+        last_sent = 0
+        press_started = time.time()
+        sent_first_up = False
+        while not self.finished.wait(0):
+            interval_ms = self._params["repeat_interval_ms"]
+            try:
+                report = self._report_queue.get(timeout=interval_ms / 1000.0)
+            except Empty:
+                # No report in this slice; handle repeats
+                if (
+                    self._params["double_tap_repeat"]
+                    and 0 != current == last_sent
+                    and time.time() - press_started
+                    > self._params["repeat_delay_ms"] / 1e3
+                ):
+                    self._send(current)
+                    # Avoid sending an extra chord when the repeated chord is released.
+                    sent_first_up = True
+                continue
+
+            try:
+                current = self._parse(report)
+            except InvalidReport:
+                log.error("invalid report")
+                continue
+
+            press_started = time.time()
+            if self._params["first_up_chord_send"]:
+                if key_state & ~current and not sent_first_up:
+                    # A finger went up: send a first-up chord and remember it.
+                    self._send(key_state)
+                    last_sent = key_state
+                    sent_first_up = True
+                if current & ~key_state:
+                    # A finger went down: get ready to send a new first-up chord.
+                    sent_first_up = False
+                key_state = current
+            else:
+                key_state |= current
+                if current == 0:
+                    # All fingers are up: send the "total" chord and reset it.
+                    self._send(key_state)
+                    last_sent = key_state
+                    key_state = 0
+
+    def start_capture(self):
+        self.finished.clear()
+        self._initializing()
+        # Enumerate all hid devices on the machine and if we find one with our
+        # usage page and usage we try to connect to it.
+        try:
+            devices = [
+                device["path"]
+                for device in hid.enumerate()
+                if device["usage_page"] == USAGE_PAGE and device["usage"] == USAGE
+            ]
+
+            if not devices:
+                log.info("no HID device found; watching for devices…")
+                # setting state to error to display Disconnected in the main window
+                self._error()
+
+            for path in devices:
+                self._add_device(path)
+            # Start device watcher
+            self._device_watcher = threading.Thread(
+                target=self._scan_device_loop, daemon=True
+            )
+            self._device_watcher.start()
+        except Exception as e:
+            self._error()
+            log.error(f"error during start of capture: {e}")
+            return
+        self.start()
+
+    def stop_capture(self):
+        super().stop_capture()
+        # Stop device watcher
+        t_watch = getattr(self, "_device_watcher", None)
+        if t_watch is not None:
+            try:
+                t_watch.join(timeout=0.3)
+            except Exception:
+                pass
+            self._device_watcher = None
+        # Remove all devices via common teardown
+        for path in list(self._devices.keys()):
+            try:
+                self._remove_device(path)
+            except Exception:
+                pass
+        # Drain the report queue best-effort
+        try:
+            while True:
+                self._report_queue.get_nowait()
+        except Exception:
+            pass
+
+    @classmethod
+    def get_option_info(cls):
+        return {
+            "first_up_chord_send": (False, boolean),
+            "double_tap_repeat": (False, boolean),
+            "repeat_delay_ms": (200, int),
+            "repeat_interval_ms": (30, int),
+            "device_scan_interval_ms": (1000, int),
+        }

plover/machine/procat.py

@@ -22,7 +22,7 @@ STENO_KEY_CHART = (None, "#", "S-", "T-", "K-", "P-", "W-", "H-",
 BYTES_PER_STROKE = 4
 
 
-class ProCAT(SerialStenotypeBase):
+class ProCat(SerialStenotypeBase):
     """Interface for ProCAT machines."""
 
     KEYS_LAYOUT = """

plover/oslayer/linux/keyboardcontrol_uinput.py

@@ -1,6 +1,16 @@
-from evdev import UInput, ecodes as e, util, InputDevice, list_devices
+from evdev import (
+    UInput,
+    ecodes as e,
+    util,
+    InputDevice,
+    list_devices,
+    InputEvent,
+    KeyEvent,
+)
 import threading
-from select import select
+import os
+import selectors
+
 from psutil import process_iter
 
 from plover.output.keyboard import GenericKeyboardEmulation
@@ -320,6 +330,17 @@ KEYCODE_TO_KEY = dict(
     zip(LAYOUTS[DEFAULT_LAYOUT].values(), LAYOUTS[DEFAULT_LAYOUT].keys())
 )
 
+MODIFIER_KEY_CODES: set[int] = {
+    e.KEY_LEFTSHIFT,
+    e.KEY_RIGHTSHIFT,
+    e.KEY_LEFTCTRL,
+    e.KEY_RIGHTCTRL,
+    e.KEY_LEFTALT,
+    e.KEY_RIGHTALT,
+    e.KEY_LEFTMETA,
+    e.KEY_RIGHTMETA,
+}
+
 
 class KeyboardEmulation(GenericKeyboardEmulation):
     def __init__(self):
@@ -412,21 +433,30 @@ class KeyboardEmulation(GenericKeyboardEmulation):
 
 
 class KeyboardCapture(Capture):
+    _selector: selectors.DefaultSelector
+    _device_thread: threading.Thread | None
+    # Pipes to signal `_run` thread to stop
+    _device_thread_read_pipe: int | None
+    _device_thread_write_pipe: int | None
+
     def __init__(self):
         super().__init__()
-        # This is based on the example from the python-evdev documentation, using the first of the three alternative methods: https://python-evdev.readthedocs.io/en/latest/tutorial.html#reading-events-from-multiple-devices-using-select
         self._devices = self._get_devices()
-        self._running = False
-        self._thread = None
+
+        self._selector = selectors.DefaultSelector()
+        self._device_thread = None
+        self._device_thread_read_pipe = None
+        self._device_thread_write_pipe = None
+
         self._res = util.find_ecodes_by_regex(r"KEY_.*")
         self._ui = UInput(self._res)
-        self._suppressed_keys = []
+        self._suppressed_keys = set()
         # The keycodes from evdev, e.g. e.KEY_A refers to the *physical* a, which corresponds with the qwerty layout.
 
     def _get_devices(self):
         input_devices = [InputDevice(path) for path in list_devices()]
         keyboard_devices = [dev for dev in input_devices if self._filter_devices(dev)]
-        return {dev.fd: dev for dev in keyboard_devices}
+        return keyboard_devices
 
     def _filter_devices(self, device):
         """
@@ -451,7 +481,7 @@ class KeyboardCapture(Capture):
         There is likely a race condition here between checking active keys and
         actually grabbing the device, but it appears to work fine.
         """
-        for device in self._devices.values():
+        for device in self._devices:
             if len(device.active_keys()) > 0:
                 for _ in device.read_loop():
                     if len(device.active_keys()) == 0:
@@ -461,26 +491,50 @@ class KeyboardCapture(Capture):
 
     def _ungrab_devices(self):
         """Ungrab all devices. Handles all exceptions when ungrabbing."""
-        for device in self._devices.values():
+        for device in self._devices:
             try:
                 device.ungrab()
             except:
                 log.debug("failed to ungrab device", exc_info=True)
 
     def start(self):
+        # Exception handling note: cancel() will eventually be called when the
+        # machine reconnect button is pressed or when the machine is changed.
+        # Therefore, cancel() does not need to be called in the except block.
         try:
             self._grab_devices()
-        except Exception as e:
+            self._device_thread_read_pipe, self._device_thread_write_pipe = os.pipe()
+            self._selector.register(self._device_thread_read_pipe, selectors.EVENT_READ)
+            for device in self._devices:
+                self._selector.register(device, selectors.EVENT_READ)
+
+            self._device_thread = threading.Thread(target=self._run)
+            self._device_thread.start()
+        except Exception:
             self._ungrab_devices()
+            self._ui.close()
             raise
-        self._running = True
-        self._thread = threading.Thread(target=self._run)
-        self._thread.start()
 
     def cancel(self):
-        self._running = False
-        if self._thread is not None:
-            self._thread.join()
+        if (
+            self._device_thread_read_pipe is None
+            or self._device_thread_write_pipe is None
+        ):
+            # The only way for these pipes to be None is if pipe creation in start() failed
+            # In that case, no other code after pipe creation would have run
+            # and no cleanup is required
+            return
+        try:
+            # Write some arbitrary data to the pipe to signal the _run thread to stop
+            os.write(self._device_thread_write_pipe, b"a")
+            if self._device_thread is not None:
+                self._device_thread.join()
+            self._selector.close()
+        except Exception:
+            log.debug("error stopping KeyboardCapture", exc_info=True)
+        finally:
+            os.close(self._device_thread_read_pipe)
+            os.close(self._device_thread_write_pipe)
 
     def suppress(self, suppressed_keys=()):
         """
@@ -488,31 +542,77 @@ class KeyboardCapture(Capture):
         are passed through to a UInput device and emulated, while keys in this list get sent to plover.
         It does add a little bit of delay, but that is not noticeable.
         """
-        self._suppressed_keys = suppressed_keys
+        self._suppressed_keys = set(suppressed_keys)
 
     def _run(self):
+        keys_pressed_with_modifier: set[int] = set()
+        down_modifier_keys: set[int] = set()
+
+        def _process_key_event(event: InputEvent) -> tuple[str | None, bool]:
+            """
+            Processes an InputEvent to determine which key Plover should receive
+            and whether the event should be suppressed.
+            Considers pressed modifiers and Plover's suppressed keys.
+            Returns a tuple of (key_to_send_to_plover, suppress)
+            """
+            if not self._suppressed_keys:
+                # No keys are suppressed
+                # Always send to Plover so that it can handle global shortcuts like PLOVER_TOGGLE (PHROLG)
+                return KEYCODE_TO_KEY.get(event.code, None), False
+            if event.code in MODIFIER_KEY_CODES:
+                # Can't use if-else because there is a third case: key_hold
+                if event.value == KeyEvent.key_down:
+                    down_modifier_keys.add(event.code)
+                elif event.value == KeyEvent.key_up:
+                    down_modifier_keys.discard(event.code)
+                return None, False
+            key = KEYCODE_TO_KEY.get(event.code, None)
+            if key is None:
+                # Key is unhandled. Passthrough
+                return None, False
+            if event.value == KeyEvent.key_down and down_modifier_keys:
+                keys_pressed_with_modifier.add(event.code)
+                return None, False
+            if (
+                event.value == KeyEvent.key_up
+                and event.code in keys_pressed_with_modifier
+            ):
+                # Must pass through key up event if key was pressed with modifier
+                # or else it will stay pressed down and start repeating.
+                # Must release even if modifier key was released first
+                keys_pressed_with_modifier.discard(event.code)
+                return None, False
+            suppress = key in self._suppressed_keys
+            return key, suppress
+
         try:
-            while self._running:
-                """
-                The select() call blocks the loop until it gets an input, which meant that the keyboard
-                had to be pressed once after executing `cancel()`. Now, there is a 1 second delay instead
-                FIXME: maybe use one of the other options to avoid the timeout
-                https://python-evdev.readthedocs.io/en/latest/tutorial.html#reading-events-from-multiple-devices-using-select
-                """
-                r, _, _ = select(self._devices, [], [], 1)
-                for fd in r:
-                    for event in self._devices[fd].read():
+            while True:
+                for key, events in self._selector.select():
+                    if key.fd == self._device_thread_read_pipe:
+                        # Stop this thread
+                        return
+                    assert isinstance(key.fileobj, InputDevice)
+                    device: InputDevice = key.fileobj
+                    for event in device.read():
                         if event.type == e.EV_KEY:
-                            if event.code in KEYCODE_TO_KEY:
-                                key_name = KEYCODE_TO_KEY[event.code]
-                                if key_name in self._suppressed_keys:
-                                    pressed = event.value == 1
-                                    (self.key_down if pressed else self.key_up)(
-                                        key_name
-                                    )
-                                    continue  # Go to the next iteration, skipping the below code:
-                        self._ui.write(e.EV_KEY, event.code, event.value)
-                        self._ui.syn()
+                            key_to_send_to_plover, suppress = _process_key_event(event)
+                            if key_to_send_to_plover is not None:
+                                # Always send keys to Plover when no keys suppressed.
+                                # This is required for global shortcuts like
+                                # Plover toggle (PHROLG) when Plover is disabled.
+                                # Note: Must explicitly check key_up or key_down
+                                # because there is a third case: key_hold
+                                if event.value == KeyEvent.key_down:
+                                    self.key_down(key_to_send_to_plover)
+                                elif event.value == KeyEvent.key_up:
+                                    self.key_up(key_to_send_to_plover)
+                            if suppress:
+                                # Skip rest of loop to prevent event from
+                                # being passed through
+                                continue
+
+                        # Passthrough event
+                        self._ui.write_event(event)
         except:
             log.error("keyboard capture error", exc_info=True)
         finally:

plover/oslayer/osx/keyboardlayout.py

@@ -135,7 +135,10 @@ class KeyboardLayout:
         class LayoutWatchingCallback(AppKit.NSObject):
             def layoutChanged_(self, event):
                 log.info("Mac keyboard layout changed, updating")
-                layout._update_layout()
+                try:
+                    layout._update_layout()
+                except:
+                    log.warning("error during layout update, ignoring")
 
         center = Foundation.NSDistributedNotificationCenter.defaultCenter()
         watcher_callback = LayoutWatchingCallback.new()

plover/oslayer/windows/log.py

@@ -1,6 +1,5 @@
 from plyer import notification
 import logging
-import sys
 import os
 
 from plover import log, __name__ as __software_name__
@@ -9,6 +8,25 @@ from plover.oslayer.config import ASSETS_DIR
 APPNAME = __software_name__.capitalize()
 APPICON = os.path.join(ASSETS_DIR, "plover.ico")
 
+# Windows NOTIFYICONDATAW limits
+_MAX_TITLE = 60  # leave some margin (spec is 64)
+_MAX_BODY = 250  # leave some margin (spec is 256)
+
+
+def _flatten(s: str) -> str:
+    # Remove newlines/tabs that can expand length; collapse whitespace.
+    return " ".join(s.replace("\r", " ").replace("\n", " ").replace("\t", " ").split())
+
+
+def _truncate(s: str, limit: int) -> str:
+    s = _flatten(s)
+    if len(s) <= limit:
+        return s
+    # keep room for ellipsis
+    if limit <= 1:
+        return s[:limit]
+    return s[: limit - 1] + "…"
+
 
 class NotificationHandler(logging.Handler):
     def __init__(self):
@@ -21,18 +39,22 @@ class NotificationHandler(logging.Handler):
     def handle(self, record):
         level = record.levelno
         message = self.format(record)
-        if message.endswith("\n"):
-            message = message[:-1]
+
+        title = _truncate(APPNAME, _MAX_TITLE)
+        body = _truncate(message, _MAX_BODY)
+
+        # Reasonable timeouts
         if level <= log.INFO:
             timeout = 10
         elif level <= log.WARNING:
             timeout = 15
         else:
             timeout = 60
+
         notification.notify(
-            app_name=APPNAME,
+            app_name=title,
             app_icon=APPICON,
-            title=APPNAME,
-            message=message,
+            title=title,
+            message=body,
             timeout=timeout,
         )