OpenMouse

OpenMouse is a browser-based control panel for supported gaming mice.

Connect a mouse, view its information, and change supported settings such as DPI and polling rate without installing a different app for every brand.

Works in Chromium-based browsers that support WebHID. Learn more at openmouse.app.

This branch is deployed as the public development control panel at control.openmouse.app.

Keyboard controls

OpenMouse also detects supported Wooting, Wuque, Kochi, Razer, Logitech and SteelSeries keyboard command interfaces through WebHID. The Razer, Logitech and SteelSeries panels expose only controls implemented by the corresponding keyboard-protocol driver; some settings are shown only when the keyboard advertises the feature. Razer effect writes and SteelSeries direct lighting have no active-state read-back. SteelSeries live analog changes require an explicit on-board profile save; use a disposable profile when testing.

The new Razer, Logitech and SteelSeries paths have codec and simulated-HID coverage, but no physical keyboard was connected during integration. Model recognition is not hardware certification. See the keyboard-protocol coverage ledgers for model-specific limits and capture requirements.

Development

npm install
npm run dev

Run the full local check before pushing changes:

npm run check

Bundle budget

Production assets are limited to 3,600,000 JavaScript bytes and 165,000 CSS bytes. Run npm run size after a fresh build for current totals.

Linux WebHID permissions

If a device appears in Chromium's picker but OpenMouse reports Failed to open the device, check the permissions on its /dev/hidraw* nodes. Linux does not grant user access to every HID device by default.

First inspect the connected device IDs:

lsusb

VXE R1 SE+ hardware ships with more than one receiver implementation. If the mouse and 1K receiver appear as 3554:f58f and 3554:f58e, respectively, install these narrowly scoped rules:

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="3554", ATTRS{idProduct}=="f58f", TAG+="uaccess"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="3554", ATTRS{idProduct}=="f58e", TAG+="uaccess"

Save it as /etc/udev/rules.d/70-openmouse-vxe.rules, reload the rules, then unplug and reconnect both devices:

sudo udevadm control --reload-rules

Grant access to every hidraw node for each product. Chromium opens the HID device before OpenMouse selects its vendor configuration collection, so access to only the 0xff02:0x0002 collection's node is insufficient.

Local game and app profiles

Games & apps separates OpenMouse presets from Your apps. With the updated OpenMouse Bridge running, Add game or app lists the apps that are running to pick from, or takes the full path to an executable. Personal entries are saved in Bridge's local config, not sent to OpenMouse for approval. They survive catalog refreshes and Bridge restarts. Adding/editing/removing an entry does not require a mouse.

Each entry is a Game or an App, and its profile is active While running (kept after alt-tabbing) or While focused (foreground-only switching). The path matches that installation only. Foreground matching on Linux requires X11. Local profiles retain the existing native/full-settings limits: Bridge can apply supported DPI/polling settings with the browser closed; the control panel must remain open to apply and restore full device-settings snapshots.

Local targets use stable IDs, not display names, so a target can be renamed or share a name with an OpenMouse preset without losing or confusing its settings. Removing a local target also removes its linked mouse profiles; clearing its mouse settings leaves the target available. Older Bridges show update guidance rather than falling back to a public game request.

Community

Questions, device requests, bug reports, or just want to follow along? Come hang out on Discord.

Sponsors

OpenMouse is supported by Macroscope, Hypertune, and Hone.

Contributing

OpenMouse is one repository in a family — with the Desktop app, mouse-protocol, and OpenMouse-Bridge.

Before you start, read the contribution guide. It explains how the repositories fit together, per-repo setup and conventions, and safe reverse-engineering practices.

Bridge updates

The Settings page compares the connected OpenMouse Bridge against its latest stable GitHub release. It only retrieves the version, changelog, and download link; it never downloads or installs an update in the background. Users can also run the check manually.

When Bridge is reachable, the control panel prefers its loopback native HID transport over browser WebHID. The same @openmouse/protocol drivers continue to handle device discovery and settings; Bridge only carries HID reports. This keeps Razer control interfaces protected by Chrome 153+ usable without relying on the browser's former protected-collection bypass.

Bridge connection attempts, disconnects, request failures, scan durations, and device inventory changes are written to the browser console with the [OpenMouse Bridge] prefix. The same lifecycle events are included in the downloadable diagnostics from a connected device's Advanced panel; HID report payloads are not written to the console.

The control panel is organized by feature. Tests sit next to the code they cover.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗