attack-shark-x11-driver

A TypeScript driver for the Attack Shark X11 gaming mouse, providing access to its configuration over USB HID without relying on the official Windows-only software.

The project is primarily developed and tested on Linux, with Node.js and Bun support wherever the underlying HID implementation is compatible.

Features

• DPI and profiles: Configure DPI stages, select the active stage, and manage device profiles.
• Buttons and macros: Remap buttons and configure onboard macros.
• Lighting: Configure lighting modes and animation speeds.
• Polling rate: Select rates from 125 Hz to 1000 Hz.
• Device state: Read settings and monitor battery status.
• Command confirmation: Check whether the device acknowledged configuration commands.

Not yet implemented: Wake-up mode configuration, Left-Click Macro (Report ID 0x32-0x33);

Getting Started

Install the package:

npm install attack-shark-x11-driver

Example: change the polling rate and read it back.

import { AttackSharkX11, Rate, CommandConfirmation } from 'attack-shark-x11-driver';

try {
	// the class also implements the AsyncDisposable interface.
	await using driver = new AttackSharkX11();
	await driver.open();

	const status = await driver.setPollingRate({ rate: Rate.Office });
	if (status !== CommandConfirmation.Success) throw new Error('The device rejected the command.');

	console.log('Current polling rate:', await driver.getPollingRate());
} catch (error) {
	console.error('Mouse communication failed:', error);
} finally {
	console.log('\nDriver closed.');
}

Linux permissions

To access the mouse without running your application as a root, create /etc/udev/rules.d/99-attack-shark-x11.rules containing:

KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1d57", ATTRS{idProduct}=="fa60", MODE="0660", GROUP="plugdev", TAG+="uaccess"
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1d57", ATTRS{idProduct}=="fa55", MODE="0660", GROUP="plugdev", TAG+="uaccess"

Then reload the rules and reconnect the mouse:

sudo udevadm control --reload-rules
sudo udevadm trigger

If your distribution does not have a plugdev group, remove GROUP="plugdev" and use TAG+="uaccess" with a compatible session manager. Some environments may require logging out and back in before permissions take effect.

Compatibility

| Device | Connection | Status | |------------------|------------------|------------| | Attack Shark X11 | Wired | Supported | | Attack Shark X11 | 2.4 GHz wireless | Supported | | Attack Shark X11 | Bluetooth | Not tested |

If you want to test with a different VID and PID, you can try passing a different transport when creating the main class:

const driver = new AttackSharkX11({
	transport: new HidTransport({
		vendorId: 0x1d57,
		productIds: {
			wired: 0xfa55,
			wireless: 0xfa60,
		},
	}),
});

The Attack Shark R1 may use a related protocol, but compatibility has not been verified.

| Runtime | Status | |----------|--------------| | Node.js | Supported | | Bun | Supported | | Electron | Experimental | | Tauri | Experimental |

Electron and Tauri may require different HID handling depending on the process architecture and platform. In particular, Tauri applications should consider native HID communication through a Rust crate such as hidapi, while reusing the protocol encoding and parsing logic where appropriate. See issue #9.

Limitations and Safety

• Unverified commands: Avoid sending unknown or malformed packets. Some configuration changes may be stored persistently on the device.
• Command timing: Sending commands too quickly can result in dropped packets or timeouts.
• Temporary communication failures: Switching briefly to Bluetooth mode and then back to wired or 2.4 GHz mode may help restore normal operation. This is not a bootloader recovery procedure.
• Firmware recovery: This library does not provide firmware flashing or bootloader recovery functionality.
• Platform coverage: Linux receives the most testing; behavior on other platforms may differ.

Protocol Research

The docs/ directory contains protocol notes, captured packet structures, and reverse-engineering findings. Research has involved USBPcap and Wireshark captures, HID feature report inspection, analysis of official desktop and web-based software, and firmware investigation.

Some fields and device behaviors remain undocumented or only partially understood. Treat those findings as experimental rather than stable protocol guarantees.

Contributing

Issues and pull requests are welcome, particularly for protocol analysis, unknown packet fields, testing on other mouse models, native HID implementations, and improvements to validation or documentation.

For compatibility reports, include the mouse model, USB VID/PID, connection mode, official software version, relevant requests and responses, and whether the device returned to normal operation after testing.

Development and reverse-engineering work are currently limited by available time and funding. Existing research will remain public, but response times and future releases are not guaranteed.

Supporting the Project

Financial support can help make additional research and testing possible but does not guarantee features or release dates. Contributions of captures, bug reports, documentation, and test results are equally useful.

• GitHub Sponsors
• Ko-fi

Acknowledgments

Special thanks to Zelozzzz for the excellent work reverse-engineering the mouse firmware. Their investigation revealed several useful details about the device and helped me recover my own X11 after it became stuck in bootloader mode. That work made a real difference to this project's research.

If you're looking for a graphical mouse configuration tool, take a look at Dorsal, another project by Zelozzzz. It provides a Windows control application with configuration, diagnostics, and firmware-related features for supported gaming mice. Compatibility and firmware support vary by model. In particular, Dorsal lists the older X11 as wired-only and not yet tested on real hardware, so check its device notes before using it.

Dorsal is an independent project and is not required to use this library.

License

MIT © HarukaYamamoto0. See LICENSE.

This project is not affiliated with or endorsed by Attack Shark. Use it at your own risk.