Merge branch 'master' into extract_rule_ui

.github/workflows/gh-pages.yml

@@ -0,0 +1,52 @@
+name: Deploy to GitHub Pages
+on:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs mkdocs-rtd-dropdown mkdocs-mermaid2-plugin mkdocstrings[python]
+
+      - name: Build and deploy
+        run: |
+          mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'site'
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1,9 +1,10 @@
-# <img src="https://pwr-solaar.github.io/Solaar/assets/solaar.svg" width="60px"/> Solaar
+# <img src="https://pwr-solaar.github.io/Solaar/img/solaar.svg" width="60px"/> Solaar
 
 Solaar is a Linux manager for many Logitech keyboards, mice, and other devices
 that connect wirelessly to a Unifying, Bolt, Lightspeed or Nano receiver
 as well as many Logitech devices that connect via a USB cable or Bluetooth.
-
+Solaar is not a device driver and responds only to special messages from devices
+that are otherwise ignored by the Linux input system.
 
 <a href="https://pwr-solaar.github.io/Solaar/index">More Information</a> -
 <a href="https://pwr-solaar.github.io/Solaar/usage">Usage</a> -

bin/solaar

@@ -21,10 +21,9 @@
 
 def init_paths():
     """Make the app work in the source tree."""
-    import os.path as _path
+    import os.path
     import sys
 
-    # Python 2 need conversion from utf-8 filenames
     # Python 3 might have problems converting back to UTF-8 in case of Unicode surrogates
     try:
         decoded_path = sys.path[0]
@@ -33,18 +32,17 @@ def init_paths():
     except UnicodeError:
         sys.stderr.write(
             "ERROR: Solaar cannot recognize encoding of filesystem path, "
-            "this may happen because non UTF-8 characters in the pathname.\n"
+            "this may happen due to non UTF-8 characters in the pathname.\n"
         )
         sys.exit(1)
 
-    prefix = _path.normpath(_path.join(_path.realpath(decoded_path), ".."))
-    src_lib = _path.join(prefix, "lib")
-    share_lib = _path.join(prefix, "share", "solaar", "lib")
+    root = os.path.join(os.path.realpath(decoded_path), "..")
+    prefix = os.path.normpath(root)
+    src_lib = os.path.join(prefix, "lib")
+    share_lib = os.path.join(prefix, "share", "solaar", "lib")
     for location in src_lib, share_lib:
-        init_py = _path.join(location, "solaar", "__init__.py")
-        # print ("sys.path[0]: checking", init_py)
-        if _path.exists(init_py):
-            # print ("sys.path[0]: found", location, "replacing", sys.path[0])
+        init_py = os.path.join(location, "solaar", "__init__.py")
+        if os.path.exists(init_py):
             sys.path[0] = location
             break
 

docs/capabilities.md

@@ -80,7 +80,7 @@ that they were bought with.
 ## Device Settings
 
 Solaar can display quite a few changeable settings of receivers and devices.
-For a list of HID++ features and their support see [the features page](features).
+For a list of HID++ features and their support see [the features page](features.md).
 
 Solaar does not do much beyond using the HID++ protocol to change the
 behavior of receivers and devices via changing their settings.

docs/implementation.md

@@ -3,8 +3,6 @@ title: Solaar Implementation
 layout: page
 ---
 
-TODO:  improve the callback mechanism(s) to support the explicit calls of the UI
-
 # Solaar Implementation
 
 Solaar has three main components: code mostly about receivers and devices, code for the command line interface, and code for the graphical user interface.
@@ -88,8 +86,6 @@ The module `descriptors` sets up information on device models for which Solaar n
 
 The module `base_usb` sets up information for most of the receiver models that Solaar supports, including USB id, USB interface used for HID++ messages, what kind of receiver model it is, and some capabilities of the receiver model.  Solaar can now support other receivers as long as they are not too unusual.  The module lso sets up lists of device models by USB ID and Bluetooth ID and provides a function to determine whether a USB ID or Bluetooth ID is an HID++ device model
 
-TODO?  Move some information down to descriptors?
-
 The module `base` provides functions that call discovery to enumerate all current receivers and devices and to set up a callback for when new receivers or devices are discovered.  It provides functions to open and close I/O channels to receivers and devices, write HID++ messages to receivers and devices, and read HID++ messages from receivers and devices.  It provides a function to turn an HID++ message into a notification.
 
 The module provides a function to send an HID++ message to a receiver or device, constructing the message from parameters to the function, and optionally waiting for and returning a response.  The function checks messages from the receiver or device, only terminating at timeout or when a message that appears to be the response is seen.  Other messages are turned into notifications if appropriate and ignoreed otherwise.  A separate function sends a ping message and waits for a reply to the ping.
@@ -109,8 +105,6 @@ After this processing HID++ 2.0 notifications are sent to the `diversion` module
 
 The `status` module provides the `DeviceStatus` class to record the battery status of a device.  It also provides an interface to signal changes to the connection status of the device that can invoke a callback.  This callback is used to update the Solaar user interface when the status changes.
 
-TODO:  check why solaar/listener.py sets the callback multiple times
-
 
 ### Settings
 
@@ -153,10 +147,6 @@ The Solaar GUI takes these settings and constructs an interface for displaying a
 
 This setup allows for very quick implementation of simple settings but it bypasses the data stored in a device object.
 
-TODO:  Refactor settings so that they always use data stored in device objects.  Set up code to create a device data as easily as simple settings are creates.  Set up code to use this to create a setting object for the Solaar GUI.  Use callbacks to control GUI redisplay whenever the device data changes.
-
-
-
 
 ### Solaar Rules
 
@@ -173,8 +163,6 @@ The module `common.py` provides utility functions, structures, and classes.
 `FirmwareInfo` provides information about device firmware.
 `BATTERY_APPROX` provides named integers used for approximate battery levels of devices.
 
-TODO: Move a couple of things from hidpp20 to here.
-
 `i18n.py` provides a few strings that need translations and might not otherwise be visible to translation software.
 
 `special_keys.py` provides named integers for various collections of key codes and colors.
@@ -192,8 +180,6 @@ Device and receiver discovery is performed when Solaar starts.  While the Solaar
 
 This code is also responsible for actual writing data to devices and receivers and reading data from them.
 
-TOD:  Is this actually the case?
-
 
 ## Solaar
 

docs/index.md

@@ -95,7 +95,7 @@ which is done using the usual Bluetooth mechanisms.
 For a partial list of supported devices
 and their features, see [the devices page](https://pwr-solaar.github.io/Solaar/devices).
 
-[logo]: https://pwr-solaar.github.io/Solaar/assets/solaar.svg
+[logo]: https://pwr-solaar.github.io/Solaar/img/solaar.svg
 
 ## Prebuilt packages
 
@@ -133,6 +133,8 @@ for the step-by-step procedure for manual installation.
 
 ## Known Issues
 
+- Onboard Profiles, when active, can prevent changes to other settings, such as Polling Rate, DPI, and various LED settings. Which settings are affected depends on the device.  To make changes to affected settings, disable Onboard Profiles.  If Onboard Profiles are later enabled the affected settings may change to the value in the profile.
+
 - Solaar version 1.1.12 has a bug resulting in devices remaining in their default configuration after a system resume.  This is fixed in 1.1.13.
 
 - Bluez 5.73 does not remove Bluetooth devices when they disconnect.

docs/rules.md

@@ -265,16 +265,14 @@ A `Later` action executes rule components later.
 `Later` actions take an integer delay in seconds between 1 and 100 followed by zero or more rule components that will be executed later.
 Processing of the rest of the rule continues immediately.
 
-### Built-in rules
-Solaar has several built-in rules, which are run after user-created rules and so can be overridden by user-created rules.
-One rule turns
+## Built-in Rules
+
+Solaar has a built-in rule, which is run after user-created rules and so can be overridden by user-created rules.
+This rule turns
 `Brightness Down` key press notifications into `XF86_MonBrightnessDown` key taps
 and `Brightness Up` key press notifications into `XF86_MonBrightnessUp` key taps.
-Another rule makes Craft crown ratchet movements move between tabs when the crown is pressed
-and up and down otherwise.
-A third rule turns Craft crown ratchet movements into `XF86_AudioNext` or `XF86_AudioPrev` key taps when the crown is pressed and `XF86_AudioRaiseVolume` or `XF86_AudioLowerVolume` otherwise.
-A fourth rule doubles the speed of `THUMB WHEEL` movements unless the `Control` modifier is on.
-All of these rules are only active if the key or feature is diverted, of course.
+
+## Example Solaar Rule File
 
 Solaar reads rules from a YAML configuration file (normally `~/.config/solaar/rules.yaml`).
 This file contains zero or more documents, each a rule.

docs/usage.md

@@ -136,9 +136,9 @@ It is possible to end up with an unusable system, for example by having no
 way to do a mouse left click, so exercise caution when remapping keys or
 buttons that are needed to operate your system.
 
-## Solaar command line interface
+## Solaar command-line interface
 
-Solaar also has a command line interface that can do most of what can be
+Solaar also has a command-line interface that can do most of what can be
 done using the main window. For more information on the
 command line interface, run `solaar --help` to see the commands and
 then `solaar <command> --help` to see the arguments to any of the commands.

lib/hidapi/hidconsole.py

@@ -29,6 +29,8 @@
 
 import hidapi
 
+LOGITECH_VENDOR_ID = 0x046D
+
 interactive = os.isatty(0)
 prompt = "?? Input: " if interactive else ""
 start_time = time.time()
@@ -38,10 +40,6 @@ def strhex(d):
     return hexlify(d).decode("ascii").upper()
 
 
-#
-#
-#
-
 print_lock = Lock()
 
 
@@ -130,8 +128,8 @@ def _validate_input(line, hidpp=False):
 
 def _open(args):
     def matchfn(bid, vid, pid, _a, _b):
-        if vid == 0x046D:
-            return {"vid": 0x046D}
+        if vid == LOGITECH_VENDOR_ID:
+            return {"vid": vid}
 
     device = args.device
     if args.hidpp and not device:
@@ -164,11 +162,6 @@ def matchfn(bid, vid, pid, _a, _b):
     return handle
 
 
-#
-#
-#
-
-
 def _parse_arguments():
     arg_parser = argparse.ArgumentParser()
     arg_parser.add_argument("--history", help="history file (default ~/.hidconsole-history)")