logi-gamepad-bridge

Bridge the browser Gamepad Haptics API (GamepadHapticActuator) to HapticWebPlugin on Logitech MX Master 4.

• npm: logi-gamepad-bridge
• GitHub: humbertogontijo/logi-gamepad-bridge

Prerequisites

1. Install HapticWebPlugin (Logi Options+ + MX Master 4).
2. Ensure local.jmw.nz resolves to 127.0.0.1.
3. Grant local network access in the browser when prompted.

Browser injection

Paste in the DevTools Console on any tab (patches navigator.getGamepads()):

document.head.appendChild(Object.assign(document.createElement('script'),{src:'https://unpkg.com/[email protected]/dist/inject.min.js'}))

A 404 plus nosniff in the console means the CDN returned an HTML error page (often 0.1.0, which has no inject bundle). Hard-refresh or pin the version above.

When you see Gamepad API patched, pick Logitech MX Master 4 (HapticWeb Bridge) if the site lists gamepads, then use its vibration/rumble controls. If it does not show up, refresh and run the line again before the page reads gamepads.

Install (npm)

npm install logi-gamepad-bridge

Test UI

git clone https://github.com/humbertogontijo/logi-gamepad-bridge.git
cd logi-gamepad-bridge
npm install
npm run dev

Opens http://localhost:5173 — click Connect (HapticWebPlugin must be running).

Build

npm install
npm run build

Produces dist/index.js (library) and dist/inject.min.js (browser injection bundle).

Usage

import { connectLogiGamepad } from 'logi-gamepad-bridge';

const bridge = connectLogiGamepad({
  patchGetGamepads: true,
});

window.addEventListener('gamepadconnected', (e) => {
  const actuator = e.gamepad.vibrationActuator;
  if (!actuator) return;

  void actuator.playEffect('dual-rumble', {
    duration: 300,
    strongMagnitude: 0.9,
    weakMagnitude: 0.4,
  });
});

Direct actuator

import { LogiGamepadBridge } from 'logi-gamepad-bridge';

const bridge = new LogiGamepadBridge();
bridge.connect();

void bridge.actuator.pulse(0.8, 200);

How it works

| Gamepad API | Bridge | HapticWebPlugin | | ----------------------------------- | --------------------------------------------- | ------------------------------ | | playEffect('dual-rumble', params) | Maps magnitude/duration → waveform index 0–14 | ws.send(Uint8Array([index])) | | pulse(value, duration) | Same mapper | WebSocket | | reset() | Clears pending delayed effects | — |

The MX Master 4 only supports 15 fixed waveforms, not continuous rumble. Intensity is capped by Logi Options+ haptic strength.

API

• LogiGamepadBridge — WebSocket client + actuator + optional synthetic Gamepad
• LogiHapticActuator — GamepadHapticActuator implementation
• HapticWebClient — low-level HapticWeb WebSocket client
• mapEffectToWaveformIndex / mapPulseToWaveformIndex
• connectLogiGamepad() / getLogiGamepadBridge()

License

MIT