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
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/)

80
docs/capabilities.md
View File

@ -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

2
docs/debian.md
View File

@ -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`

128
docs/devices.md
View File

@ -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

44
docs/features.md
View File

@ -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 ),
```

14
docs/i18n.md
View File

@ -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 <language>`; it will create/update the file
`./po/<language>.po`.
3. Edit `./po/<language>.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/<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 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=<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:

86
docs/index.md
View File

@ -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.

26
docs/installation.md
View File

@ -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 <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
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
@ -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

63
docs/usage.md
View File

@ -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 <command> --help` to see the arguments to any of the commands.