RivalBridge

I have played World of Warcraft with the same mouse for years: a SteelSeries Rival 500, fifteen buttons, a thumb cluster that fits my hand, and a little flick switch under the thumb that I bind to something important. Then SteelSeries moved on. The mouse was dropped from the current software, the old Engine 3 was left behind, and on a new Mac the extra buttons did nothing at all. The hardware was perfect. The company had simply stopped talking to it.

RivalBridge is the app I wrote to talk to it instead.

The problem, exactly

Plug the Rival 500 into a Mac and look at what it announces on the USB bus. It offers three channels. One is an ordinary mouse: movement, the wheel, and room for exactly eight buttons. One is a keyboard, which the mouse uses when a button has been told to type a key. The third is a private configuration channel that only SteelSeries' software knew how to speak.

That eight-button limit is the whole story. Fifteen buttons cannot all be mouse buttons, so buttons 9 through 13 and the two wheel tilts were always routed through the configuration software, which either turned them into keystrokes or ran them itself. Take that software away and seven buttons go dark. WoW can bind a mouse button, and it can bind a key; what it cannot bind is a button the computer never hears about.

What RivalBridge does

It works in two layers.

The hardware layer speaks the configuration channel directly, from native Swift, with no drivers and no SteelSeries software. The protocol was recovered by the open-source rivalcfg project, and RivalBridge's version of it is checked byte-for-byte against that project's output in a test suite. Through this channel the app sets the two DPI presets, the polling rate, the colours and cycles of the logo and wheel lights, and the job of every one of the fifteen buttons: a mouse button, a scroll, the DPI switch, a typed key, a media key, off, or app-controlled. Whatever it writes can also be saved into the mouse's own memory, so the mouse behaves the same on another computer with nothing installed.

The bridge layer is the part SteelSeries used to provide and no longer does. An app-controlled button is told, in the mouse, to type a hidden key that nothing else uses (F13 to F24). RivalBridge then takes the mouse's keyboard channel away from macOS entirely, so those hidden keys never leak into a document or a game, and it sees each press and release with the exact identity of the button. For each one it does whatever the active profile says:

• act as an extra mouse button, so WoW sees Mouse Button 9 through 15 and binds them like any other, Shift, Ctrl and Alt combinations included;
• press a keyboard shortcut, held for as long as the button is held;
• scroll, in either direction;
• type text, or run a sequence of steps with waits between them, for work outside the game.

Profiles switch by the app in front. When WoW is frontmost the buttons do WoW's work; on the desktop the wheel tilt goes back to scrolling sideways. Keys the mouse was told to type on its own still pass straight through, and media keys are re-posted as media keys, so handing the channel to RivalBridge costs nothing.

Using it

1. Open RivalBridge from the menu bar. The Buttons tab shows the mouse from the top and from the thumb side; click any button to change what it does in the mouse and what it does in each profile.
2. Grant the two macOS permissions it asks for: Input Monitoring, to read the hidden keys, and Accessibility, to post the events it makes.
3. Press Write to mouse. The map, DPI, polling rate and lights go into the mouse, and by default into its onboard memory.
4. In WoW, open Options › Keybindings, click the action you want, and press the mouse button. It appears as Mouse Button 9 to 15.

Buttons set to be plain mouse buttons, to type a key or to switch DPI keep working with RivalBridge closed. Only the app-controlled ones need it running; that is what the menu-bar icon is for.

Playing by the rules

Blizzard's policy is one press, one action. A key that casts two spells is automation, and RivalBridge does not encourage it: the sequence and text actions exist for the desktop, and the app labels any action that would send more than one input per press. In the game, every button is a single key or a single mouse button, exactly as a keyboard would be.

Under the hood

Native SwiftUI menu-bar app for macOS 14 and later, built with XcodeGen. IOKit HID for both the configuration channel and the seized keyboard interface; Core Graphics events for what it posts. Thirteen unit tests compare every packet the app can build with rivalcfg's reference output, including the LED gradient encoding and its rule that a colour cycle closes back on its first colour. Nothing is sent anywhere: there is no account, no network, no telemetry.

RivalBridge is not affiliated with SteelSeries or Blizzard Entertainment.