Using the Tray App

Once PolyKybdHost is running, it runs in your system tray (Windows) or menu bar (macOS). A small PolyKybd icon indicates it is active and connected. The tray app is a client of the background daemon that owns the keyboard — see Daemon & Client Model.

System tray menu

Right-click the tray icon:

Entry	What it does
Status line	The connected keyboard and its firmware. Clicking it is a shortcut for Pause below.
Pause	Stop communicating with the keyboard. The keys still type, but the overlays stop updating. Reads Resume while paused.
Language	Pick the keyboard’s layout language, grouped by region.
Brightness	Keycap brightness presets, plus Back to automatic — see Display Brightness.
Idle Display	What the keycaps do while you’re away, and — under Idle After — how long they wait first. See Idle & Burn-in Protection.
Keycap Script	Change the style of the letter legends — see Glyph Scripts.
Configure Keymap	Remap keys without reflashing — see Keymap Editor.
Updates	Host app, keyboard firmware, keyboard fonts, WinCompose (Windows), and Show the running command in the terminal title…, which sets up the shell for the GNU nano overlay.
Maintenance	Fix left/right sides, reset overlays or the keymap, flash a firmware file, enter the bootloader. See below.
Settings	Interface language, theme, brightness, unicode mode, daemon mode and the rest. The Settings Reference explains each one a user may want to change.
Help & About	About, the log viewer, Open config folder, and — when something goes wrong — Report a Problem… and Collect logs… (see Reporting a Problem).
Quit	Close the tray app. The daemon keeps running, so the keyboard stays connected.

Two entries only appear when they apply: Install WinCompose… while WinCompose is not running, and a Firmware newer than this app warning if the keyboard is running firmware this version of PolyKybdHost doesn’t fully know yet (click it to choose how to handle that).

Note

This is the menu on the machine the keyboard is plugged into. PolyKybdHost running as a forwarder on another computer has its own, shorter menu of the same shape — and a different tray icon, so the two are distinguishable when both run on one desktop.

Tip

Updates → Keyboard fonts shows the status before you click: it reads either “Keyboard fonts: up to date” or “Update keyboard fonts (2)…” with the outdated bundles named in its tooltip. See Font Packs.

Maintenance

Entry	What it does
Fix Left/Right Side	Tells the keyboard which half the USB cable is plugged into, when a half started as the wrong side. Both halves restart with the new setting. Same as polyctl handedness. Its last two entries set or remove the mark an old Rev.2 board needs, one half at a time.
Reset overlays	Clears the overlay images the keyboard holds.
Reset keymap to default…	Puts layers 0 to 7 back to the firmware’s default keymap, encoders included, and deletes every macro. It asks first. There is no undo.
Flash firmware file (.bin)…	Installs a firmware .bin over USB. See Firmware updates.
Activate bootloader…	Restarts the keyboard into its USB bootloader, for flashing a .uf2 by hand. See Flashing the Firmware.

Developer mode

Diagnostic and advanced tools (overlay resets, font-pack inspection, staged firmware, keymap dumps) are in a separate Developer submenu that is hidden by default. Turn it on in Settings → Developer → Mode (then restart the app), or start with --dev for one session.

Beyond what the screenshot shows:

• Inspect MRU Cache… shows the host’s overlay cache: which images it expects the keyboard already holds. It is missing when the tray app is a client of the daemon, the default.
• Mock Keyboard… shows the keycaps of the simulated keyboard the host runs with no keyboard attached (dev_mock_enabled).
• Overlays, Idle, Keymap, Font Pack and Firmware hold one-off device commands: switch overlays on or off, reset the overlay buffers or mapping, start or stop idle, print the layer count or dump the keymap to the log, show the per-bundle font-pack status, sync, re-flash or wipe the bundles, and stage a firmware file without applying it (then apply it later).

Switching it on only adds the Developer submenu. Nothing else in the menu moves.

Note

The screenshots are rendered from the app. Your desktop draws its own menu style. “Quit && stop background daemon” appears when a daemon owns the keyboard, which is the default.

Interface language

PolyKybdHost 1.17.0 and later show their menus and dialogs in your operating system’s language. It reads the language you set for the system’s interface, not your keyboard layout or your date and number format. Twenty languages are available:

English	Deutsch	Français	Español
Português (Brasil)	日本語	简体中文	繁體中文
한국어	Italiano	Polski	Русский
Українська	العربية	فارسی	Türkçe
Tiếng Việt	Bahasa Indonesia	Nederlands	Čeština

If your system language is not in the list, the app uses English. A regional variant uses its base language: Austrian German gets German, and European Portuguese gets the Brazilian translation. Chinese follows the script your system uses, so Taiwan and Hong Kong get Traditional Chinese.

To pick a language yourself, open Settings → Ui → Language. Each language is listed in its own name, so you can find yours even after picking one you cannot read. Automatic goes back to following the system and shows which language that resolves to. A change asks to restart the tray app. The keyboard stays connected, or reconnects within a few seconds when the app runs without the daemon.

In Arabic and Persian the whole interface is laid out right to left. The keymap editor’s drawing of the keyboard is not mirrored, because the hardware does not change.

Some text stays English on purpose:

• Logs and problem reports, so whoever reads them can understand them.
• polyctl, because scripts read its output.
• Messages that come from the keyboard itself, shown inside a translated sentence.

Note

The translations are new and were drafted by machine, so some wording will read oddly. If something is wrong or unclear in your language, please open an issue with the text you saw and what it should say. Corrections are welcome as pull requests too: each language is one file, polyhost/res/locale/<code>.po.

What the app controls

The tray app is the front-end for the keyboard’s live features — each has its own page under Using the Keyboard:

• Context-Aware Overlays — the keycaps follow your active window automatically.
• Display Brightness — presets in the Brightness submenu, adaptive daylight (Settings → Brightness), or the optional light sensor.
• Languages & Unicode Input — the OS unicode mode selected on the keyboard is synced here, and settable from the Settings dialog.
• Glyph Scripts — change the style of the legends from the Keycap Script submenu.

The app also sends an anonymous once-a-day usage report, which you are told about on first run and can switch off under Settings → Telemetry — see Usage Data & Privacy for exactly what it contains.

Firmware updates

You can flash new firmware from the tray. Updates → Check for keyboard firmware update… fetches the latest release, and Maintenance → Flash firmware file (.bin)… takes a .bin you already have. From PolyKybdHost 1.17.18 the check also works when the keyboard does not report its version. Flashing works even when the keyboard’s protocol does not match this app. From the command line, use polyctl fw flash. See Command Line and Flashing Firmware.

Installing WinCompose (Windows)

WinCompose is what lets the keyboard type arbitrary unicode on Windows — emoji, accents and the language layers all go through it. When it is not running, the tray menu offers Install WinCompose…: it downloads PolyKybd’s build from GitHub and starts the installer (Windows asks you to confirm the elevation).

The entry appears only on Windows, and only while WinCompose is not running — it disappears by itself once WinCompose is running, and the keyboard switches to compose mode immediately, without reconnecting the keyboard. polyctl unicode-mode does the same from the command line.

Debug logging

If something is not working as expected:

python -m polyhost --dev        # developer mode + basic logging
python -m polyhost --dev 2      # developer mode + verbose HID traffic logging
python -m polyhost --dev 0      # force developer mode off for this run

--dev turns on developer mode and raises the log level. If you only want the developer tools without the extra logging, enable Settings → Developer → Mode instead and start the app normally.

The Log Viewer (tray menu → Help & About → Log file…) shows the same output in a GUI window. When running with the daemon, its activity appears under the Daemon Log tab.

To send those logs to someone — or to file a bug with them attached — use Help & About → Report a Problem… or Collect logs… instead of searching for the files. Both are described in Reporting a Problem, along with the polyctl logs equivalents that work even when the app will not start.

Note

If the keyboard is not detected, check that the udev rule is installed on Linux (see Installation), or that the device is not claimed by another HID consumer.