mouse_m908/README.md

156 lines
6.1 KiB
Markdown
Raw Normal View History

2019-11-08 17:09:17 -07:00
# mouse_m908
2020-08-29 09:00:34 -06:00
Control the Redragon M908 Impact, M709, M711 and M715 gaming mice from Linux, BSD and Haiku
2019-11-08 17:17:19 -07:00
2020-03-20 16:47:17 -06:00
**Disclaimer: This software is not supported by the manufacturer of the hardware in any way, and relies completely on information from reverse-engineering. There is no warranty, especially in case of damage to the hardware.**
2020-07-25 14:33:28 -06:00
- [Status](#status)
- [Supported mice](#supported-mice)
- [Installing](#installing)
- [Linux](#linux)
- [OpenBSD and FreeBSD](#openbsd-and-freebsd)
- [Haiku](#haiku)
- [Other platforms](#other-platforms)
- [Usage](#usage)
- [Macros](#macros)
- [Macro file](#macro-file)
- [--bus and --device options](#--bus-and---device-options)
- [--kernel-driver option](#--kernel-driver-option)
- [License](#license)
## Status
2020-07-31 10:41:47 -06:00
All settings from the official software are implemented, except repeating macros, which seems to be broken in the official software and is therefore currently disabled in this program.
2020-07-18 07:26:11 -06:00
### Supported mice
2020-07-25 14:33:28 -06:00
Name | Support | VID:PID | Additional notes
---|---|---|---
M908 | complete | 0x04d9:0xfc4d |
M709 | experimental | 0x04d9:0xfc2a | See [this issue](https://github.com/dokutan/mouse_m908/issues/1)<br>- Changing the profile works<br>- Changing the settings is untested but implemented<br>- Macros are untested<br>- Reading the settings is currently not properly implemented due to a lack of captured data
2020-09-05 12:56:52 -06:00
M711 | experimental | 0x04d9:0xfc30 | See [this issue](https://github.com/dokutan/mouse_m908/issues/2)<br>- Nothing is tested, please report your results<br>- Implemented: led color, mode, brightness and speed, changing profiles, macros, reading settings<br>- No usb capture available, therefore missing: button mapping, dpi, scrollspeed, usb poll rate
2020-08-29 09:00:34 -06:00
M715 | experimental | 0x04d9:0xfc39 | Nothing is tested, please report your results<br>- The device specific code is copied from the M711 and mostly unmodified
2020-07-18 07:26:11 -06:00
If you have a compatible device sold under a different name, or with a different VID or PID, please let me know so the readme can be updated.
2020-07-25 14:33:28 -06:00
If you want to add support for a different mouse, please open an issue (and pull request if you have code to contribute).
2020-04-03 09:57:53 -06:00
2019-11-08 17:21:11 -07:00
## Installing
2020-02-08 15:10:16 -07:00
### Linux
2019-11-08 17:17:19 -07:00
- Install the dependencies:
2020-05-14 13:46:58 -06:00
- libusb (On some distributions (e.g. Ubuntu) a dev package is required)
2020-02-07 21:00:14 -07:00
- Clone this repo or download a release and run
2020-03-17 14:15:07 -06:00
```
2020-03-17 14:07:19 -06:00
make
2019-11-08 17:17:19 -07:00
sudo make install
2020-03-17 14:15:07 -06:00
```
2019-11-08 17:17:19 -07:00
- Restart to get userspace access to the mouse via the installed udev rule
2019-11-30 16:09:48 -07:00
- Uninstall with
2020-03-17 14:15:07 -06:00
```
2019-11-30 16:09:48 -07:00
sudo make uninstall
2020-03-17 14:15:07 -06:00
```
2019-11-08 17:17:19 -07:00
2020-06-24 16:20:51 -06:00
### OpenBSD and FreeBSD
2020-02-08 15:10:16 -07:00
2020-06-24 16:20:51 -06:00
- Install dependencies:
- OpenBSD: libusb1
- FreeBSD: pkgconf
2020-02-08 15:10:16 -07:00
- Clone this repo and compile with
```
2020-04-19 07:41:45 -06:00
make CC=clang++
2020-02-08 15:10:16 -07:00
```
2020-06-13 08:26:01 -06:00
- Install with: (run as root)
```
make install-bsd
```
2020-06-24 16:20:51 -06:00
- OpenBSD: The --kernel-driver option is required
- FreeBSD: Running as root is required, however if you know how to fix this please let me know
2020-06-13 08:26:01 -06:00
- Uninstall with:
```
make uninstall
```
2020-04-19 08:21:04 -06:00
### Haiku
2020-05-27 08:55:04 -06:00
- Install dependencies: libusb and libusb_devel (from the HaikuPorts repo)
2020-04-19 08:21:04 -06:00
- Clone this repo and compile with
```
make
```
2020-05-27 08:55:04 -06:00
- Run with ``./mouse_m908`` or build a .hpkg package for installation with
```
make hpkg
```
- This should create a file named mouse_m908.hpkg in the Haiku directory. The .hpkg package can be installed with HaikuDepot.
2020-04-19 08:21:04 -06:00
- The --kernel-driver option is required
2020-02-08 15:10:16 -07:00
### Other platforms
2020-05-09 18:43:08 -06:00
Other platforms are not tested, however as long as the dependencies are available there is no special reason they should not be compatible. If you (tried) to compile on a platform that is not listed above, please report your results so this file can be updated (and potential bugs can be fixed).
2020-02-08 15:10:16 -07:00
2019-11-08 17:21:11 -07:00
## Usage
2020-07-20 13:22:21 -06:00
The settings are stored in a file and applied all at once (except macros, see below). See examples/example_m*.ini and keymap.md
2019-11-08 17:17:19 -07:00
2019-11-30 16:11:46 -07:00
- Apply the example configuration:
2019-11-08 17:17:19 -07:00
``
2020-07-20 13:22:21 -06:00
mouse_m908 -c examples/example_m908.ini
2019-11-08 17:17:19 -07:00
``
2020-08-14 11:33:57 -06:00
- To explicitly state which mouse to open, use the ``--model`` option, e.g. for the M709
2020-07-18 07:26:11 -06:00
``
2020-07-20 13:22:21 -06:00
mouse_m908 -c examples/example_m709.ini -M 709
2019-11-08 17:17:19 -07:00
``
2020-05-09 15:36:23 -06:00
- Read the configuration from the mouse and store it in config.ini:
``
2020-05-11 11:02:26 -06:00
mouse_m908 -R config.ini
2020-05-09 15:36:23 -06:00
``
2019-11-08 17:17:19 -07:00
- Set active profile to number 3:
``
mouse_m908 -p 3
``
- Get usage info:
``
mouse_m908 -h
``
2019-12-07 17:52:41 -07:00
- Send macro example.macro to slot 1:
``
2020-07-20 13:22:21 -06:00
mouse_m908 -m examples/example.macro -n 1
2019-12-07 17:52:41 -07:00
``
2020-07-20 13:22:21 -06:00
- Send all macros from example_m908.ini:
2020-05-13 11:28:09 -06:00
``
2020-07-20 13:22:21 -06:00
mouse_m908 -m examples/example_m908.ini
2020-05-13 11:28:09 -06:00
``
2019-12-07 17:52:41 -07:00
### Macros
2020-05-13 11:28:09 -06:00
There is space for 15 macros on the mouse, these are shared over all profiles. Each macro can hold up to 67 actions, any further actions get ignored.
There are two file formats in which macros can be specified, one macro per file (the older type) and multiple macros as comments in the config.ini file (as produced by ``mouse_m908 --read``).
To set a macro to a specific button:
2019-12-07 17:52:41 -07:00
1. Create a file containing the macro actions
2. Add macro⟨N⟩ to the button mapping configuration to set a button to the ⟨N⟩th macro
2020-05-13 11:28:09 -06:00
3. Apply the configuration: ``mouse_m908 -c ⟨config.ini⟩``
4. Depending on the file format:
- older type: Apply the specific macro: ``mouse_m908 -m ⟨macrofile⟩ -n ⟨N⟩``
2020-05-13 11:32:09 -06:00
- newer type: Apply all macros: ``mouse_m908 -m ⟨config.ini⟩``
2020-05-13 11:28:09 -06:00
2019-12-07 17:52:41 -07:00
#### Macro file
Each line contains an action and a parameter separated by a tab. Supported actions are:
- down ⟨key⟩
- up ⟨key⟩
2019-12-10 15:45:36 -07:00
- delay ⟨1-255⟩
2019-12-07 17:55:35 -07:00
2020-07-20 13:22:21 -06:00
examples/example.macro for an example of the older file format, examples/example_m*.ini for an example of the newer format, keymap.md section Keyboard keys/Keys for a list of recognized Keys. Supported mousebuttons (up and down):
2019-12-10 15:45:36 -07:00
- mouse_left
- mouse_right
- mouse_middle
2019-11-08 17:17:19 -07:00
2020-02-08 15:10:16 -07:00
### --bus and --device options
2020-02-07 20:34:17 -07:00
With these options the USB bus id and device number can be specified. This is useful if there are multiple devices with the same vendor and product id, or if the particular device has a different vendor or product id that is not expected by this software.
2020-02-08 15:10:16 -07:00
### --kernel-driver option
On some systems libusb might not be able to detect or detach kernel drivers, this results in a failure because the mouse can not be opened. This options skips this step.
2020-03-20 16:47:17 -06:00
2020-03-28 11:10:12 -06:00
## License
2020-03-20 16:47:17 -06:00
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.