v0.2.0

New

• A versioned JSON interface for scripts and bar widgets, documented in docs/INTERFACE.md. Every --json output carries "interface": 1, and fields are only added within a version.
• list, keys and set now take --json. keys --json gives the full settings schema (kind, range, allowed values, unit), so a UI can be built without knowing the mouse.
• Errors come back inside the JSON with a code to branch on: permission, no-answer (mouse asleep or out of range) or io.
• No mouse connected is now "mice": [] with exit 0 instead of an error, so a bar can poll whether or not the dongle is plugged in.

Breaking

• status --json, battery --json and get --json changed shape. They now return an object ({"interface": 1, "mice": [...]}, or a single mouse for get) instead of a bare list or one value per line. See the doc for the new shapes.
• Battery states are now a fixed set: charging, discharging, full, unknown. The Attack Shark X11's "fully charged" and "charging/wired" are now full and charging, in the text output and the TUI as well.

No changes to how any mouse is configured.

Full Changelog: v0.1.2...v0.2.0

v0.1.2

New

• mousectl --version prints the installed version. The bug report form now asks for it.
• The README pins the pipx install to a release tag instead of main:
  pipx install "git+https://github.com/D3m0nZOnFire/mousectl@v0.1.2"

No changes to how any mouse is configured.

Full Changelog: v0.1.1...v0.1.2

v0.1.1

Fixed

• Attack Shark X11: settings could silently fail to apply over the dongle. The dongle sometimes loses a write, and mousectl set and mousectl restore still reported success. Every write is now read back and resent if it was lost; if the mouse still doesn't have it after 5 tries, mousectl says so with an error.
• Report descriptor parsing: Push/Pop items, long items, bits of one report packed across items, and truncated descriptors are now handled per the HID spec. No supported mouse's report lengths change.

New

• Install with pipx: pipx install git+https://github.com/D3m0nZOnFire/mousectl
• docs/PROTOCOLS.md: where each mouse's protocol comes from and what was checked on real hardware.
• TUI screenshot in the README, issue templates and a security policy.

Full Changelog: v0.1.0...v0.1.1

v0.1.0

First tagged release. Configure gaming mice on Linux over /dev/hidraw*, without vendor software. Pure Python 3 standard library: no packages, no venv.

Supported mice

Mouse	Links	id / alias
Attack Shark X11	wired 1d57:fa55, dongle 1d57:fa60	attackshark-x11 / ashark
Rapoo VT3 PRO	wired 24ae:4431, dongle 24ae:1231	rapoo-vt3pro / vt3pro
Pulsar X3 (PX3R21)	wired 3710:3409 / 3410, dongle 3710:5402 / 5403 (8K)	pulsar-x3 / x3

What's in it

• CLI: list, status, keys, get, set, battery (with --json), save / restore
• mousectl tui: every connected mouse in one curses TUI
• DPI stages, polling rate (up to 8K on the Pulsar dongle), lighting and battery, depending on the mouse
• An automatic backup of the mouse's original settings before the first write (~/.config/mousectl/<id>/auto-backup.json)
• mousectl install-udev: a uaccess udev rule so it runs without root

Install

git clone https://github.com/D3m0nZOnFire/mousectl && cd mousectl
./install.sh            # symlinks mousectl into ~/.local/bin
mousectl install-udev   # only if you get permission errors

New mouse? See docs/ADDING_A_DRIVER.md.