diff --git a/docs/README.md b/docs/README.md index 708a6911..a8c11aa8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ # Documentation Readme -This project's documentation is hosted using GitHub pages, which serves static pages using Jeykll. +This project's documentation is hosted using GitHub pages, which serves static pages using Jekyll. [Please refer to the official documentation for instructions for how to build the site locally.](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/) diff --git a/docs/capabilities.md b/docs/capabilities.md index 296d0b12..dba49be0 100644 --- a/docs/capabilities.md +++ b/docs/capabilities.md @@ -2,13 +2,14 @@ title: Solaar Capabilities layout: page --- + # Solaar capabilities [**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. Solaar is designed to detect all devices paired with your +protocol. 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 @@ -18,98 +19,95 @@ and a dozen Nano receivers. ## HID++ HID++ is a Logitech-proprietary protocol that extends the standard HID -protocol for interfacing with keyboards, mice, and so on. HID++ allows +protocol for interfacing with keyboards, mice, and so on. It allows Logitech receivers to communicate with multiple devices and modify some -features of the device on the device itself. As the HID++ protocol is -proprietary many aspects of it are unknown. Some information about HID++ +features of the device on the device itself. As the HID++ protocol is +proprietary, many aspects of it are unknown. Some information about HID++ has been obtained from Logitech but even that is subject to change and extension. -There are several versions of the HID++ and many different Logitech -receivers and devices that utilize it. Different receivers and devices +There are several versions of the HID++ and many Logitech +receivers and devices that utilize it. Different receivers and devices implement different portions of HID++ so even if two devices appear to be -the same in both physical appearance and behavior they may working -completely differently underneath. (For example, there are versions of the +the same in both physical appearance and behavior they may work +completely differently underneath. (For example, there are versions of the M510 mouse that use different versions of the HID++ protocol.) Contrariwise, two different devices may appear different physically but -actually look the same to software. (For example, some M185 mice look the +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 -(reported by Solaar and also viewable in Linux using `lsusb`). The software +(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. Even something as fundamental as pairing works differently for different -receivers. For Unifying receivers, pairing adds a new paired device, but -only if there is an open slot on the receiver. So these receivers need to +receivers. For Unifying receivers, pairing adds a new paired device, but +only if there is an open slot on the receiver. So these receivers need to be able to unpair devices that they have been paired with or else they will -not have any open slots for pairing. Some other receivers, like the +not have any open slots for pairing. Some other receivers, like the Nano receiver with USB ID `046d:c534`, can only pair with particular kinds of devices and pairing a new device replaces whatever device of that kind was -previously paired to the receiver. These receivers cannot unpair. Further, +previously paired to the receiver. These receivers cannot unpair. Further, some receivers can pair an unlimited number of times but others can only pair a limited number of times. -Only some connections between receivers and devices are possible. In should +Only some connections between receivers and devices are possible. In should be possible to connect any device with a Unifying logo on it to any receiver -with a Unifying logo on it. Receivers without the Unifying logo probably +with a Unifying logo on it. Receivers without the Unifying logo probably can connect only to the kind of devices they were bought with and devices without the Unifying logo can probably only connect to the kind of receiver that they were bought with. - ## Supported features Solaar uses the HID++ protocol to pair devices to receivers and unpair -devices from receivers. Solaar also uses the HID++ protocol to display -features of receivers and devices. Solaar can modify some of the features -of devices. Solaar currently only displays some features and can modify -even fewer. For more information on HID++ features and their support in -Solaar see [docs/features.md](https://pwr-solaar.github.io/Solaar/features). +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 +and their support see [the features page](features). Solaar does not do anything beyond using the HID++ protocol to change the -behavior of receivers and devices. In particular, Solaar cannot change how +behavior of receivers and devices. In particular, it cannot change how the operating system turns the keycodes that a keyboard produces into -characters that are sent to programs. That is the province of HID device +characters that are sent to programs. That is the province of HID device drivers and other software (such as X11). -Logitech receivers and devices have firmware in them. Some of the firmware -can be updated using Logitech software in Windows. For example, there are +Logitech receivers and devices have firmware in them. Some firmware +can be updated using Logitech software in Windows. For example, there are security issues with some Logitech receivers and devices and Logitech has -firmware updates to alleviate these problems. Some Logitech firmware can +firmware updates to alleviate these problems. Some Logitech firmware can also be updated in Linux using `fwupdmgr`. -WARNING: Updating firmware can cause a piece of hardware to to become +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 of the changeable state of a device between -invocations. When Solaar starts it restores on-line devices to their -previously-known state. Also, while running Solaar restores devices to -their previously-known state when the device comes on line. +Solaar does keep track of some changeable state 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. This information is stored in the file `~/.config/solaar/config.json`. Querying a device for its current state can require quite a few HID++ -interactions. These interactions can temporarily slow down the device, so -Solaar tries to internally cache information about devices. If the device +interactions. These interactions can temporarily slow down the device, so +Solaar tries to internally cache information about devices. If the device state is changed by some other means, even sometimes by another invocation -of Solaar, this cached information may become incorrect. Currently there is -no way to force an update of the cached information besides terminating -Solaar and starting it again. - +of the program, this cached information may become incorrect. Currently there is +no way to force an update of the cached information besides restarting the +program. ## Battery Icons For many devices, Solaar shows the approximate battery level via icons that -show up in both main Solaar window and the system tray. Solaar used to use +show up in both the main window and the system tray. In previous versions several heuristics to determine which icon names to use for this purpose, but as more and more battery icon schemes have been developed this has -become impossible to do well. Solaar now uses the eleven standard +become impossible to do well. Solaar now uses the eleven standard battery icon names `battery-{full,good,low,critical,empty}[-charging]` and `battery-missing`. Solaar will use the symbolic versions of these icons if started with the -option `--battery-icons=symbolic`. Because of bugs external to Solaar +option `--battery-icons=symbolic`. Because of external bugs, these symbolic icons may be nearly invisible in dark themes. [solaar]: https://github.com/pwr-Solaar/Solaar diff --git a/docs/debian.md b/docs/debian.md index 9a891a8b..d1db8780 100644 --- a/docs/debian.md +++ b/docs/debian.md @@ -5,4 +5,4 @@ layout: page # Debian repository -Solaar is now part of the [official debian repository](https://packages.debian.org/solaar), to install it on your debian machine, use the following command: `sudo apt install solaar` +Solaar is now part of the [official Debian repository](https://packages.debian.org/solaar). To install it on your Debian machine, use the following command: `sudo apt install solaar` diff --git a/docs/devices.md b/docs/devices.md index ff5132ff..257b23e9 100644 --- a/docs/devices.md +++ b/docs/devices.md @@ -6,10 +6,10 @@ layout: page # Supported devices and receivers These tables list Logitech receivers and devices and to what degree their -features are supported by Solaar. The information in these tables is +features are supported by Solaar. The information in these tables is incomplete, based on what devices users have been able to test Solaar with. -The HID++ column specifies the device's HID++ version. Some devices report +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. For devices what support HID++ 2.0 or greater, Solaar is able to discover the features the device supports. @@ -20,32 +20,31 @@ level. For mice, the DPI column specifies if the mouse's sensitivity is fixed (`-`), can only be read (`R`), or can be read and changed by Solaar (`R/W`). -### Adding new receivers and devices +## Adding new receivers and devices Adding a new receiver requires knowing whether the receiver is a regular -Unifying receiver, a nano receiver, or a lightspeed receiver. Add a line to -../lib/logitech_receiver/base_usb.py defining the receiver as one of these. -If the receiver has an unusual number of pairing slots then this also needs -to be specified. Then add the receiver to the tuple of receivers (ALL). +Unifying receiver, a nano receiver, or a lightspeed receiver. Add a line to +`../lib/logitech_receiver/base_usb.py` defining the receiver as one of these. +If the receiver has an unusual number of pairing slots, then this also needs +to be specified. Then add the receiver to the tuple of receivers (ALL). To let Solaar read and write to the receiver information on it needs to be -added to rules.d/42-logitech-unify-permissions.rules. Add a new line to +added to `rules.d/42-logitech-unify-permissions.rules`. Add a new line to that file with the vendor and product ids, just like the other lines in the -file. Then this file has to be copied into /etc/udev/rules.d +file. Then this file has to be copied into `/etc/udev/rules.d`. -Most new devices do not need to be known to Solaar to work. However, an -entry in lib/logitech-receiver/descriptors.py can provide a better name for -the device and a feature list can speed up Solaar startup a bit. The +Most new devices do not need to be known to Solaar to work. However, an +entry in `lib/logitech-receiver/descriptors.py` can provide a better name for +the device and a feature list can speed up Solaar startup a bit. The 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). +a tuple of known feature settings (from `lib/logitech/settings_templates.py`). - -### Receivers: +### Receivers | USB ID | Kind | Max Paired Devices | ------------|------------|--------------------| -| 046d:c517 | 27Mhz old | 2-4? | +| 046d:c517 | 27MHz old | 2-4? | | 046d:c518 | Nano | 1 | | 046d:c51a | Nano | 1 | | 046d:c51b | Nano | 1 | @@ -64,10 +63,10 @@ a tuple of known feature settings (from lib/logitech/settings_templates.py). | 064d:c53f | Lightspeed | 1 | | 17ef:6042 | Nano | 1 | -* The receiver with usb Id 046d:c517 is old, 27 MHz receiver, supporting only +* The receiver with USB Id 046d:c517 is an old 27 MHz receiver, supporting only subset of HID++ 1.0 protocol. Only hardware pairing supported. -### Keyboards (Unifying): +### Keyboards (Unifying) | Device | WPID | HID++ | Battery | Other supported features | |------------------|------|-------|---------|-----------------------------------------| @@ -97,10 +96,9 @@ a tuple of known feature settings (from lib/logitech/settings_templates.py). window and display the current lighting value (Lux) as reported by the keyboard, similar to Logitech's *Solar.app* for Windows. -* FN swap changes the way the function keys (`F1`..`F12`) work, i.e., whether holding `FN` while pressing the function keys will generate the standard `Fx` keycodes or the special function (yellow icons) keycodes. +* FN swap changes the way the function keys (`F1`–`F12`) work, i.e., whether holding `FN` while pressing the function keys will generate the standard `Fx` keycodes or the special function (yellow icons) keycodes. - -### Mice (Unifying): +### Mice (Unifying) | Device | WPID | HID++ | Battery | DPI | Other supported features | |------------------|------|-------|---------|-------|---------------------------------| @@ -111,21 +109,21 @@ a tuple of known feature settings (from lib/logitech/settings_templates.py). | M317 | | | | | | | M325 | 400A | 2.0 | yes | 1000 | smooth scrolling | | M330 | | 2.0 | yes | 1000 | smooth scrolling | -| M345 | 4017 | 2.0 | yes | - | smooth scrolling | +| M345 | 4017 | 2.0 | yes | – | smooth scrolling | | M350 | 101C | 1.0 | yes | | | | M350 | 4080 | 2.0 | | | | | M505 | 101D | 1.0 | yes | | smooth scrolling, side scrolling| | M510 | 1025 | 1.0 | yes | | smooth scrolling, side scrolling| | M510 | 4051 | 2.0 | yes | | smooth scrolling | -| M515 Couch | 4007 | 2.0 | yes | - | smooth scrolling | -| M525 | 4013 | 2.0 | yes | - | smooth scrolling | -| M560 | | 2.0 | yes | - | smooth scrolling | +| M515 Couch | 4007 | 2.0 | yes | – | smooth scrolling | +| M525 | 4013 | 2.0 | yes | – | smooth scrolling | +| M560 | | 2.0 | yes | – | smooth scrolling | | M585 | 406B | 2.0 | yes | R/W | smooth scrolling | | M590 | 406B | 2.0 | yes | R/W | smooth scrolling | | M600 Touch | 401A | 2.0 | yes | | | -| M705 Marathon | 101B | 1.0 | yes | - | smooth scrolling, side scrolling| +| M705 Marathon | 101B | 1.0 | yes | – | smooth scrolling, side scrolling| | M705 Marathon | 406D | 2.0 | yes | R/W | smooth scrolling | -| M720 Triathlon | 405E | 2.0 | yes | - | | +| M720 Triathlon | 405E | 2.0 | yes | – | | | T400 Zone Touch | | 2.0 | yes | | smooth scrolling | | T620 Touch | | 2.0 | yes | | | | Performance MX | 101A | 1.0 | yes | R/W | smooth scrolling, side scrolling| @@ -135,18 +133,17 @@ a tuple of known feature settings (from lib/logitech/settings_templates.py). | MX Master 2S | 4069 | 2.0 | yes | R/W | smooth scrolling, smart shift | | Cube | | 2.0 | yes | | | - -### Mice (Nano): +### Mice (Nano) | Device | WPID | HID++ | Battery | DPI | Other supported features | |------------------|------|-------|---------|-------|---------------------------------| -| G7 | 1002 | 1.0 | yes | - | | -| G700 | 1023 | 1.0 | yes | - | smooth scrolling, side scrolling| -| G700s | 102A | 1.0 | yes | - | smooth scrolling, side scrolling| -| V450 Nano | 1011 | 1.0 | yes | - | smooth scrolling | -| V550 Nano | 1013 | 1.0 | yes | - | smooth scrolling, side scrolling| -| VX Nano | 100B | 1.0 | yes | - | smooth scrolling, side scrolling| -| VX Nano | 100F | 1.0 | yes | - | smooth scrolling, side scrolling| +| G7 | 1002 | 1.0 | yes | – | | +| G700 | 1023 | 1.0 | yes | – | smooth scrolling, side scrolling| +| G700s | 102A | 1.0 | yes | – | smooth scrolling, side scrolling| +| V450 Nano | 1011 | 1.0 | yes | – | smooth scrolling | +| V550 Nano | 1013 | 1.0 | yes | – | smooth scrolling, side scrolling| +| VX Nano | 100B | 1.0 | yes | – | smooth scrolling, side scrolling| +| VX Nano | 100F | 1.0 | yes | – | smooth scrolling, side scrolling| | M175 | 4008 | | yes | | | | M185 (old) | 4038 | 2.0 | yes | R/W | smooth scrolling (note) | | M185 (new) | 4054 | 2.0 | no | R/W | smooth scrolling (note) | @@ -157,50 +154,45 @@ a tuple of known feature settings (from lib/logitech/settings_templates.py). | M310 | 1024 | 1.0 | yes | | | | M315 | | | yes | | | | M330 | | ?.? | yes | ? | smooth scrolling | -| MX 1100 | 1014 | 1.0 | yes | - | smooth scrolling, side scrolling| +| MX 1100 | 1014 | 1.0 | yes | – | smooth scrolling, side scrolling| -(old): M185 with P/N: 810-003496 - -(new): M185 with P/N: 810-005238 or 810-005232 - -(note): Currently, smooth scrolling events are not processed in xfce and this +* (old): M185 with P/N: 810-003496 +* (new): M185 with P/N: 810-005238 or 810-005232 +* (note): Currently, smooth scrolling events are not processed in xfce and this setting is useful only to disable smooth scrolling. - -### Mice (Mini): - -| Device | WPID | HID++ | Battery | DPI | Other supported features | -|------------------|------|-------|---------|-------|---------------------------------| -| MX610 | 1001 | 1.0 | yes | | | -| MX610 lefthanded | 1004 | 1.0 | yes | | | -| MX620 | 100A | 1.0 | yes | | | -| MX620 | 1016 | 1.0 | yes | | | -| V400 | 1003 | 1.0 | yes | | | -| V450 | 1005 | 1.0 | yes | | | -| VX Revolution | 1006 | 1.0 | yes | | | -| VX Revolution | 100D | 1.0 | yes | | | -| MX Air | 1007 | 1.0 | yes | | | -| MX Air | 100E | 1.0 | yes | | | -| MX Revolution | 1008 | 1.0 | yes | | | -| MX Revolution | 100C | 1.0 | yes | | | - - -### Trackballs (Unifying): +### Mice (Mini) | Device | WPID | HID++ | Battery | DPI | Other supported features | |-------------------|------|-------|---------|-------|---------------------------------| -| M570 Trackball | | 1.0 | yes | - | | -| MX Ergo Trackball | | 2.0 | yes | - | | +| MX610 | 1001 | 1.0 | yes | | | +| MX610 left handed | 1004 | 1.0 | yes | | | +| MX620 | 100A | 1.0 | yes | | | +| MX620 | 1016 | 1.0 | yes | | | +| V400 | 1003 | 1.0 | yes | | | +| V450 | 1005 | 1.0 | yes | | | +| VX Revolution | 1006 | 1.0 | yes | | | +| VX Revolution | 100D | 1.0 | yes | | | +| MX Air | 1007 | 1.0 | yes | | | +| MX Air | 100E | 1.0 | yes | | | +| MX Revolution | 1008 | 1.0 | yes | | | +| MX Revolution | 100C | 1.0 | yes | | | -### Touchpads (Unifying): +### Trackballs (Unifying) + +| Device | WPID | HID++ | Battery | DPI | Other supported features | +|-------------------|------|-------|---------|-------|---------------------------------| +| M570 Trackball | | 1.0 | yes | – | | +| MX Ergo Trackball | | 2.0 | yes | – | | + +### Touchpads (Unifying) | Device | WPID | HID++ | Battery | DPI | Other supported features | |------------------|------|-------|---------|-------|---------------------------------| | Wireless Touch | 4011 | 2.0 | yes | | | | T650 Touchpad | 4101 | 2.0 | yes | | smooth scrolling | - -### Mice and Keyboards sold as combos: +### Mice and Keyboards sold as combos | Device | WPID | HID++ | Battery | Other supported features | |------------------|------|-------|---------|-----------------------------------------| @@ -216,7 +208,7 @@ setting is useful only to disable smooth scrolling. | EX100 keyboard | 6500 | 1.0 | yes | | | EX100 mouse | 3f00 | 1.0 | yes | | -* The EX100 is old, pre-unifying set, supporting only part of HID++ 1.0 features +* The EX100 is old, preunifying 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 b72701a3..05a79940 100644 --- a/docs/features.md +++ b/docs/features.md @@ -3,8 +3,11 @@ title: List of HID++ 2.0 features layout: page --- -# Feature status -See functions in hidpp20.py and settings_templates.py +# List of HID++ 2.0 features + +## Feature status + +See functions in `hidpp20.py` and `settings_templates.py` Feature | ID | Status | Notes ---------------------------------------|----------|:------------------:|------ @@ -17,7 +20,7 @@ Feature | ID | Status | Notes `DEVICE_GROUPS` | `0x0006` | :x: | `DEVICE_FRIENDLY_NAME` | `0x0007` | :x: | `KEEP_ALIVE` | `0x0008` | :x: | -`RESET` | `0x0020` | :x: | aka "Config Change" +`RESET` | `0x0020` | :x: | aka “Config Change” `CRYPTO_ID` | `0x0021` | :x: | `TARGET_SOFTWARE` | `0x0030` | :x: | `WIRELESS_SIGNAL_STRENGTH` | `0x0080` | :x: | @@ -110,9 +113,9 @@ Feature | ID | Status | Notes `EQUALIZER` | `0x8310` | :x: | `HEADSET_OUT` | `0x8320` | :x: | -"read only" in the notes column means that the feature is a read-only feature and cannot be changed. +A “read only” note means the feature is a read-only feature and cannot be changed. -# Implementing a feature +## Implementing a feature Features are implemented as settable features in lib/logitech_receiver/settings_templates.py @@ -134,8 +137,10 @@ should be a valid Python identifier. (Some older settings have dashes.) The label is displayed in the Solaar main window and the description is used as a tooltip there. The label and description should be specified as translatable strings. -``` -_POINTER_SPEED = ('pointer_speed', _("Sensitivity (Pointer Speed)"), _("How fast the pointer moves")) +```python +_POINTER_SPEED = ('pointer_speed', + _("Sensitivity (Pointer Speed)"), + _("How fast the pointer moves")) ``` Implement a register interface for the setting (if you are very brave and @@ -159,23 +164,27 @@ and which kinds of devices can have this setting. (This last is no longer used because keyboards with integrated pointers only report that they are keyboards.) The values to be used need to be determined from documentation of the -feature or from reverse-engineering behaviour of Logitech software under +feature or from reverse-engineering behavior of Logitech software under Windows or MacOS. -``` +```python def _feature_pointer_speed(): """Pointer Speed feature""" - return feature_range(_POINTER_SPEED[0], _F.POINTER_SPEED, 0x002e, 0x01ff, - read_function_id=0x0, - write_function_id=0x10, - bytes_count=2, - label=_POINTER_SPEED[1], description=_POINTER_SPEED[2], - device_kind=(_DK.mouse, _DK.trackball)) + return feature_range(_POINTER_SPEED[0], + _F.POINTER_SPEED, + 0x002e, + 0x01ff, + read_function_id=0x0, + write_function_id=0x10, + bytes_count=2, + label=_POINTER_SPEED[1], + description=_POINTER_SPEED[2], + device_kind=(_DK.mouse, _DK.trackball)) ``` Settings that are toggles or choices work very similarly. Settings where the choices are determined from the device -need an auxiliary function to receive and decipher the permissable choices. +need an auxiliary function to receive and decipher the permissible choices. See `_feature_adjustable_dpi_choices` for an example. Add an element to _SETTINGS_TABLE with @@ -189,6 +198,7 @@ The identifier is used in descriptors.py to say that a device has the register o The identifier can be the same as the setting name if there is only one implementation for the setting. This table is used to generate the data structures for describing devices in descriptors.py and is also used to auto-discover feature implementations. -``` + +```python _S( _POINTER_SPEED[0], _F.POINTER_SPEED, _feature_pointer_speed ), ``` diff --git a/docs/i18n.md b/docs/i18n.md index a6c57343..4eee8a50 100644 --- a/docs/i18n.md +++ b/docs/i18n.md @@ -1,3 +1,8 @@ +--- +title: Translating Solaar +layout: page +--- + # Translating Solaar First, make sure you have installed the `gettext` package. @@ -12,8 +17,8 @@ the source root): 2. Run `./tools/po-update.sh `; it will create/update the file `./po/.po`. -3. Edit `./po/.po` with your favourite editor (just make sure it saves - the file with the UTF-8 encoding). For each string in english (msgid), edit +3. Edit `./po/.po` with your favorite editor (just make sure it saves + the file with the UTF-8 encoding). For each string in English (msgid), edit the translation (msgstr); if you leave msgstr empty, the string will remain untranslated. @@ -22,7 +27,7 @@ the source root): 4. Run `./tools/po-compile.sh`. It will bring up-to-date all the compiled language files, necessary at runtime. -5. Start Solaar (`./bin/solaar`). By default it will pick up the system language +5. Start Solaar (`./bin/solaar`). By default, it will pick up the system language from your environment; to start it in another language, run `LANGUAGE= ./bin/solaar`. @@ -33,8 +38,7 @@ Before opening a pull request, please run `./tools/po-update.sh` again. It will format and sort the translation file, and ensure a minimal diff when updating a translation. - -# Supported languages +## Supported languages Currently Solaar has been translated in the following languages: diff --git a/docs/index.md b/docs/index.md index 9ff49c7b..65062b49 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,41 +3,41 @@ title: Solaar layout: default --- -**Solaar** is a Linux manager for Logitech's devices that connect via a USB -[Unifying][unifying], Lightspeed, or Nano receiver. -Solaar does not work with Logitech peripherals that +**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 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. -If Solaar is invoked with the `--window=show` option (the default) Solaar starts with its main window visible. -If Solaar is invoked with the `--window=hide` option Solaar starts with its main window hidden. -If solaar is invoked with the `--window=only` option Solaar does not set up an icon in the -system tray and also starts with its main window showing. +The program can be invoked 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, but 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 of the changeable features of devices, such as smooth scrolling or -function key behavior. -For more information on how to use Solaar see -[docs/usage.md](https://pwr-solaar.github.io/Solaar/usage). -For more information on the capabilities of Solaar see -[docs/capabilities.md](https://pwr-solaar.github.io/Solaar/capabilities). +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](usage), and for more information on the capabilities see +[the capabilities page](capabilities). -Solaar does not process normal input from the devices. Solaar is thus unable +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. -Solaar has progressed past version 1.0. Problems with earlier versions should -not be reported as bugs. Instead upgrade to a recent version or manually install +Solaar has progressed past version 1.0. Problems with earlier versions should +not be reported as bugs. Instead, upgrade to a recent version or manually install the current version from [GitHub](https://github.com/pwr-Solaar/Solaar). -Some of the capabilities of Solaar have been developed by observing the behavior of +Some capabilities of Solaar have been developed by observing the behavior of Logitech receivers and devices and generalizing from these observations. -If your Logitech receiver or device behaves in a strange way this may be caused by +If your Logitech receiver or device behaves strangely this may be caused by an incorrect behavior generalization. Please report such experiences by creating an issue in [the Solaar repository](https://github.com/pwr-Solaar/Solaar/issues). @@ -46,40 +46,39 @@ Please report such experiences by creating an issue in ## Supported Devices -**Solaar** will detect all devices paired with your Unifying, Lightspeed, or Nano +Solaar will detect all devices paired with your Unifying, Lightspeed, or Nano receiver, and at the very least display some basic information about them. -Solaar can pair and unpair a Logitech device showing the Unifying logo (Solaar's version of the [logo][logo]) +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 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 +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 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 -and their features, see [docs/devices.md](https://pwr-solaar.github.io/Solaar/devices). +and their features, see [the devices page](devices). -[logo]: https://pwr-solaar.github.io/Solaar/assets/solaar.svg +[logo]: assets/solaar.svg -## Pre-built packages +## Prebuilt packages -Pre-built packages are available for a few Linux distros. +Prebuilt packages are available for some Linux distros. Solaar has progressed beyond version 1.0 but some distros or repositories version 0.9.2, which is very old. Installing the current version will -provide significant improvements. If a recent version of Solaar is not +provide significant improvements. If a recent version of Solaar is not available from the standard repositories for your distribution you can try one of these packages. -* Arch solaar package in the [community repository][arch] -* Debian 7 (Wheezy) or higher: packages in this [repository](https://pwr-solaar.github.io/Solaar/debian) -* Ubuntu/Kubuntu 16.04+: use the solaar package from [universe repository][universe repository] -* Ubuntu/Kubuntu stable packages: use the [Solaar stable ppa][ppa2], courtesy of [gogo][ppa4] -* Ubuntu/Kubuntu git build packages: use the [Solaar git ppa][ppa1], courtesy of [gogo][ppa4] -* a [Fedora package][fedora], courtesy of Eric Smith -* a [Gentoo package][gentoo], courtesy of Carlos Silva and Tim Harder -* a [Mageia package][mageia], courtesy of David Geiger -* an [OpenSUSE rpm][opensuse], courtesy of Mathias Homann +- Arch solaar package in the [community repository][arch] +- Debian 7 (Wheezy) or higher: packages in this [repository](debian) +- Ubuntu/Kubuntu 16.04+: use the solaar package from [universe repository][universe repository] +- Ubuntu/Kubuntu stable packages: use the [Solaar stable ppa][ppa2], courtesy of [gogo][ppa4] +- Ubuntu/Kubuntu git build packages: use the [Solaar git ppa][ppa1], courtesy of [gogo][ppa4] +- a [Fedora package][fedora], courtesy of Eric Smith +- a [Gentoo package][gentoo], courtesy of Carlos Silva and Tim Harder +- a [Mageia package][mageia], courtesy of David Geiger +- an [OpenSUSE rpm][opensuse], courtesy of Mathias Homann Solaar uses a standard system tray implementation; solaar-gnome3 is no longer required for gnome or unity integration. @@ -96,14 +95,13 @@ Solaar uses a standard system tray implementation; solaar-gnome3 is no longer re ## Manual installation -See [docs/installation.md](https://pwr-solaar.github.io/Solaar/installation) for the step-by-step procedure for manual installation. - +See [the installation page](installation) for the step-by-step procedure for manual installation. ## Known Issues - The icon in the system tray can show up as 'black on black' in dark - distributions. This is due to problems in many system tray - implementations. Changing to a different theme may help. + distributions. This is due to problems in many system tray + implementations. Changing to a different theme may help. - If some icons appear broken in the application, make sure you've properly configured the Gtk theme and icon theme in your control panel. @@ -112,13 +110,11 @@ See [docs/installation.md](https://pwr-solaar.github.io/Solaar/installation) for application is also running *may* occasionally cause either of them to become confused about the state of the devices. - ## License This software is distributed under the terms of the [GNU Public License, v2](COPYING). - ## Thanks This project began as a third-hand clone of [Noah K. Tilton](https://github.com/noah)'s @@ -136,5 +132,5 @@ who also provided some internal - [Nestor Lopez Casado](http://drive.google.com/folderview?id=0BxbRzx7vEV7eWmgwazJ3NUFfQ28) provided some more Logitech specifications for the HID++ protocol -Also thanks to Douglas Wagner, Julien Gascard and Peter Wu for helping with +Also, thanks to Douglas Wagner, Julien Gascard, and Peter Wu for helping with application testing and supporting new devices. diff --git a/docs/installation.md b/docs/installation.md index 942fd482..d16fbc92 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -5,21 +5,19 @@ layout: page # Manual installation - ## Downloading -Clone solaar from GitHub via `git clone https://github.com/pwr-Solaar/Solaar.git` +Clone Solaar from GitHub by `git clone https://github.com/pwr-Solaar/Solaar.git` - -## Requirements for running Solaar +## Requirements for Solaar Installing Solaar from a repository should have set up all these requirements so in this situation you should be able to skip this section. Solaar needs a reasonably new kernel (5.2+ should work fine and recent CentOS distributions are likely to work), with kernel modules `hid-logitech-dj` -and `hid-logitech-hidpp` loaded. Also, the `udev` package must be installed -and its daemon running. If you have a recent Linux distribution, you are +and `hid-logitech-hidpp` loaded. Also, the `udev` package must be installed +and its daemon running. If you have a recent Linux distribution, you are most likely good to go. Solaar requires Python 3.6+ @@ -28,7 +26,7 @@ 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`; -in Fedora you need `gtk3` and `python3-gobject`; +in Fedora you need `gtk3` and `python3-gobject`; if you're using another distribution the required packages are most likely named something similar. @@ -41,8 +39,7 @@ recommended to install and use `gir1.2-ayatanaappindicator3-0.1` if it is available, you can also use `gir1.2-appindicator3-0.1` if necessary (e.g., for Unity in Ubuntu). - -### Installing Solaar's udev Rule +### Installing Solaar's udev rule Solaar needs to write to the receiver's HID device. To be able to do this without running as root requires a udev rule @@ -60,19 +57,17 @@ re-insert it 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. - ## Running from the Download Directories If Solaar's udev rule is installed, you can just go to the solaar directory and run `bin/solaar` for the GUI or `bin/solaar ` for the CLI. -Otherwise you will need to run Solaar as root via +Otherwise, you will need to run Solaar as root via `sudo bin/solaar` for the GUI or `sudo bin/solaar ` for the CLI. -Warning: Running Solaar as root may result in problems with the Solaar icon in the system tray. - +Warning: Running Solaar as root may result in problems with the Solaar icon in the system tray. ## Installing Solaar @@ -86,7 +81,7 @@ Once the udev rule has been installed you can then run Solaar as `~/.local/bin/s Installing python programs to system directories using pip is generally frowned on both because this runs arbitrary code as root and because this can override existing python libraries -that other users or even the system depend on. If you want to install solaar to /usr/local run +that other users or even the system depend on. If you want to install solaar to /usr/local run `sudo bash -c 'umask 022 ; pip install .'` in the solaar directory. (The umask is needed so that the created files and directories can be read and executed by everyone.) Then solaar can be run as /usr/local/bin/solaar. @@ -94,14 +89,12 @@ You will also have to install the udev rule. [pip]: https://en.wikipedia.org/wiki/Pip_(package_manager) - ## Solaar in other languages If you want to have Solaar's user messages in some other language you need to run `tools/po-compile.sh` to create the translation files before running or installing Solaar and set the LANGUAGE environment variable appropriately when running Solaar. - ## Running Solaar at Startup Distributions can cause Solaar can be run automatically at user login by installing a desktop file at @@ -109,7 +102,6 @@ Distributions can cause Solaar can be run automatically at user login by install If you install Solaar yourself you may need to create or modify this file or install a startup file under your home directory. - ## Installing from PyPI As an alternative to downloading and installing you can install the most recent release diff --git a/docs/usage.md b/docs/usage.md index c8fe6c28..edebd817 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -5,23 +5,22 @@ layout: page # Solaar usage -Under normal usage Solaar creates an icon in your system tray. This icon is +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 is no battery information to -show the icon is one of the Solaar icons. +with the lowest known battery level. If there are no battery information, +then the icon is one of the Solaar icons. -Solaar also has a main window. To show the main window if it is not visible -click on the icon in the system tray to bring up the Solaar menu and then +Solaar also has a main window. When it 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. -Here is an image of the Solaar menu and the Solaar icon (here the battery -symbol in the system tray at the left of the image ). The Solaar icon can +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 also be other battery icons or versions of the Logitech Unifying icon. ![Solaar-menu](Solaar-menu.png) -Clicking on "Quit" in the Solaar menu terminates Solaar. -Clicking on "About Solaar" pops up a window with information on Solaar. +Clicking on “Quit” in the Solaar menu terminates the program, and “About Solaar” pops up a window with further information. ## Solaar options @@ -41,29 +40,27 @@ view and change some settings of the selected receiver or device. To select a receiver or device click on it in the left side of the window. Closing the main window does not terminate Solaar (unless Solaar is not using the system tray). -Clicking on "Quit Solaar" terminates Solaar. -Clicking on "About Solaar" pops up a window with information on Solaar. -Clicking on the lightbulb (or similar icon) displays detailed information -about the selected receiver or device (mostly only useful for debugging). +Clicking on “Quit Solaar” terminates the program, and “About Solaar” pops up a window with further information. +The light bulb (or a similar icon) displays detailed information +about the selected receiver or device (useful for debugging). ### Pairing and unpairing devices -When a receiver is selected in the main window you can pair a new device by -clicking on the "Pair new device" button. +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. ![Solaar-main-window-receiver](Solaar-main-window-receiver.png) -Some receivers can only pair with certain kinds of devices. Some receivers -pair a new device by replacing an existing paired device of the same kind. -Some receivers can only pair a limited number of times. +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. 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 +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 first need to unpair a device. When a device is selected you can unpair the device if your receiver supports -unpairing. To unpair the device, just click on the "Unpair" button and +unpairing. To unpair the device, just click on the “Unpair” button and confirm in the window that pops up. ### Viewing and changing device settings @@ -72,14 +69,15 @@ When a device is selected you can see the approximate battery level of the device, if that is reported by the device, and the status of the link between the device and its receiver. You can also see some settings of the device and change -some of these. Changing settings is performed by clicking on buttons or +some of these. Changing settings is performed by clicking on buttons or moving sliders. ![Solaar-main-window-keyboard](Solaar-main-window-keyboard.png) ![Solaar-main-window-mouse](Solaar-main-window-mouse.png) -If the selected device is off or otherwise disconnected its settings cannot be changed +If the selected device is powered down or otherwise disconnected its settings +cannot be changed but it still can be unpaired if its receiver allows unpairing. ![Solaar-main-window-offline](Solaar-main-window-offline.png) @@ -87,14 +85,14 @@ but it still can be unpaired if its receiver allows unpairing. #### Remapping key and button actions For many devices Solaar can remap some of their keys or buttons to -perform a different action. (This actually changes the information that the -device sends when the key or button is activated.) Only some keys on some +perform a different action. (This changes the information that the +device sends when the key or button is activated.) Only some keys on some devices can be remapped and they can only be remapped to a limited -number of actions. The remapping is done in Solaar by selecting a key -or button in the left-hand box on the ``Action'' setting line and then -selecting the action to be performed in the right-hand box. The default -action is always the shown first in the list. As with all settings, -Solaar will remembers past action settings and restore them on the device +number of actions. The remapping is done by selecting a key +or button in the left-hand box on the “Action” setting line and then +selecting the action to be performed in the right-hand box. The default +action is always the shown first in the list. As with all settings, +Solaar will remember past action settings and restore them on the device from then on. ![Solaar-main-window-actions](Solaar-main-window-button-actions.png) @@ -106,10 +104,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 also has a command line interface that can do most of what can be -done using the Solaar main window. For more information on the Solaar -command line interface, run `solaar --help` to see the Solaar commands and +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.