From 3effccf39013461a2be1e850093a92578bafd43e Mon Sep 17 00:00:00 2001 From: "Peter F. Patel-Schneider" Date: Wed, 23 Sep 2020 23:14:20 -0400 Subject: [PATCH] docs: update for USB and Bluetooth --- docs/capabilities.md | 24 +++++++++++------ docs/devices.md | 13 +++++++--- docs/features.md | 8 +++--- docs/index.md | 62 ++++++++++++++++++++++++++------------------ docs/installation.md | 18 +++++++------ docs/usage.md | 46 +++++++++++++++++++++++++++++--- 6 files changed, 118 insertions(+), 53 deletions(-) diff --git a/docs/capabilities.md b/docs/capabilities.md index dba49be0..31188190 100644 --- a/docs/capabilities.md +++ b/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++ -protocol. It is designed to detect all devices paired with your +your USB ports) +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 -Solaar. +identity of a device that connects to a receiver can be determined by +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. diff --git a/docs/devices.md b/docs/devices.md index 10dfa13f..e5c038a1 100644 --- a/docs/devices.md +++ b/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 diff --git a/docs/features.md b/docs/features.md index 58426611..de8d9045 100644 --- a/docs/features.md +++ b/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: | diff --git a/docs/index.md b/docs/index.md index cc2bedfa..477e794f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,33 +3,34 @@ title: Solaar layout: default --- -**Solaar** is a Linux manager for Logitech's devices that connect via USB -[Unifying][unifying], Lightspeed, or Nano receivers. -It does not work with Logitech peripherals that -use Bluetooth or peripherals from other companies. +**Solaar** is a Linux manager for many Logitech keyboards, mice, and trackpads +that connect wirelessly to a USB [Unifying][unifying], Lightspeed, or Nano receiver, +connect directly via a USB cable, or connect via Bluetooth. +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 -show information about each device, including battery status for devices that support this feature. -Solaar's GUI normally uses an icon in the system tray and starts with its main window hidden. -The program can be invoked in several ways +Both interfaces are able to list the connected devices and +show information about each device, often including battery status. +Solaar is able to pair and unpair devices with +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 -- `--window=hide` starts with its main window hidden -- `--window=only` do not use the system tray, but start with main window visible +Solaar's GUI normally uses an icon in the system tray and starts with its main window visible. +The GUI can be started in several ways + +- `--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 -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 +Solaar does not process normal input from 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]) -with any Unifying receiver and can pair and unpair devices with Lightspeed receivers. +Solaar will detect some Logitech devices that connect via a USB cable or Bluetooth. + +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 -Linux system configuration) are supported. For a list of supported devices +Solaar does not handle connecting or disconnecting via Bluetooth, +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. diff --git a/docs/installation.md b/docs/installation.md index b903d185..41307d36 100644 --- a/docs/installation.md +++ b/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 -you will then need to either physically remove the receiver and -re-insert it or reboot your computer. +For this rule to set up the correct permissions for your receivers and devices +you will then need to either disconnect your receivers and +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 diff --git a/docs/usage.md b/docs/usage.md index edebd817..12cd8a6d 100644 --- a/docs/usage.md +++ b/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 --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.