Windows Support for CLI interface

.github/workflows/checks.yml

@@ -7,10 +7,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
-    - name: Setup Python
-      uses: actions/setup-python@v4.3.0
+    - name: Set up Python
+      uses: actions/setup-python@v5
 
     - name: Run pre-commit
       uses: pre-commit/[email protected]

.github/workflows/tests.yml

@@ -0,0 +1,60 @@
+name: tests
+
+on: [push, pull_request]
+
+jobs:
+  ubuntu-tests:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: [3.7, 3.12]
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install Ubuntu dependencies
+      run: |
+        make install_apt
+
+    - name: Install Python dependencies
+      run: |
+        make install_pip PIP_ARGS='.["test"]'
+
+    - name: Run tests on Ubuntu
+      run: |
+        make test
+
+  macos-tests:
+    runs-on: macos-latest
+
+    strategy:
+      matrix:
+        python-version: [3.7, 3.12]
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Set up macOS dependencies
+      run: |
+        make install_brew
+
+    - name: Install Python dependencies
+      run: |
+        make install_pip PIP_ARGS='.["test"]'
+
+    - name: Run tests on macOS
+      run: |
+        make test

ChangeLog.md

@@ -1,3 +1,55 @@
+# 1.1.11
+
+* Rename light icons and install them in correct place
+* Setup macOS tests using GitHub action (#2284)
+* Better checking for setting in record_setting
+* Fix invalid func name set logo name
+* Simplify installation of udev rules
+* Add document on implementation
+* Tidy up scrolling appearance in configuration panel
+* Correctly handle profile button with no action
+* Don't unlock setting when changed by external means
+* Refactor code to record change to setting
+* Add GitHub action for tests
+* Introduce tests with pytest
+* Simplify logger instantiation
+* Update label and tooltip for divert-gkeys setting
+* Don't lock setting when an error occurs
+* Catch assertion errors when reading setting values from devices
+* Support LED Zone control feature
+* Dump and load device profiles
+* Select among profiles.
+* Support backlight levels and duration
+* Use "Report Rate" instead of "Polling" for movement report rate
+* Support extended report rate setting
+* Add stable branch to release.sh (#2236)
+* Fix changelog parsing in release.sh
+* Update installation.md with new udev rules location
+* Downgrade assertion on missing notification flag to warning
+* Write empty file if there are no rules to save
+* Be defensive in device error messages
+* Add descriptions of M650, PRO X 2, G915, MX Anywhere 2S, G305, and MX Keys S
+* Report hidraw node in debugging messages
+* Add names for new Logitech features
+* Update Spanish, French, and Polish translations
+* Defend against lightspeed receivers that contact devices for basic information
+* Remove incorrect feature for M325 mice
+* Add K845 keyboard
+* Add partial support for macOS and minimal support for Windows
+* Correctly enumerate devices on receiver
+* Add wording in documentation about Logitech reusing model numbers
+* Better handling and installation of icons
+* Catch errors when pinging to try to put device online
+* Be more cautious when creating log messages to avoid exceptions
+* Correctly handle NoSuchDevice exception when pinging device
+* Fix test in rules for device equality
+* Add installation instructions for pipx and add not about other GTK system packages
+* Fix bug in NamedInt
+* Add support for MK550
+* Install udev rule files to correct placces
+* Expand expected ping responses
+* Update codename when device status changes
+
 # 1.1.10
 
 * Add information about NixOS flake package

Makefile

@@ -0,0 +1,53 @@
+UDEV_RULE_FILE = 42-logitech-unify-permissions.rules
+UDEV_RULES_SOURCE := rules.d/$(UDEV_RULE_FILE)
+UDEV_RULES_SOURCE_UINPUT := rules.d-uinput/$(UDEV_RULE_FILE)
+UDEV_RULES_DEST := /etc/udev/rules.d/
+
+PIP_ARGS ?= .
+
+.PHONY: install_ubuntu install_macos
+.PHONY: install_apt install_brew install_pip
+.PHONY: install_udev install_udev_uinput reload_udev uninstall_udev
+.PHONY: test
+
+install_ubuntu: install_apt install_udev_uinput install_pip
+
+install_macos: install_brew install_pip
+
+install_apt:
+	@echo "Installing Solaar dependencies via apt"
+	sudo apt update
+	sudo apt install libdbus-1-dev libglib2.0-dev
+
+install_brew:
+	@echo "Installing Solaar dependencies via brew"
+	brew update
+	brew install hidapi gtk+3 pygobject3
+
+install_pip:
+	@echo "Installing Solaar dependencies via pip"
+	python -m pip install --upgrade pip
+	pip install $(PIP_ARGS)
+
+install_udev:
+	@echo "Copying Solaar udev rule to $(UDEV_RULES_DEST)"
+	sudo cp $(UDEV_RULES_SOURCE) $(UDEV_RULES_DEST)
+	make reload_udev
+
+install_udev_uinput:
+	@echo "Copying Solaar udev rule (uinput) to $(UDEV_RULES_DEST)"
+	sudo cp $(UDEV_RULES_SOURCE_UINPUT) $(UDEV_RULES_DEST)
+	make reload_udev
+
+reload_udev:
+	@echo "Reloading udev rules"
+	sudo udevadm control --reload-rules
+
+uninstall_udev:
+	@echo "Removing Solaar udev rules from $(UDEV_RULES_DEST)"
+	sudo rm -f $(UDEV_RULES_DEST)/$(UDEV_RULE_FILE)
+	make reload_udev
+
+test:
+	@echo "Running Solaar tests"
+	pytest --cov=lib/ tests/

Release_Notes.md

@@ -1,5 +1,17 @@
 # Notes on Major Changes in Releases
 
+## Version 1.1.11
+
+* Solaar can dump device profiles in YAMLfor devices that support profiles and load profiles back from an edited file.  See [the capabilities page](https://pwr-solaar.github.io/Solaar/capabilities) for more information.
+
+* Solaar has settings for each LED Zone that a device supports under feature Color LED Effects.
+
+* Solaar has settings for extended report rate, backlight levels, durations, and profile selection.
+
+* Solaar now partly works in MacOS.  Please open new issues for problems.  Solaar may work in Windows.   Please open new issues for problems.  See https://github.com/pwr-Solaar/Solaar/pull/1971 for more information.  Fixing problems in MacOS or Windows may take considerable time.
+
+* Solaar works better when the Python package hid-parser is available.   Distriubtions should try have this package installed.
+
 ## Version 1.1.10
 
 * The mouse click rule action can now just simulate depressing or releasing the button.

docs/capabilities.md

@@ -174,6 +174,96 @@ is sent to the Solaar rule system so that rules can detect these notifications.
 For more information on Mouse Gestures rule conditions see
 [the rules page](https://pwr-solaar.github.io/Solaar/rules).
 
+### Device Profiles
+
+Some mice store one or more profiles, which control aspects of the behavior of the device.
+
+Profiles can control the rate at which the mouse reports movement, the resolution of the the movement reports, what the mouse buttons do, and its LED effects.  Solaar can dump the entire set of profiles into a YAML file can load an entire set of profiles from a file.  Users can edit the file to effect changes to the profiles.  Solaar has a setting that switches between profiles or disables all profiles.  When switching between profiles or using a button to change resolution Solaar keeps track of the changes in the settings for these features.
+
+When profiles are active changes cannot be made to the Report Rate setting.   Changes can be made to the Sensitivity setting and to LED settings.  To keep the profile values make these setting ignored.
+
+A profile file has some bookkeeping information, including profile version and the name of the device, and a sequence of profiles.
+
+Each profile has the following fields:
+- enabled: Whether the profile is enabled.
+- sector: Where the profile is stored in device memory.  Sectors greater than 0xFF are in ROM and cannot be written (use the low byte as the sector to write to Flash).
+- name: A memonic name for the profile.
+- report_rate: A report rate in milliseconds from 1 to 8.
+- resolutions: A sequence of five sensor resolutions in DPI.
+- resolution_default_index: The index of the default sensor resolution (0 to 4).
+- resolution_shift_index: The index of the sensor resolution used when the DPI Shift button is pressed (0 to 4).
+- buttons: The action for each button on the mouse in normal mode.
+- gbuttons: The action for each button on the mouse in G-Shift mode.
+- angle_snap: Enable angle snapping for devices.
+- red, blue, green: Color indicator for the profile.
+- lighting: Lighting information for logo and side LEDs in normal mode, then for power saving mode.
+- ps_timeout: Delay in ms to go into power saving mode.
+- po_timeout: Delay in ms to go from power saving mode to fully off.
+- power_mode: Unknown purpose.
+- write count: Unknown purpose.
+Missing or unused parts of a profile are often a sequence of 0xFF bytes.
+
+Button actions can either perform a function (behavior: 9) or send a button click or key press (behaviour: 8).
+Functions are:
+- 0: No Action - do nothing
+- 1: Tilt Left
+- 2: Tilt Right
+- 3: Next DPI - change device resolution to the next DPI
+- 4: Previous DPI - change device resolution to the previous DPI
+- 5: Cycle DPI - change device resolution to the next DPI considered as a cycle
+- 6: Default_DPI - change device resolution to the default resolution
+- 7: Shift_DPI - change device resolution to the shift resolution
+- 8: Next Profile - change to the next enabled profile
+- 9: Previous Profile - change to the previous enabled profile
+- 10: Cycle Profile - change to the next enabled profile considered as a cycle
+- 11: G-Shift - change all buttons to their G-Shift state
+- 12: Battery Status - show battery status on the device LEDs
+- 13: Profile Select - select the n'th enabled profile
+- 14: Mode Switch
+- 15: Host Button - switch between hosts (unverified)
+- 16: Scroll Down
+- 17: Scroll Up
+Some devices might not be able to perform all functions.
+
+Buttons can send (type):
+- 0: Don't send anything.
+- 1: A button click (value) as a 16-bit bitmap, i.e., 1 is left click, 2 is right, 4 is middle, etc.
+- 2: An 8-bit USB HID keycode (value) plus an 8-bit modifier bitmap (modifiers), i.e., 0 for no modifiers, 1 for control, 2 for shift, etc.
+- 3: A 16-bit HID Consumer keycode (value).
+
+See USB_HID_KEYCODES and HID_CONSUMERCODES in lib/logitech_receiver/special_keys.py for values to use for keycodes.
+
+Buttons can also execute macros but Solaar does not provide any support for macros.
+
+Lighting information is a sequence of lighting effects, with the first for the logo LEDs and the second for the side LEDs.
+
+The fields possible in an effect are:
+- ID: The kind of effect:
+- color: A color parameter for the effect as a 24-bit RGB value.
+- intensity: How intense to make the color (1%-100%), 0 for the default (usually 100%).
+- speed: How fast to pulse in ms (one byte).
+- ramp: How to change to the color (0=default, 1=ramp up/down, 2=no ramping).
+- period: How fast to perform the effect in ms (two bytes).
+- form: The form of the breathe effect.
+- bytes: The raw bytes of other effects.
+
+The possible effects and the fields the use are:
+- 0x0: Disable - No fields.
+- 0x1: Fixed color - color, whether to ramp.
+- 0x2: Pulse a color - color, speed.
+- 0x3 Cycle through the spectrum - period, intensity, form.
+- 0x8; A boot effect - No fields.
+- 0x9: A demo effect - NO fields.
+- 0xa: breathe a color (like pulse) - color, period.
+- 0xb: Ripple - color, period.
+- null: An unknown effect.
+Only effects supported by the device can be used.
+
+To set up profiles, first run `solaar profiles <device name>`, which will output a YAML dump of the profiles on the device. Then store the YAML dump into a file and edit the file to make changes. Finally run `solaar profiles <device name> <file name>` to load the profiles back onto the device. Profiles are stored in flash memory and persist when the device is inactive or turned off. When loading profiles Solaar is careful to only write the flash memory sectors that need to be changed. Solaar also checks for correct profile version and device name before loading a profile into a device.
+
+Keep a copy of the initial dump of profiles so that it can be loaded back to the device if problems are encountered with the edited profiles. The safest changes are to take an unused or unenabled profile sector and create a new profile in it, likely mostly copying parts of another profile.
+
+
 ## System Tray
 
 Solaar's GUI normally uses an icon in the system tray.

docs/devices/G305 Lightspeed Wireless Gaming Mouse 4074.text

@@ -0,0 +1,58 @@
+solaar version 1.1.10
+
+  1: G305 Lightspeed Wireless Gaming Mouse
+     Device path  : /dev/hidraw7
+     WPID         : 4074
+     Codename     : G305
+     Kind         : mouse
+     Protocol     : HID++ 4.2
+     Polling rate : 1 ms (1000Hz)
+     Serial number: ED5E9515
+     Model ID:      407400000000
+     Unit ID:       F074D567
+        Bootloader: BOT 69.02.B0021
+          Firmware: RQM 68.02.B0021
+     The power switch is located on the base.
+     Supports 27 HID++ 2.0 features:
+         0: ROOT                   {0000} V0
+         1: FEATURE SET            {0001} V0
+         2: DEVICE FW VERSION      {0003} V2
+            Firmware: Bootloader BOT 69.02.B0021 4074452F3940
+            Firmware: Firmware RQM 68.02.B0021 4074452F3940
+            Unit ID: F074D567  Model ID: 407400000000  Transport IDs: {'wpid': '4074'}
+         3: DEVICE NAME            {0005} V0
+            Name: G305 Lightspeed Wireless Gaming Mouse
+            Kind: mouse
+         4: WIRELESS DEVICE STATUS {1D4B} V0
+         5: BATTERY STATUS         {1000} V0
+            Battery: 50%, discharging, next level 30%.
+         6: COLOR LED EFFECTS      {8070} V6
+         7: ONBOARD PROFILES       {8100} V0
+            Device Mode: On-Board
+            Onboard Profiles (saved): Enable
+            Onboard Profiles        : Enable
+         8: MOUSE BUTTON SPY       {8110} V0
+         9: REPORT RATE            {8060} V0
+            Polling Rate (ms): 1
+            Polling Rate (ms) (saved): 1
+            Polling Rate (ms)        : 1
+        10: MODE STATUS            {8090} V1
+        11: DFUCONTROL SIGNED      {00C2} V0
+        12: DEVICE RESET           {1802} V0    internal, hidden
+        13: unknown:1803           {1803} V0    internal, hidden
+        14: CONFIG DEVICE PROPS    {1806} V4    internal, hidden
+        15: unknown:1811           {1811} V0    internal, hidden
+        16: OOBSTATE               {1805} V0    internal, hidden
+        17: unknown:1830           {1830} V0    internal, hidden
+        18: unknown:1890           {1890} V0    internal, hidden
+        19: unknown:1DF3           {1DF3} V0    internal, hidden
+        20: unknown:1E00           {1E00} V0    hidden
+        21: unknown:1EB0           {1EB0} V0    internal, hidden
+        22: unknown:1861           {1861} V0    internal, hidden
+        23: unknown:18B1           {18B1} V0    internal, hidden
+        24: unknown:1E22           {1E22} V0    internal, hidden
+        25: unknown:1801           {1801} V0    internal, hidden
+        26: ADJUSTABLE DPI         {2201} V1
+            Sensitivity (DPI) (saved): 1600
+            Sensitivity (DPI)        : 1600
+     Battery: 50%, discharging, next level 30%.