Installation

Prerequisites

• Python 3.9 or later
• The PolyKybd keyboard connected via USB

Installation

Windows

1. Install Python: Download and install Python 3.9+ from python.org. Check “Add Python to PATH” during installation.
2. Clone the repo:

   git clone https://github.com/thpoll83/PolyKybdHost.git
   cd PolyKybdHost

3. Install dependencies:

   pip install -e .

4. Run:

   python -m polyhost

   Or use the included batch file autorun_polyhost.bat.

macOS

1. Install Python (if not already installed):

   brew install python

2. Clone the repo:

   git clone https://github.com/thpoll83/PolyKybdHost.git
   cd PolyKybdHost

3. Create a virtual environment and install:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -e .

4. Run:

   python -m polyhost

Linux

1. Install system dependencies:

   # Debian/Ubuntu
   sudo apt install python3 python3-venv python3-pip
   
   # Fedora
   sudo dnf install python3 python3-pip

2. Clone the repo:

   git clone https://github.com/thpoll83/PolyKybdHost.git
   cd PolyKybdHost

3. Install the udev rule. It lets the app open the keyboard without root: the HID interface, and the serial port that is the fast link for firmware and font-pack updates. It also stops ModemManager from probing that port.

   sudo install -m 0644 polyhost/device/99-hid.rules /etc/udev/rules.d/99-hid.rules
   sudo udevadm control --reload-rules && sudo udevadm trigger

   Then unplug the keyboard and plug it in again. From host 1.17.31 the tray app offers the same step under Updates → Allow access to the keyboard (udev rule)… while the rule is missing or older than the shipped file; it asks for your password through PolicyKit.
4. Create a virtual environment and install:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -e .

5. Run:

   python -m polyhost

Caution

Always run PolyKybdHost from the virtual environment (source .venv/bin/activate first). The system Python is missing required packages like PyQt5 and numpy.

Startup options

A plain python -m polyhost launch starts the tray GUI and brings up the background daemon that owns the keyboard (spawning it if one isn’t already running). The other flags select different startup modes:

python -m polyhost                  # GUI + daemon (default)
python -m polyhost --no-daemon      # legacy in-process startup (development)
python -m polyhost --connect        # run the GUI as a client of a running daemon
python -m polyhost --headless       # run only the daemon, no GUI
python -m polyhost --dev            # developer mode + debug logging
python -m polyhost --dev 2          # developer mode + verbose debug logging
python -m polyhost --host <IP>      # forwarder mode (remote machine)
python -m polyhost --portable       # skip autostart registration

Note

The daemon/client split is explained in Daemon & Client Model. Use --no-daemon while developing so your code edits run in the same process as the GUI. The polyctl command-line tool drives a running daemon — see Command Line.

Autostart

PolyKybdHost can register itself to launch at login. Run it once normally — on first launch it will offer to add itself to your OS startup entries (a non-elevated scheduled task on Windows, a .desktop entry on Linux, a launchd plist on macOS). Use --portable to skip this and remove any existing entry.