RomanNum3ral
/
Solaar
mirror of https://github.com/pwr-Solaar/Solaar.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

cleanup and lint the docs

This commit is contained in:
John Erling Blad 2020-08-02 14:15:29 +02:00 committed by Peter F. Patel-Schneider
parent 6645b5b04c
commit aaee650caf
9 changed files with 217 additions and 228 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/README.md
View File

@ -1,4 +1,4 @@
# Documentation Readme # 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/) [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/)

80
docs/capabilities.md
View File

@ -2,13 +2,14 @@
title: Solaar Capabilities title: Solaar Capabilities
layout: page layout: page
--- ---
# Solaar capabilities # Solaar capabilities
[**Solaar**][solaar] reports on and controls [Logitech][logitech] devices [**Solaar**][solaar] reports on and controls [Logitech][logitech] devices
(keyboards, mice, and trackballs) that connect to your computer via a (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 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) 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. receivers, and at the very least display some basic information about them.
At this moment, all [Unifying][unifying] receivers are supported (devices At this moment, all [Unifying][unifying] receivers are supported (devices
@ -18,98 +19,95 @@ and a dozen Nano receivers.
## HID++ ## HID++
HID++ is a Logitech-proprietary protocol that extends the standard 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 Logitech receivers to communicate with multiple devices and modify some
features of the device on the device itself. As the HID++ protocol is features of the device on the device itself. As the HID++ protocol is
proprietary many aspects of it are unknown. Some information about HID++ proprietary, many aspects of it are unknown. Some information about HID++
has been obtained from Logitech but even that is subject to change and has been obtained from Logitech but even that is subject to change and
extension. extension.
There are several versions of the HID++ and many different Logitech There are several versions of the HID++ and many Logitech
receivers and devices that utilize it. Different receivers and devices receivers and devices that utilize it. Different receivers and devices
implement different portions of HID++ so even if two devices appear to be implement different portions of HID++ so even if two devices appear to be
the same in both physical appearance and behavior they may working the same in both physical appearance and behavior they may work
completely differently underneath. (For example, there are versions of the completely differently underneath. (For example, there are versions of the
M510 mouse that use different versions of the HID++ protocol.) M510 mouse that use different versions of the HID++ protocol.)
Contrariwise, two different devices may appear different physically but 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.) 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 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 identity of a device can be determined by its Wireless PID as reported by
Solaar. Solaar.
Even something as fundamental as pairing works differently for different Even something as fundamental as pairing works differently for different
receivers. For Unifying receivers, pairing adds a new paired device, but 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 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 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 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 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 some receivers can pair an unlimited number of times but others can only
pair a limited number of times. 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 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 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 without the Unifying logo can probably only connect to the kind of receiver
that they were bought with. that they were bought with.
## Supported features ## Supported features
Solaar uses the HID++ protocol to pair devices to receivers and unpair Solaar uses the HID++ protocol to pair devices to receivers and unpair
devices from receivers. Solaar also uses the HID++ protocol to display devices from receivers, and also uses the HID++ protocol to display
features of receivers and devices. Solaar can modify some of the features features of receivers and devices. Currently it only displays some
of devices. Solaar currently only displays some features and can modify features, but can modify even fewer. For more information on HID++ features
even fewer. For more information on HID++ features and their support in and their support see [the features page](features).
Solaar see [docs/features.md](https://pwr-solaar.github.io/Solaar/features).
Solaar does not do anything beyond using the HID++ protocol to change the 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 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). drivers and other software (such as X11).
Logitech receivers and devices have firmware in them. Some of the firmware Logitech receivers and devices have firmware in them. Some firmware
can be updated using Logitech software in Windows. For example, there are can be updated using Logitech software in Windows. For example, there are
security issues with some Logitech receivers and devices and Logitech has 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`. 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 permanently non-functional if something goes wrong with the update or the
update installs the wrong firmware. update installs the wrong firmware.
Solaar does keep track of some of the changeable state of a device between Solaar does keep track of some changeable state of a device between
invocations. When Solaar starts it restores on-line devices to their invocations. When it starts, it restores on-line devices to their
previously-known state. Also, while running Solaar restores devices to previously-known state, and while running it restores devices to
their previously-known state when the device comes on line. their previously-known state when the device itself comes on line.
This information is stored in the file `~/.config/solaar/config.json`. This information is stored in the file `~/.config/solaar/config.json`.
Querying a device for its current state can require quite a few HID++ Querying a device for its current state can require quite a few HID++
interactions. These interactions can temporarily slow down the device, so interactions. These interactions can temporarily slow down the device, so
Solaar tries to internally cache information about devices. If the device Solaar tries to internally cache information about devices. If the device
state is changed by some other means, even sometimes by another invocation state is changed by some other means, even sometimes by another invocation
of Solaar, this cached information may become incorrect. Currently there is of the program, this cached information may become incorrect. Currently there is
no way to force an update of the cached information besides terminating no way to force an update of the cached information besides restarting the
Solaar and starting it again. program.
## Battery Icons ## Battery Icons
For many devices, Solaar shows the approximate battery level via icons that 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, 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 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 icon names `battery-{full,good,low,critical,empty}[-charging]` and
`battery-missing`. `battery-missing`.
Solaar will use the symbolic versions of these icons if started with the 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. these symbolic icons may be nearly invisible in dark themes.
[solaar]: https://github.com/pwr-Solaar/Solaar [solaar]: https://github.com/pwr-Solaar/Solaar

2
docs/debian.md
View File

@ -5,4 +5,4 @@ layout: page
# Debian repository # 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`

128
docs/devices.md
View File

@ -6,10 +6,10 @@ layout: page
# Supported devices and receivers # Supported devices and receivers
These tables list Logitech receivers and devices and to what degree their 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. 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. 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 For devices what support HID++ 2.0 or greater, Solaar is able to discover
the features the device supports. the features the device supports.
@ -20,32 +20,31 @@ level.
For mice, the DPI column specifies if the mouse's sensitivity is fixed (`-`), 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`). 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 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 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. `../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 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 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 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 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 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 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 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 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 (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 | | USB ID | Kind | Max Paired Devices |
------------|------------|--------------------| ------------|------------|--------------------|
| 046d:c517 | 27Mhz old | 2-4? | | 046d:c517 | 27MHz old | 2-4? |
| 046d:c518 | Nano | 1 | | 046d:c518 | Nano | 1 |
| 046d:c51a | Nano | 1 | | 046d:c51a | Nano | 1 |
| 046d:c51b | 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 | | 064d:c53f | Lightspeed | 1 |
| 17ef:6042 | Nano | 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. subset of HID++ 1.0 protocol. Only hardware pairing supported.
### Keyboards (Unifying): ### Keyboards (Unifying)
| Device | WPID | HID++ | Battery | Other supported features | | 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 window and display the current lighting value (Lux) as reported by the
keyboard, similar to Logitech's *Solar.app* for Windows. 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 | | 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 | | | | | | | M317 | | | | | |
| M325 | 400A | 2.0 | yes | 1000 | smooth scrolling | | M325 | 400A | 2.0 | yes | 1000 | smooth scrolling |
| M330 | | 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 | 101C | 1.0 | yes | | |
| M350 | 4080 | 2.0 | | | | | M350 | 4080 | 2.0 | | | |
| M505 | 101D | 1.0 | yes | | smooth scrolling, side scrolling| | M505 | 101D | 1.0 | yes | | smooth scrolling, side scrolling|
| M510 | 1025 | 1.0 | yes | | smooth scrolling, side scrolling| | M510 | 1025 | 1.0 | yes | | smooth scrolling, side scrolling|
| M510 | 4051 | 2.0 | yes | | smooth scrolling | | M510 | 4051 | 2.0 | yes | | smooth scrolling |
| M515 Couch | 4007 | 2.0 | yes | - | smooth scrolling | | M515 Couch | 4007 | 2.0 | yes | – | smooth scrolling |
| M525 | 4013 | 2.0 | yes | - | smooth scrolling | | M525 | 4013 | 2.0 | yes | – | smooth scrolling |
| M560 | | 2.0 | yes | - | smooth scrolling | | M560 | | 2.0 | yes | – | smooth scrolling |
| M585 | 406B | 2.0 | yes | R/W | smooth scrolling | | M585 | 406B | 2.0 | yes | R/W | smooth scrolling |
| M590 | 406B | 2.0 | yes | R/W | smooth scrolling | | M590 | 406B | 2.0 | yes | R/W | smooth scrolling |
| M600 Touch | 401A | 2.0 | yes | | | | 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 | | 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 | | T400 Zone Touch | | 2.0 | yes | | smooth scrolling |
| T620 Touch | | 2.0 | yes | | | | T620 Touch | | 2.0 | yes | | |
| Performance MX | 101A | 1.0 | yes | R/W | smooth scrolling, side scrolling| | 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 | | MX Master 2S | 4069 | 2.0 | yes | R/W | smooth scrolling, smart shift |
| Cube | | 2.0 | yes | | | | Cube | | 2.0 | yes | | |
### Mice (Nano)
### Mice (Nano):
| Device | WPID | HID++ | Battery | DPI | Other supported features | | Device | WPID | HID++ | Battery | DPI | Other supported features |
|------------------|------|-------|---------|-------|---------------------------------| |------------------|------|-------|---------|-------|---------------------------------|
| G7 | 1002 | 1.0 | yes | - | | | G7 | 1002 | 1.0 | yes | – | |
| G700 | 1023 | 1.0 | yes | - | smooth scrolling, side scrolling| | G700 | 1023 | 1.0 | yes | – | smooth scrolling, side scrolling|
| G700s | 102A | 1.0 | yes | - | smooth scrolling, side scrolling| | G700s | 102A | 1.0 | yes | – | smooth scrolling, side scrolling|
| V450 Nano | 1011 | 1.0 | yes | - | smooth scrolling | | V450 Nano | 1011 | 1.0 | yes | – | smooth scrolling |
| V550 Nano | 1013 | 1.0 | yes | - | smooth scrolling, side scrolling| | V550 Nano | 1013 | 1.0 | yes | – | smooth scrolling, side scrolling|
| VX Nano | 100B | 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| | VX Nano | 100F | 1.0 | yes | – | smooth scrolling, side scrolling|
| M175 | 4008 | | yes | | | | M175 | 4008 | | yes | | |
| M185 (old) | 4038 | 2.0 | yes | R/W | smooth scrolling (note) | | M185 (old) | 4038 | 2.0 | yes | R/W | smooth scrolling (note) |
| M185 (new) | 4054 | 2.0 | no | 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 | | | | M310 | 1024 | 1.0 | yes | | |
| M315 | | | yes | | | | M315 | | | yes | | |
| M330 | | ?.? | yes | ? | smooth scrolling | | 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 * (old): M185 with P/N: 810-003496
* (new): M185 with P/N: 810-005238 or 810-005232
(new): M185 with P/N: 810-005238 or 810-005232 * (note): Currently, smooth scrolling events are not processed in xfce and this
(note): Currently, smooth scrolling events are not processed in xfce and this
setting is useful only to disable smooth scrolling. setting is useful only to disable smooth scrolling.
### Mice (Mini)
### 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):
| Device | WPID | HID++ | Battery | DPI | Other supported features | | Device | WPID | HID++ | Battery | DPI | Other supported features |
|-------------------|------|-------|---------|-------|---------------------------------| |-------------------|------|-------|---------|-------|---------------------------------|
| M570 Trackball | | 1.0 | yes | - | | | MX610 | 1001 | 1.0 | yes | | |
| MX Ergo Trackball | | 2.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 | | Device | WPID | HID++ | Battery | DPI | Other supported features |
|------------------|------|-------|---------|-------|---------------------------------| |------------------|------|-------|---------|-------|---------------------------------|
| Wireless Touch | 4011 | 2.0 | yes | | | | Wireless Touch | 4011 | 2.0 | yes | | |
| T650 Touchpad | 4101 | 2.0 | yes | | smooth scrolling | | 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 | | 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 keyboard | 6500 | 1.0 | yes | |
| EX100 mouse | 3f00 | 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 [solaar]: https://github.com/pwr-Solaar/Solaar
[logitech]: https://www.logitech.com [logitech]: https://www.logitech.com

44
docs/features.md
View File

@ -3,8 +3,11 @@ title: List of HID++ 2.0 features
layout: page layout: page
--- ---
# Feature status # List of HID++ 2.0 features
See functions in hidpp20.py and settings_templates.py
## Feature status
See functions in `hidpp20.py` and `settings_templates.py`
Feature | ID | Status | Notes Feature | ID | Status | Notes
---------------------------------------|----------|:------------------:|------ ---------------------------------------|----------|:------------------:|------
@ -17,7 +20,7 @@ Feature | ID | Status | Notes
`DEVICE_GROUPS` | `0x0006` | :x: | `DEVICE_GROUPS` | `0x0006` | :x: |
`DEVICE_FRIENDLY_NAME` | `0x0007` | :x: | `DEVICE_FRIENDLY_NAME` | `0x0007` | :x: |
`KEEP_ALIVE` | `0x0008` | :x: | `KEEP_ALIVE` | `0x0008` | :x: |
`RESET` | `0x0020` | :x: | aka "Config Change" `RESET` | `0x0020` | :x: | aka “Config Change”
`CRYPTO_ID` | `0x0021` | :x: | `CRYPTO_ID` | `0x0021` | :x: |
`TARGET_SOFTWARE` | `0x0030` | :x: | `TARGET_SOFTWARE` | `0x0030` | :x: |
`WIRELESS_SIGNAL_STRENGTH` | `0x0080` | :x: | `WIRELESS_SIGNAL_STRENGTH` | `0x0080` | :x: |
@ -110,9 +113,9 @@ Feature | ID | Status | Notes
`EQUALIZER` | `0x8310` | :x: | `EQUALIZER` | `0x8310` | :x: |
`HEADSET_OUT` | `0x8320` | :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 Features are implemented as settable features in
lib/logitech_receiver/settings_templates.py 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 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. The label and description should be specified as translatable strings.
``` ```python
_POINTER_SPEED = ('pointer_speed', _("Sensitivity (Pointer Speed)"), _("How fast the pointer moves")) _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 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 (This last is no longer used because keyboards with integrated pointers only
report that they are keyboards.) report that they are keyboards.)
The values to be used need to be determined from documentation of the 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. Windows or MacOS.
``` ```python
def _feature_pointer_speed(): def _feature_pointer_speed():
"""Pointer Speed feature""" """Pointer Speed feature"""
return feature_range(_POINTER_SPEED[0], _F.POINTER_SPEED, 0x002e, 0x01ff, return feature_range(_POINTER_SPEED[0],
read_function_id=0x0, _F.POINTER_SPEED,
write_function_id=0x10, 0x002e,
bytes_count=2, 0x01ff,
label=_POINTER_SPEED[1], description=_POINTER_SPEED[2], read_function_id=0x0,
device_kind=(_DK.mouse, _DK.trackball)) 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 that are toggles or choices work very similarly.
Settings where the choices are determined from the device 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. See `_feature_adjustable_dpi_choices` for an example.
Add an element to _SETTINGS_TABLE with 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. 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 This table is used to generate the data structures for describing devices in descriptors.py
and is also used to auto-discover feature implementations. and is also used to auto-discover feature implementations.
```
```python
_S( _POINTER_SPEED[0], _F.POINTER_SPEED, _feature_pointer_speed ), _S( _POINTER_SPEED[0], _F.POINTER_SPEED, _feature_pointer_speed ),
``` ```

14
docs/i18n.md
View File

@ -1,3 +1,8 @@
---
title: Translating Solaar
layout: page
---
# Translating Solaar # Translating Solaar
First, make sure you have installed the `gettext` package. First, make sure you have installed the `gettext` package.
@ -12,8 +17,8 @@ the source root):
2. Run `./tools/po-update.sh <language>`; it will create/update the file 2. Run `./tools/po-update.sh <language>`; it will create/update the file
`./po/<language>.po`. `./po/<language>.po`.
3. Edit `./po/<language>.po` with your favourite editor (just make sure it saves 3. Edit `./po/<language>.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 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 the translation (msgstr); if you leave msgstr empty, the string will remain
untranslated. untranslated.
@ -22,7 +27,7 @@ the source root):
4. Run `./tools/po-compile.sh`. It will bring up-to-date all the compiled 4. Run `./tools/po-compile.sh`. It will bring up-to-date all the compiled
language files, necessary at runtime. 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 from your environment; to start it in another language, run
`LANGUAGE=<language> ./bin/solaar`. `LANGUAGE=<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 format and sort the translation file, and ensure a minimal diff when updating
a translation. a translation.
## Supported languages
# Supported languages
Currently Solaar has been translated in the following languages: Currently Solaar has been translated in the following languages:

86
docs/index.md
View File

@ -3,41 +3,41 @@ title: Solaar
layout: default layout: default
--- ---
**Solaar** is a Linux manager for Logitech's devices that connect via a USB **Solaar** is a Linux manager for Logitech's devices that connect via USB
[Unifying][unifying], Lightspeed, or Nano receiver. [Unifying][unifying], Lightspeed, or Nano receivers.
Solaar does not work with Logitech peripherals that It does not work with Logitech peripherals that
use Bluetooth or peripherals from other companies. use Bluetooth or peripherals from other companies.
Solaar can be used as a GUI application or via its command-line interface. 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 devices paired to a receiver and
show information about each device, including battery status for devices that support this feature. 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. 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. The program can be invoked in several ways
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 - `--window=show` (the default) starts with its main window visible
system tray and also starts with its main window showing. - `--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, For more information on Solaar's command-line interface use the help option,
as in `solaar --help`. as in `solaar --help`.
Solaar is able to pair and unpair devices with Solaar is able to pair and unpair devices with
receivers as supported by the receiver. Solaar can also control receivers as supported by the receiver. Solaar can also control
some of the changeable features of devices, such as smooth scrolling or some changeable features of devices, such as smooth scrolling or
function key behavior. function key behavior. For more information on how to use Solaar see
For more information on how to use Solaar see [the usage page](usage), and for more information on the capabilities see
[docs/usage.md](https://pwr-solaar.github.io/Solaar/usage). [the capabilities page](capabilities).
For more information on the capabilities of Solaar see
[docs/capabilities.md](https://pwr-solaar.github.io/Solaar/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 to fix problems that arise from incorrect handling of mouse movements or keycodes
by Linux drivers or other software. by Linux drivers or other software.
Solaar has progressed past version 1.0. Problems with earlier versions should 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 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). 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. 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. an incorrect behavior generalization.
Please report such experiences by creating an issue in Please report such experiences by creating an issue in
[the Solaar repository](https://github.com/pwr-Solaar/Solaar/issues). [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 ## 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. 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. with any Unifying receiver and can pair and unpair devices with Lightspeed receivers.
Solaar can pair some Logitech Solaar can pair some Logitech devices with Logitech Nano receivers but not all Logitech
devices with Logitech Nano receivers but not all Logitech devices can be devices can be paired with Nano receivers. Logitech devices without a Unifying logo
paired with Nano receivers. Logitech devices without a Unifying logo
generally cannot be paired with Unifying receivers. generally cannot be paired with Unifying receivers.
For some devices, extra settings (usually not available through the standard For some devices, extra settings (usually not available through the standard
Linux system configuration) are supported. For a list of supported devices 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 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 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 available from the standard repositories for your distribution you can try
one of these packages. one of these packages.
* Arch solaar package in the [community repository][arch] - Arch solaar package in the [community repository][arch]
* Debian 7 (Wheezy) or higher: packages in this [repository](https://pwr-solaar.github.io/Solaar/debian) - 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 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 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] - Ubuntu/Kubuntu git build packages: use the [Solaar git ppa][ppa1], courtesy of [gogo][ppa4]
* a [Fedora package][fedora], courtesy of Eric Smith - a [Fedora package][fedora], courtesy of Eric Smith
* a [Gentoo package][gentoo], courtesy of Carlos Silva and Tim Harder - a [Gentoo package][gentoo], courtesy of Carlos Silva and Tim Harder
* a [Mageia package][mageia], courtesy of David Geiger - a [Mageia package][mageia], courtesy of David Geiger
* an [OpenSUSE rpm][opensuse], courtesy of Mathias Homann - 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. 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 ## 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 ## Known Issues
- The icon in the system tray can show up as 'black on black' in dark - 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 distributions. This is due to problems in many system tray
implementations. Changing to a different theme may help. implementations. Changing to a different theme may help.
- If some icons appear broken in the application, make sure you've properly - If some icons appear broken in the application, make sure you've properly
configured the Gtk theme and icon theme in your control panel. 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 application is also running *may* occasionally cause either of them to become
confused about the state of the devices. confused about the state of the devices.
## License ## License
This software is distributed under the terms of the This software is distributed under the terms of the
[GNU Public License, v2](COPYING). [GNU Public License, v2](COPYING).
## Thanks ## Thanks
This project began as a third-hand clone of [Noah K. Tilton](https://github.com/noah)'s 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) - [Nestor Lopez Casado](http://drive.google.com/folderview?id=0BxbRzx7vEV7eWmgwazJ3NUFfQ28)
provided some more Logitech specifications for the HID++ protocol 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. application testing and supporting new devices.

26
docs/installation.md
View File

@ -5,21 +5,19 @@ layout: page
# Manual installation # Manual installation
## Downloading ## 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 Solaar
## Requirements for running Solaar
Installing Solaar from a repository should have set up all these requirements Installing Solaar from a repository should have set up all these requirements
so in this situation you should be able to skip this section. 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), 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` with kernel modules `hid-logitech-dj`
and `hid-logitech-hidpp` loaded. Also, the `udev` package must be installed 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 its daemon running. If you have a recent Linux distribution, you are
most likely good to go. most likely good to go.
Solaar requires Python 3.6+ Solaar requires Python 3.6+
@ -28,7 +26,7 @@ To run the GUI, solaar also requires Gtk3, and its GObject
introspection bindings. introspection bindings.
The Debian/Ubuntu packages that need to be installed are The Debian/Ubuntu packages that need to be installed are
`python3-gi` and `gir1.2-gtk-3.0`; `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 if you're using another
distribution the required packages are most likely named something similar. 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., available, you can also use `gir1.2-appindicator3-0.1` if necessary (e.g.,
for Unity in Ubuntu). for Unity in Ubuntu).
### Installing Solaar's udev rule
### Installing Solaar's udev Rule
Solaar needs to write to the receiver's HID device. Solaar needs to write to the receiver's HID device.
To be able to do this without running as root requires a udev rule 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 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 you have a receiver that is not in the installed rule.
## Running from the Download Directories ## Running from the Download Directories
If Solaar's udev rule is installed, If Solaar's udev rule is installed,
you can just go to the solaar directory and run `bin/solaar` for the GUI you can just go to the solaar directory and run `bin/solaar` for the GUI
or `bin/solaar <command> <arguments>` for the CLI. or `bin/solaar <command> <arguments>` 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 `sudo bin/solaar` for the GUI
or `sudo bin/solaar <command> <arguments>` for the CLI. or `sudo bin/solaar <command> <arguments>` 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 ## 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 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 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. `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.) (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. 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) [pip]: https://en.wikipedia.org/wiki/Pip_(package_manager)
## Solaar in other languages ## Solaar in other languages
If you want to have Solaar's user messages in some other language you need to run 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 `tools/po-compile.sh` to create the translation files before running or installing Solaar
and set the LANGUAGE environment variable appropriately when running Solaar. and set the LANGUAGE environment variable appropriately when running Solaar.
## Running Solaar at Startup ## Running Solaar at Startup
Distributions can cause Solaar can be run automatically at user login by installing a desktop file at 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. 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 ## Installing from PyPI
As an alternative to downloading and installing you can install the most recent release As an alternative to downloading and installing you can install the most recent release

63
docs/usage.md
View File

@ -5,23 +5,22 @@ layout: page
# Solaar usage # 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 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 with the lowest known battery level. If there are no battery information,
show the icon is one of the Solaar icons. 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 Solaar also has a main window. When it is invisible,
click on the icon in the system tray to bring up the Solaar menu and then 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.
Here is an image of the Solaar menu and the Solaar icon (here the battery The following is an image of the Solaar menu and the icon (the battery
symbol in the system tray at the left of the image ). The Solaar icon can 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. also be other battery icons or versions of the Logitech Unifying icon.
![Solaar-menu](Solaar-menu.png) ![Solaar-menu](Solaar-menu.png)
Clicking on "Quit" in the Solaar menu terminates Solaar. Clicking on “Quit” in the Solaar menu terminates the program, and “About Solaar” pops up a window with further information.
Clicking on "About Solaar" pops up a window with information on Solaar.
## Solaar options ## 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. 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). Closing the main window does not terminate Solaar (unless Solaar is not using the system tray).
Clicking on "Quit Solaar" terminates Solaar. Clicking on “Quit Solaar” terminates the program, and “About Solaar” pops up a window with further information.
Clicking on "About Solaar" pops up a window with information on Solaar. The light bulb (or a similar icon) displays detailed information
Clicking on the lightbulb (or similar icon) displays detailed information about the selected receiver or device (useful for debugging).
about the selected receiver or device (mostly only useful for debugging).
### Pairing and unpairing devices ### Pairing and unpairing devices
When a receiver is selected in the main window you can pair a new device by When a receiver is selected in the main window, you can pair a new device by
clicking on the "Pair new device" button. clicking on the “Pair new device” button.
Then turn on the device and it should pair with the receiver if that is possible. 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) ![Solaar-main-window-receiver](Solaar-main-window-receiver.png)
Some receivers can only pair with certain kinds of devices. Some receivers 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. 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.
Some receivers can only pair a limited number of times.
A receiver with the Unifying logo should be able to pair with any device 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 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 not be able to pair a new device. In this case to pair a new device you
first need to unpair a device. first need to unpair a device.
When a device is selected you can unpair the device if your receiver supports 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. confirm in the window that pops up.
### Viewing and changing device settings ### 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 device, if that is reported by the device, and the status of the link
between the device and its receiver. between the device and its receiver.
You can also see some settings of the device and change 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. moving sliders.
![Solaar-main-window-keyboard](Solaar-main-window-keyboard.png) ![Solaar-main-window-keyboard](Solaar-main-window-keyboard.png)
![Solaar-main-window-mouse](Solaar-main-window-mouse.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. but it still can be unpaired if its receiver allows unpairing.
![Solaar-main-window-offline](Solaar-main-window-offline.png) ![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 #### Remapping key and button actions
For many devices Solaar can remap some of their keys or buttons to For many devices Solaar can remap some of their keys or buttons to
perform a different action. (This actually changes the information that the perform a different action. (This changes the information that the
device sends when the key or button is activated.) Only some keys on some 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 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 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 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 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, 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 Solaar will remember past action settings and restore them on the device
from then on. from then on.
![Solaar-main-window-actions](Solaar-main-window-button-actions.png) ![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 way to do a mouse left click, so exercise caution when remapping keys or
buttons that are needed to operate your system. 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 Solaar main window. For more information on the Solaar done using the main window. For more information on the
command line interface, run `solaar --help` to see the Solaar commands and command line interface, run `solaar --help` to see the commands and
then `solaar <command> --help` to see the arguments to any of the commands. then `solaar <command> --help` to see the arguments to any of the commands.