Rivalcfg: Configure SteelSeries gaming mice
===========================================

|GitHub| |Discord| |PYPI Version| |GitHub Actions| |Black| |License|

Rivalcfg is a **Python library** and a **CLI utility program** that allows you
to configure SteelSeries gaming mice on Linux, macOS and Windows (probably works on
BSD too, but not tested).

I first created this program to configure my Rival 100 and the original Rival
mice, then I added support for other Rival devices thanks to contributors.
Today this project aims to support any SteelSeries gaming mice (Rival,
Sensei, Aerox, Prime,...).

   **IMPORTANT:** This is an unofficial software. It was made by reverse
   engineering devices and is not supported nor approved by SteelSeries.

.. figure:: https://flozz.github.io/rivalcfg/_images/steelseries_mice.jpg
   :alt: SteelSeries Gaming Mice

If you have any trouble running this software, please open an issue on GitHub:

* https://github.com/flozz/rivalcfg/issues


Links
-----

* `Project website (rivalcfg.flozz.org) <https://rivalcfg.flozz.org/>`__
* `News and announces <https://rivalcfg.flozz.org/news/>`__
* `Download Rivalcfg <https://rivalcfg.flozz.org/download.html>`__
* `Supported and unsupported devices <https://rivalcfg.flozz.org/devices.html>`__
* `Rivalcfg documentation <https://flozz.github.io/rivalcfg/>`__:

  * `Requirements <https://flozz.github.io/rivalcfg/requirements.html>`__
  * `Install from sources <https://flozz.github.io/rivalcfg/install.html>`__
  * `Devices documentation <https://flozz.github.io/rivalcfg/devices/index.html>`__
  * `FAQ <https://flozz.github.io/rivalcfg/faq.html>`__
  * `Contributing <https://flozz.github.io/rivalcfg/contributing.html>`__ (please read before opening issues and PRs 😀️)


Supporting this project
-----------------------

Wanna support this project?

* `☕️ Buy me a coffee <https://www.buymeacoffee.com/flozz>`__,
* `❤️ sponsor me on GitHub <https://github.com/sponsors/flozz>`__,
* `💵️ or give me a tip on PayPal <https://www.paypal.me/0xflozz>`__.


Changelog
---------

* **[NEXT]** (changes on ``master`` that have not been released yet):

  * feat(device): Added support for lift-off distance setting on the Rival 650 (1038:172b) (@MAbbara, #288)
  * feat(device): Added support for querying the firmware version on Rival 3 Wireless (1038:1830) (@flozz)
  * fix(color_helpers): Fixed color-gradient validation (@eeshsaxena, #287)
  * misc(test): New E2E tests for devices (@flozz)
  * misc(standalone): Windows standalone build is now using Python 3.14 (@flozz)

* **v4.17.0:**

  * feat(device) Added support of the Rival 5 (1038:183C) mouse (@Saltblob, @nonoo, @flozz, #165, #268)
  * feat(device) Added support of the Rival 5 Destiny Edition (1038:183E) mouse (@flozz)
  * feat(device) Added initial support of the Prime+ (1038:182C) mouse (@BenJamesAndo, @flozz, #201)
  * feat(debug): Allowed to print bytes send to/received from the device by setting the ``RIVALCFG_DEBUG_PRINT_HID_REPORT`` env var (@flozz)
  * feat(debug): Do not print the udev rules warning in DRY debug mode (@flozz)
  * fix(debug): Fixed a crash when getting hidapi version without having setuptools installed (@flozz)
  * misc(standalone): Added a standalone build for Linux (@flozz)
  * misc(standalone): Added a standalone build for Windows (@flozz, #231)
  * misc(standalone): Added a standalone build for macOS (@flozz)
  * misc(ssdb): Updated ssdb script to extract the product_id of wireless mice dongles (@flozz)
  * docs(device): Added missing Aerox 5 documentation (@flozz)

* **v4.16.1 (hotfix):**

  * fix(device): Fixed Rival 3 Wireless Gen 2 becoming unusable after setting sensitivity (@flozz, #273)
  * fix(handler): Fixed ``multidpi_range_choice_xy`` handler with xxyy mapping using less than ``max_preset_count`` presets (@flozz, #273)

* **v4.16.0:**

  * feat(devices): Added support for the Aerox 3 Wireless CS2 Dragon Lore Edition (1038:187a, 1038:1878) (@flozz)
  * feat(devices): Added support for the Rival 3 Gen 2 (1038:1870) (#249, #257, @flozz, @orsonteodoro)
  * feat(devices): Added support for the Rival 3 Wireless Gen 2 (1038:1872) (#258, @flozz)
  * feat(handler): Added range_choice handler (@flozz)
  * feat(handler): Added multidpi_range_choice handler (@flozz)
  * feat(handler): Added multidpi_range_choice_xy handler (@flozz)
  * fix(devices): Fixed DPI values for devices using the TrueMove Air sensor (@flozz):

    * Aerox 3 Wireless (1038:183A, 1038:187A, 1038:1838, 1038:1878)
    * Aerox 5 (1038:1850)
    * Aerox 5 Wireless (1038:1854, 1038:185E, 1038:1862, 1038:1852, 1038:185C, 1038:1860)
    * Aerox 9 Wireless (1038:185A, 1038:1876, 1038:1858, 1038:1874)
    * Prime Wireless (1038:1842, 1038:184A, 1038:1840, 1038:1848)
    * Rival 3 Wireless (1038:1830)

  * fix(devices): Fixed DPI values for devices using the TrueMove Core sensor (@flozz):

    * Aerox 3 (1038:1836)
    * Rival 3 (1038:1824, 1038:184C)

  * fix(devices): Fixed DPI values for devices using the PixArt PMW3326 sensor (@flozz):

    * Rival 106 device (1038:1816)
    * Rival 110 device (1038:1729)
    * Rival 300S device (1038:1810)

  * misc(tests): Added tests for the Aerox 5 device (1038:1850) (@flozz)
  * misc: Modernized packaging setup.py/setuptools -> pyproject.toml/flit (@flozz)
  * misc: Added Python 3.14 support (@flozz)
  * misc!: Removed Python 3.9 support (@flozz)

* **v4.15.0:**

  * feat(devices): Added button support for Prime mouse (@flozz, 248)
  * fix(mouse): Fixed a crash when getting battery level in some circumstances (@flozz, #245)
  * docs(install): Updated install instructions for newer Python versions (@flozz #235)
  * docs(devices): Updated Prime Wireless and Prime Mini button schema (@flozz)

* **v4.14.0:**

  * feat: Added partial support of the Aerox 9 Wireless WOW Edition (@flozz)
  * feat: Allow to reduce the delay between two commands sent to devices (@Miskler, #236)
  * feat: Added an env var to remove the delay between commands to speedup the tests (@flozz)
  * misc: Added Python 3.13 support (@flozz)
  * misc!: Removed Python 3.8 support (@flozz)

* **v4.13.0:**

  * feat: Added button binding support for Rival 600 (@flozz)

* **v4.12.0:**

  * feat: Added Aerox 5 (wired) support (@flozz, #192)

* **v4.11.0:**

  * feat: Added Prime Mini support (@flozz, @NextWork123, #227)
  * misc: Added Python 3.12 support
  * misc!: Dropped Python 3.7 support

* **v4.10.0:**

  * Added Prime Mini Wireless support (@intersectRaven, #210, #207)
  * Code quality: more robust type comparison (@flozz)

* **v4.9.1:**

  * Improved device profile generation (@airblast-dev, #211)
  * Fixed battery level reported at 630% when the mouse is off
    (@LennardKittner, #187, #212)
  * Unrecognized arguments error when no device is found (@LennardKittner,
    #213, #214)

* **v4.9.0:**

  * Added Aerox 5 Wireless Destiny 2 Editon support (@flozz, #205)
  * Added Aerox 5 Wireless Diablo IV Edition support (@flozz, #206)
  * Updated HIDAPI to v0.14 to fix a macOS Ventura issue (@flozz, #200)
  * Removed the default lighting option for the Prime mouse (reported not
    working and not needed on this device) (@flozz, #196)

* **v4.8.0:**

  * Improved CLI startup time (@gryzus24, #194)
  * Added default lighting setting to following devices (@flozz, #191, #195):

    * Aerox 3
    * Aerox 3 Wireless
    * Aerox 5 Wireless
    * Aerox 9 Wireless
    * Prime
    * Prime Wireless

  * Added Python 3.11 support (@flozz)

* **4.7.0:**

  * Add initial Aerox 9 Wireless support (#188)
  * Add Aerox 5 Wireless support (#184)
  * Fix inverted firmware version minor and major digits
  * Fix crash when reading battry level of a device in sleep mode
  * Improve udev rules reloading
  * Rival 100: Rivalcfg is now able to read the firmware version of this device
    (#179, @staticssleever668)

* **4.6.0:**

  * Add support for the Prime Wireless mouse (#172)
  * Aerox 3 Wireless support improved:

    * Sleep timer support implemented
    * Dim timer support implemented
    * Brightness removed to support Dim timer (it is still possible to dim the
      LED by setting darker colors)

  * Fix a crash when printing debug information with udev rules not installed
  * Remove Python 2.7 compatibility code

* **4.5.0:**

  * Do not try to open devices when not needed (#170)
  * Add support for SteelSeries Prime Rainbow 6 Siege Black Ice Edition
    (1038:182A)
  * Add support for SteelSeries Prime CS:GO Neo Noir Edition (1038:1856)
  * Add initial support for the Rival 3 Wireless mouse (#146)
  * Add initial support for the Rival 650 mouse (#112)

* **4.4.0:**

  * Add Prime support (#169, @sephiroth99)
  * Add Aerox 3 (non wireless version) support (#156)
  * Add Aerox 3 Wireless support (#167)
  * Save devices settings on disk
  * Add Black (code formatter)
  * Drop Python 3.5 support
  * **WARNING:** This version will be the last one to support Python 2.7

* **4.3.0:**

  * Fixes Sensei TEN default config (#158)
  * Adds the ``--print-udev`` to generate udev rules and print them to ``stdout`` (#157)
  * CLI: Displays a usage message when no argument was given (#152)
  * CLI: Write udev warning message to ``stderr`` instead of ``stdout``
  * Adds a ``--print-debug`` option to display various information
  * Adds a ``--firmware-version`` option to display the firmware version of some devices
  * Rivalcfg can now read the firmware version of the following devices:

    * Rival 3
    * Rival 300
    * Rival 310
    * Rival 500
    * Rival 700 / 710
    * Sensei 310
    * Sensei TEN

* **4.2.0:**

  * Rival 3: support of firmware v0.37.0.0 (#147)
  * Support of the Sensei TEN (1038:1832)
  * Support of the Sensei TEN CS:GO Neon Rider Edition (1038:1834)
  * Rival 500:

    * Handles color shift
    * Handles button mapping

* **4.1.0:**

  * Support of the Rival 300S

  * Rival 310 support improved:

    * Support of button mapping

  * Sensei 310 support improved:

    * Support of button mapping

  * Rival 3 support improved:

    * Colors can now be defined separately
    * Button mapping support implemented
    * Light effects support implemented

* **4.0.0:**

  * Full rewrite of most parts of the software
  * Mice are now grouped by families to reduce code duplication
  * Improved udev support on Linux:

    * Dynamically generate udev rules instead of maintaining a static file
    * Automatically check that the rules file is up to date
    * Adds a command to update udev rules

  * Improved testing:

    * Better coverage
    * Test the device output to avoid regressions

  * Improved documentation:

    * A Sphinx documentation was added instead of stacking everything in the
      README
    * Each device family now have its own documentation page to make it easier
      to understand
    * Python APIs are now documented
    * A document was added to help contribute
    * Installation instructions were updated to recommend using Python 3

  * New devices support was added:

    * Support of the Rival 100 Dota 2 Edition (retail version) (#17)
    * Support of the Rival 300 Fallout 4 Edition (#44)
    * Support of the Rival 310 CS:GO Howl Edition (#113)
    * Support of the Rival 3 (#111)
    * Support of the Rival 300 Evil Geniuses Edition
    * Support of the Rival 95 MSI Edition
    * Support of the Rival 95 PC Bang
    * Support of the Rival 100 PC Bang
    * Support of the Rival 100 (Dell China)
    * Support of the Rival 600 Dota 2 Edition
    * Support of the Rival 106 (#84, @SethDusek)

  * Some devices gained a better support:

    * Rival 300 / Original Rival family

      * Support of buttons mapping

    * Rival 700 / 710

      * Support of gradients / Color shift (#129, @nixtux)

  * A generic support of mouse buttons mapping was added (rewriting of what was
    originally done for the Sensei [RAW]). The following devices now support
    it:

    * Rival 300 / Original Rival family
    * Sensei [RAW] family

  * Regressions:

    The following things were removed for this release:

    * Sensei Ten: this mouse needs more work to be added back.
    * Colorshift of the Rival 500: this feature needs more work to be added back.

Older changelog entries were moved to the `CHANGELOG.rst
<https://github.com/flozz/rivalcfg/blob/master/CHANGELOG.rst>`_ file.


.. |GitHub| image:: https://img.shields.io/github/stars/flozz/rivalcfg?label=GitHub&logo=github
   :target: https://github.com/flozz/rivalcfg

.. |Discord| image:: https://img.shields.io/badge/chat-Discord-8c9eff?logo=discord&logoColor=ffffff
   :target: https://discord.gg/P77sWhuSs4

.. |PYPI Version| image:: https://img.shields.io/pypi/v/rivalcfg?logo=python&logoColor=f1f1f1
   :target: https://pypi.org/project/rivalcfg/

.. |GitHub Actions| image:: https://github.com/flozz/rivalcfg/actions/workflows/python-ci.yml/badge.svg
   :target: https://github.com/flozz/rivalcfg/actions

.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://black.readthedocs.io/en/stable/

.. |License| image:: https://img.shields.io/github/license/flozz/rivalcfg
   :target: https://github.com/flozz/rivalcfg/blob/master/LICENSE