docs: update for USB and Bluetooth

docs/capabilities.md

@@ -8,16 +8,22 @@ layout: page
 [**Solaar**][solaar] reports on and controls [Logitech][logitech] devices
 (keyboards, mice, and trackballs) that connect to your computer via a
 Logitech USB receiver (a very small piece of hardware that plugs into one of
-your USB ports) and communicate with the receiver using Logitech's HID++
+your USB ports)
-protocol. It is designed to detect all devices paired with your
+It is designed to detect all devices paired with your
 receivers, and at the very least display some basic information about them.
-
 At this moment, all [Unifying][unifying] receivers are supported (devices
 with USB ID `046d:c52b` or `046d:c532`) as are several Lightspeed Receivers
 and a dozen Nano receivers.
 
+Solaar also reports on and controls some Logitech devices that connect to your
+computer using a USB cable or via Bluetooth.
+At this moment only a few devices types that connect via a USB cable or Bluetooth
+are supported in Solaar as information needs to be added to Solaar for each device type.
+
 ## HID++
 
+The devices that Solaar handles use Logitech's HID++ protocol.
+
 HID++ is a Logitech-proprietary protocol that extends the standard HID
 protocol for interfacing with keyboards, mice, and so on. It allows
 Logitech receivers to communicate with multiple devices and modify some
@@ -36,10 +42,12 @@ Contrariwise, two different devices may appear different physically but
 actually look the same to software. (For example, some M185 mice look the
 same to software as some M310 mice.)
 
-The software identity of a receiver can be determined by its USB id
+The software identity of a receiver can be determined by its USB product ID
 (reported by Solaar and also viewable in Linux using `lsusb`). The software
-identity of a device can be determined by its Wireless PID as reported by
+identity of a device that connects to a receiver can be determined by
-Solaar.
+its Wireless PID as reported by Solaar.  The software identity of devices that
+connect via a USB cable or via bluetooth can be determined by their USB or
+Bluetooth product ID.
 
 Even something as fundamental as pairing works differently for different
 receivers. For Unifying receivers, pairing adds a new paired device, but
@@ -64,7 +72,7 @@ that they were bought with.
 Solaar uses the HID++ protocol to pair devices to receivers and unpair
 devices from receivers, and also uses the HID++ protocol to display
 features of receivers and devices. Currently it only displays some
-features, but can modify even fewer. For more information on HID++ features
+features, and can modify even fewer. For a list of HID++ features
 and their support see [the features page](features).
 
 Solaar does not do anything beyond using the HID++ protocol to change the
@@ -82,7 +90,7 @@ WARNING: Updating firmware can cause a piece of hardware to become
 permanently non-functional if something goes wrong with the update or the
 update installs the wrong firmware.
 
-Solaar does keep track of some changeable state of a device between
+Solaar does keep track of some changeable settings of a device between
 invocations. When it starts, it restores on-line devices to their
 previously-known state, and while running it restores devices to
 their previously-known state when the device itself comes on line.

docs/devices.md

@@ -5,9 +5,10 @@ layout: page
 
 # Supported devices and receivers
 
-These tables list Logitech receivers and devices and to what degree their
+These tables provide a partial list of supported Logitech receivers and
+devices and to what degree their
 features are supported by Solaar. The information in these tables is
-incomplete, based on what devices users have been able to test Solaar with.
+based on what devices users have been able to test Solaar with.
 
 The HID++ column specifies the device's HID++ version. Some devices report
 version 4.5, but that is the same as version 2.0 as listed here.
@@ -40,11 +41,15 @@ arguments to the _D function are the device's long name, its short name
 (codename), its HID++ protocol version, its wireless product ID (wpid), and
 a tuple of known feature settings (from `lib/logitech/settings_templates.py`).
 
+If a device connects via a USB cable or via Bluetooth its USB or Bluetooth product ID
+has to be added in `lib/logitech/descriptors.py`.
+
+
 ### Receivers
 
 | USB ID    | Kind       | Max Paired Devices |
 ------------|------------|--------------------|
-| 046d:c517 | 27MHz old  | 2-4?               |
+| 046d:c517 | 27MHz old  | 4                  |
 | 046d:c518 | Nano       | 1                  |
 | 046d:c51a | Nano       | 1                  |
 | 046d:c51b | Nano       | 1                  |
@@ -214,7 +219,7 @@ setting is useful only to disable smooth scrolling.
 | EX100 keyboard   | 0065 | 1.0   | yes     |                                         |
 | EX100 mouse      | 003f | 1.0   | yes     |                                         |
 
-* The EX100 is old, preunifying set, supporting only part of HID++ 1.0 features
+* The EX100 is an old, preunifying receiver and device set, supporting only part of HID++ 1.0 features
 
 [solaar]: https://github.com/pwr-Solaar/Solaar
 [logitech]: https://www.logitech.com

docs/features.md

@@ -36,7 +36,7 @@ Feature                                | ID       | Status             | Notes
 `DEVICE_RESET`                         | `0x1802` | :x:                |
 `OOBSTATE`                             | `0x1805` | :x:                |
 `CONFIG_DEVICE_PROPS`                  | `0x1806` | :x:                |
-`CHANGE_HOST`                          | `0x1814` | :wrench:           |
+`CHANGE_HOST`                          | `0x1814` | :heavy_check_mark: |
 `HOSTS_INFO`                           | `0x1815` | :heavy_plus_sign:  | `get_host_names`, partial listing only
 `BACKLIGHT`                            | `0x1981` | :x:                |
 `BACKLIGHT2`                           | `0x1982` | :heavy_check_mark: | `_feature_backlight2`
@@ -50,7 +50,7 @@ Feature                                | ID       | Status             | Notes
 `REPROG_CONTROLS_V4`                   | `0x1B04` | :heavy_plus_sign:  | `get_keys`, _feature_reprogrammable_keys
 `REPORT_HID_USAGE`                     | `0x1BC0` | :x:                |
 `PERSISTENT_REMAPPABLE_ACTION`         | `0x1C00` | :wrench:           |
-`WIRELESS_DEVICE_STATUS`               | `0x1D4B` | :x:                | status reporting from device
+`WIRELESS_DEVICE_STATUS`               | `0x1D4B` | :heavy_plus_sign:  | status reporting from device
 `REMAINING_PAIRING`                    | `0x1DF0` | :x:                |
 `FIRMWARE_PROPERTIES`                  | `0x1F1F` | :x:                |
 `ADC_MEASUREMENT`                      | `0x1F20` | :x:                |
@@ -93,7 +93,7 @@ Feature                                | ID       | Status             | Notes
 `TOUCHMOUSE_RAW_POINTS`                | `0x6110` | :x:                |
 `TOUCHMOUSE_6120`                      | `0x6120` | :x:                |
 `GESTURE`                              | `0x6500` | :x:                |
-`GESTURE_2`                            | `0x6501` | :wrench:           | `_feature_gesture2_gestures`, `_feature_gesture2_params`
+`GESTURE_2`                            | `0x6501` | :heavy_plus_sign:  | `_feature_gesture2_gestures`, `_feature_gesture2_params`
 `GKEY`                                 | `0x8010` | :x:                |
 `MKEYS`                                | `0x8020` | :x:                |
 `MR`                                   | `0x8030` | :x:                |
@@ -104,7 +104,7 @@ Feature                                | ID       | Status             | Notes
 `PER_KEY_LIGHTING`                     | `0x8080` | :x:                |
 `PER_KEY_LIGHTING_V2`                  | `0x8081` | :x:                |
 `MODE_STATUS`                          | `0x8090` | :x:                |
-`ONBOARD_PROFILES`                     | `0x8100` | :x:                |
+`ONBOARD_PROFILES`                     | `0x8100` | :x:                | in progress
 `MOUSE_BUTTON_SPY`                     | `0x8110` | :x:                |
 `LATENCY_MONITORING`                   | `0x8111` | :x:                |
 `GAMING_ATTACHMENTS`                   | `0x8120` | :x:                |

docs/index.md

@@ -3,33 +3,34 @@ title: Solaar
 layout: default
 ---
 
-**Solaar** is a Linux manager for Logitech's devices that connect via USB
+**Solaar** is a Linux manager for many Logitech keyboards, mice, and trackpads
-[Unifying][unifying], Lightspeed, or Nano receivers.
+that connect wirelessly to a USB [Unifying][unifying], Lightspeed, or Nano receiver,
-It does not work with Logitech peripherals that
+connect directly via a USB cable, or connect via Bluetooth.
-use Bluetooth or peripherals from other companies.
+Solaar does not work with peripherals from other companies.
 
 Solaar can be used as a GUI application or via its command-line interface.
-Both interfaces are able to list the devices paired to a receiver and
+Both interfaces are able to list the connected devices and
-show information about each device, including battery status for devices that support this feature.
+show information about each device, often including battery status.
-Solaar's GUI normally uses an icon in the system tray and starts with its main window hidden.
+Solaar is able to pair and unpair devices with
-The program can be invoked in several ways
+receivers as supported by the device and receiver.
+Solaar can also control some changeable features of devices,
+such as smooth scrolling or function key behavior.
+For more information on how to use Solaar see
+[the usage page](https://pwr-solaar.github.io/Solaar/usage),
+and for more information on its capabilities see
+[the capabilities page](https://pwr-solaar.github.io/Solaar/capabilities).
 
-- `--window=show` (the default) starts with its main window visible
+Solaar's GUI normally uses an icon in the system tray and starts with its main window visible.
-- `--window=hide` starts with its main window hidden
+The GUI can be started in several ways
-- `--window=only` do not use the system tray, but start with main window visible
+
+- `--window=show` (the default) starts with its main window visible,
+- `--window=hide` starts with its main window hidden,
+- `--window=only` do not use the system tray, and start with main window visible.
 
 For more information on Solaar's command-line interface use the help option,
 as in `solaar --help`.
 
-Solaar is able to pair and unpair devices with
+Solaar does not process normal input from devices. It is thus unable
-receivers as supported by the receiver. Solaar can also control
-some changeable features of devices, such as smooth scrolling or
-function key behavior. For more information on how to use Solaar see
-[the usage page](https://pwr-solaar.github.io/Solaar/usage),
-and for more information on the capabilities see
-[the capabilities page](https://pwr-solaar.github.io/Solaar/capabilities).
-
-Solaar does not process normal input from the devices. It is thus unable
 to fix problems that arise from incorrect handling of mouse movements or keycodes
 by Linux drivers or other software.
 
@@ -45,18 +46,26 @@ Please report such experiences by creating an issue in
 
 [unifying]: https://en.wikipedia.org/wiki/Logitech_Unifying_receiver
 
+
 ## Supported Devices
 
 Solaar will detect all devices paired with your Unifying, Lightspeed, or Nano
 receiver, and at the very least display some basic information about them.
-It can pair and unpair a Logitech device showing the Unifying logo (Solaar's version of the [logo][logo])
+Solaar will detect some Logitech devices that connect via a USB cable or Bluetooth.
-with any Unifying receiver and can pair and unpair devices with Lightspeed receivers.
+
+Solaar can pair and unpair a Logitech device showing the Unifying logo
+(Solaar's version of the [logo][logo])
+with any Unifying receiver and
+can pair and unpair Lightspeed devices with Lightspeed receivers for the same model.
 Solaar can pair some Logitech devices with Logitech Nano receivers but not all Logitech
-devices can be paired with Nano receivers. Logitech devices without a Unifying logo
+devices can be paired with Nano receivers.
+Logitech devices without a Unifying logo
 generally cannot be paired with Unifying receivers.
 
-For some devices, extra settings (usually not available through the standard
+Solaar does not handle connecting or disconnecting via Bluetooth,
-Linux system configuration) are supported. For a list of supported devices
+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]: assets/solaar.svg
@@ -105,6 +114,9 @@ for the step-by-step procedure for manual installation.
   distributions. This is due to problems in many system tray
   implementations. Changing to a different theme may help.
 
+- Sometimes the system tray icon does not show up.  The cause of this is unknown.
+  Either wait a while and try again or try with the `--window=hide` option.
+
 - If some icons appear broken in the application, make sure you've properly
   configured the Gtk theme and icon theme in your control panel.
 

docs/installation.md

@@ -22,7 +22,7 @@ most likely good to go.
 
 Solaar requires Python 3.6+
 and the `python3-pyudev` package.
-To run the GUI, solaar also requires Gtk3, and its GObject
+To run the GUI Solaar also requires Gtk3, and its GObject
 introspection bindings.
 The Debian/Ubuntu packages that need to be installed are
 `python3-gi` and `gir1.2-gtk-3.0`;
@@ -30,9 +30,9 @@ in Fedora you need `gtk3` and `python3-gobject`;
 if you're using another
 distribution the required packages are most likely named something similar.
 
-If the desktop notifications bindings are also installed
+If desktop notifications bindings are also installed
 (`gir1.2-notify-0.7` for Debian/Ubuntu),
-you will also get desktop notifications when devices come online/go offline.
+you will also see desktop notifications when devices come online/go offline.
 For GNOME Shell/Budgie Desktop/KDE/XFCE support, you also need to have
 `gir1.2-ayatanaappindicator3-0.1` installed in Debian/Ubuntu. Although it is
 recommended to install and use `gir1.2-ayatanaappindicator3-0.1` if it is
@@ -48,14 +48,16 @@ that gives seated users write access to the HID devices for Logitech receiver an
 You can install this rule by copying, as root,
 `rules.d/42-logitech-unify-permissions.rules` from Solaar to
 `/etc/udev/rules.d`.
-The udev daemon will automatically pick up this file using inotify.
+You will probably also have to tell udev to reload its rule via
+`sudo udevadm control --reload-rules`.
 
-For this rule to set up the correct permissions for your receiver
+For this rule to set up the correct permissions for your receivers and devices
-you will then need to either physically remove the receiver and
+you will then need to either disconnect your receivers and
-re-insert it or reboot your computer.
+any USB-connected or Bluetooth-connected devices and
+re-connect them or reboot your computer.
 
 You only need to install Solaar's udev rule if it is not already installed
-on your system or you have a receiver that is not in the installed rule.
+on your system or the rule has changed.
 
 ## Running from the Download Directories
 

docs/usage.md

@@ -7,12 +7,13 @@ layout: page
 
 Under normal usage Solaar creates an icon in your system tray. This icon is
 usually a battery icon showing the approximate battery level for your device
-with the lowest known battery level. If there are no battery information,
+with the lowest known battery level. If there are no devices with battery information,
 then the icon is one of the Solaar icons.
 
-Solaar also has a main window. When it is invisible,
+Solaar also has a main window.  When the main window is invisible,
 click on the icon in the system tray to bring up the menu, and then
-click on a receiver or device in the menu.
+click on a receiver or device in the menu to see information about
+that receiver or device.
 
 The following is an image of the Solaar menu and the icon (the battery
 symbol is in the system tray at the left of the image). The icon can
@@ -49,11 +50,14 @@ about the selected receiver or device (useful for debugging).
 When a receiver is selected in the main window, you can pair a new device by
 clicking on the “Pair new device” button.
 Then turn on the device and it should pair with the receiver if that is possible.
+For multi-host devices first select the host position that you want.
+Some Lightspeed devices may pair by pressing a special pairing button.
 
 ![Solaar-main-window-receiver](Solaar-main-window-receiver.png)
 
 Some receivers can only pair with certain kinds of devices, other receivers
-pair a new device by replacing an existing paired device of the same kind, and even other receivers can only pair a limited number of times.
+pair a new device by replacing an existing paired device of the same kind,
+and even other receivers can only pair a limited number of times.
 A receiver with the Unifying logo should be able to pair with any device
 with the Unifying logo. If there are no open pairing slots, however, you may
 not be able to pair a new device. In this case to pair a new device you
@@ -110,3 +114,37 @@ 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.
+
+## Solaar settings
+
+Solaar supports the following settings:
+
+Setting                          | Description
+---------------------------------|------------
+Hand Detection			 | Turn on backlight when your hands hover over the keyboard
+Scroll Wheel Smooth Scrolling	 | Higher-speed vertical scrolling
+Side Scrolling	    		 | When off, side scrolling sends custom button events
+Scroll Wheel High Resolution	 | Higher-speed vertical scrolling
+Scroll Wheel HID++ Scrolling	 | When on, vertical scrolling uses HID++ events
+Scroll Wheel Direction		 | Reverse direction of vertical scrolling
+Scroll Wheel Resolution		 | Higher-speed vertical scrolling
+Scroll Wheel Rachet		 | Shift wheel ratchet on and off based on wheel speed
+Thumb Wheel HID++ Scrolling	 | When on, thumb-wheel scrolling uses HID++ events
+Thumb Wheel Direction		 | Reverse direction of thumb-wheel scrolling
+Sensitivity (DPI)		 | Mouse movement sensitivity
+Sensitivity (Pointer Speed)	 | Mouse movement sensitivity
+Backlight   			 | Turn on backlight
+Swap Fx function		 | Change Fn keys to normally do their special action
+Key/Button Actions   		 | Change what a key or button does
+Disable keys			 | Disable one or more keys
+Set OS				 | Change keys to match OS
+Change Host			 | Connect to a different host
+Gestures			 | Turn on and off various (mostly touchpad) gestures
+Gesture params			 | Modify parameters for gestures
+
+HID++ events are mostly not processed by Linux input drivers.
+Settings that involve sending HID++ events exist so that they can be
+turned off under Linux.
+
+Different Logitech devices may implement the same functionality in different ways,
+thus the different settings that do the same thing.