Mirror of forum.nim-lang.org

13941 :: nimouse: A command-line tool for configuring Microsoft IntelliMouse

• luciano (orginal) [2026-05-23T13:53:42+02:00] view original

  

  nimouse

  A command-line tool for configuring Microsoft IntelliMouse devices on Linux, macOS, and Windows. Written in Nim.

  https://github.com/lucianofedericopereira/nimouse

  
  $ nimouse get 0 --all
  Microsoft Pro IntelliMouse:
    color:              #FF0000  ██
    dpi:                1600
    polling rate:       1000 Hz
    lift-off distance:  2 mm
    back button:        BackButton
    middle button:      MiddleClick
  Run

  Copyright © 2026 Luciano Federico Pereira — MIT License Adapted from intellimouse-ctl by Kim Visscher (© 2022, MIT)

  ---

  Features

  Feature	Pro IntelliMouse (2019)	Classic IntelliMouse (2017)
  DPI	200 – 16 000 (×50)	400 – 3 200 (×200)
  LED tail-light color	✓ (16M colors)	—
  Polling rate	125 / 500 / 1000 Hz	—
  Lift-off distance	2 mm / 3 mm	—
  Button remapping	✓ back + middle	—
  Config file	✓	✓
  JSON output	✓	✓
  Shell completion	✓	✓

  ---

  Install

  Dependencies

  Linux (Debian/Ubuntu)

  
  sudo apt install libhidapi-dev
  Run

  Linux (Arch)

  
  sudo pacman -S hidapi
  Run

  macOS

  
  brew install hidapi
  Run

  Windows — download hidapi.dll from the hidapi releases page and place it next to the binary.

  Build from source

  
  # Install Nim via choosenim (https://nim-lang.org/install.html)
  curl https://nim-lang.org/choosenim/init.sh -sSf | sh
  
  git clone https://github.com/yourusername/nimouse
  cd nimouse
  nimble install
  Run

  This installs the nimouse binary to ~/.nimble/bin/.

  Linux: run without sudo

  Create /etc/udev/rules.d/99-intellimouse.rules:

  
  # Microsoft Pro IntelliMouse
  SUBSYSTEM=="hidraw", ATTRS{idVendor}=="045e", ATTRS{idProduct}=="082a", MODE="0666"
  # Microsoft Classic IntelliMouse
  SUBSYSTEM=="hidraw", ATTRS{idVendor}=="045e", ATTRS{idProduct}=="0823", MODE="0666"
  Run

  Reload rules:

  
  sudo udevadm control --reload-rules && sudo udevadm trigger
  Run

  ---

  Usage

  
  nimouse <subcommand> [options]
  Run

  list — show connected devices

  
  nimouse list
  nimouse list --json
  Run

  
  0. Microsoft Pro IntelliMouse
     path: /dev/hidraw2
  Run

  ---

  get — read settings

  
  nimouse get 0 --all                        # everything
  nimouse get 0 --dpi                        # single setting
  nimouse get 0 --dpi --color --polling-rate # multiple
  nimouse get 0 --back-button --middle-button
  nimouse get 0 --all --json                 # machine-readable
  Run

  Flags

  Flag	Description
  --dpi	DPI value
  --color	LED tail-light color (hex + preview)
  --polling-rate	Polling rate in Hz
  --lift-off-distance	Lift-off distance in mm
  --back-button	Current back button action
  --middle-button	Current middle button action
  --all	All of the above (default)
  --json	Output as JSON

  ---

  set — change settings

  
  nimouse set 0 --dpi=1600
  nimouse set 0 --polling-rate=500           # 125 | 500 | 1000
  nimouse set 0 --lift-off-distance=2        # 2 | 3
  Run

  LED color — accepts hex strings, named colors, or decimals:

  
  nimouse set 0 --color=red
  nimouse set 0 --color="#FF8800"
  nimouse set 0 --color=0xFF8800
  nimouse set 0 --color=off                  # turn off the light
  Run

  Named colors: red green blue white purple cyan yellow orange pink off

  Button remapping — use nimouse button-actions to list valid action names:

  
  nimouse set 0 --back-button=BrowserForward
  nimouse set 0 --middle-button=DpiShift
  nimouse set 0 --back-button=IncreaseDpi --middle-button=DecreaseDpi
  Run

  ---

  button-actions — list remappable actions

  
  nimouse button-actions
  Run

  
  Available button actions:
    BackButton
    BrowserForward
    MiddleClick
    HorizVertToggle
    DpiShift
    IncreaseDpi
    DecreaseDpi
    KeyCombination
    Alt
    Ctrl
    Shift
    Enter
  Run

  ---

  config-save / config-load — persist settings

  Save the current device settings to disk:

  
  nimouse config-save
  nimouse config-save --index=1   # save device at index 1
  Run

  Restore them later (e.g. on login):

  
  nimouse config-load
  Run

  Config file location: $XDG_CONFIG_HOME/nimouse/config.ini (defaults to ~/.config/nimouse/config.ini)

  
  [defaults]
  index = 0
  
  [pro]
  dpi = 1600
  polling_rate = 1000
  lift_off_distance = 2
  color = 16711680
  
  [classic]
  dpi = 1600
  Run

  To apply settings automatically on login, add nimouse config-load to your .profile, .bash_profile, or a systemd user service.

  ---

  Shell completion

  
  # bash — add to ~/.bashrc
  source <(nimouse --help-syntax bash)
  
  # zsh — add to ~/.zshrc
  source <(nimouse --help-syntax zsh)
  
  # fish — add to ~/.config/fish/config.fish
  nimouse --help-syntax fish | source
  Run

  ---

  Protocol

  The USB HID protocol used to communicate with these mice has been reverse-engineered by the community. See PROTOCOL.md for full technical details including all property codes, byte layouts, and known button action codes.

  Sources used:

  • xlanor/intellimouse — USB packet captures and Go implementation
  • namazso/ProIntelliColor — independent C verification
  • k-visscher/intellimouse-ctl — original Python library

  ---

  License

  MIT — see LICENSE

  Copyright © 2026 Luciano Federico Pereira Adapted from intellimouse-ctl by Kim Visscher (© 2022)

---