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

doc: better documentation: devices and capabilities

This commit is contained in:
Peter F. Patel-Schneider 2020-01-13 19:07:10 -05:00 committed by Filipe Laíns
parent bd26b9340d
commit 0a735a32ed
3 changed files with 181 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/capabilities.md Normal file
View File

@ -0,0 +1,36 @@
---
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 receivers, and at the very least display some basic information about them.
At this moment, all [Unifying][unifying] receivers are supported (devices with
USB ID `046d:c52b` or `046d:c532`) as are several Lightspeed Receivers, but only some newer Nano receivers (devices with USB ID `046d:c52f`, and `046d:c534`) are supported. Note that Linux incorrectly states that some Nano receivers are Unifying receivers.
## HID++
HID++ is a Logitech-proprietary protocol that extends the standard HID protocol for interfacing with keyboards, mice, and so on. HID++ 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++ 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 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 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 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 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 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 receiver with USB ID `046d:c532`, 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, 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 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 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.
Solaar does not do anything beyond using the HID++ protocol to change the behavior of receivers and devices. In particular, Solaar 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 drivers and other software (such as X11). Solaar also does not keep track of the state of a device between invocations and thus cannot restore a device to a previously-known state when Solaar is restarted.
Querying a device for its current state can require quite a few HID++ interactions. These interactions can 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.
[solaar]: https://github.com/pwr-Solaar/Solaar
[logitech]: https://www.logitech.com
[unifying]: https://en.wikipedia.org/wiki/Logitech_Unifying_receiver

266
docs/devices.md
View File

@ -3,47 +3,9 @@ title: Supported Devices
layout: page
---
# Supported devices
# Supported devices and receivers
**Solaar** will detect all devices paired with your receiver, and at the very
least display some basic information about them.
At this moment, all [Unifying][unifying] receivers are supported (devices with
USB ID `046d:c52b` or `046d:c532`), but only some newer Nano receivers (devices
with USB ID `046d:c52f`, `046d:c52b`, and `046d:c534`). Note that Linux incorrectly states that
some Nano receivers are Unifying receivers.
For some devices, extra settings (usually not available through the standard
Linux system configuration) are supported:
* The [K750 Solar Keyboard][K750] is also queried for its solar charge status.
Pressing the `Light-Check` button on the keyboard will pop-up the application
window and display the current lighting value (Lux) as reported by the
keyboard, similar to Logitech's *Solar.app* for Windows.
* The state of the `FN` key can be toggled on some keyboards ([K360][K360],
[MK700][K700], [K750][K750], [K800][K800] and [K830][K830]). It 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.
* The DPI can be changed on the [Performance MX Mouse][P_MX].
* Smooth scrolling (higher sensitivity on vertical scrolling with the wheel) can
be toggled on the [M705 Marathon Mouse][M705], [M510 Wireless Mouse][M510],
[M325][M325] and [G700s][G700s].
# Supported features
These tables list all known Logitech [Unifying][unifying] devices, and to what
degree their features are supported by Solaar. If your device is not listed here
at all, it is very unlikely Solaar would be able to support it.
The information in these tables is incomplete, based on what devices myself and
other users have been able to test Solaar with. If your device works with
Solaar, but its supported features are not specified here, I would love to hear
about it.
These tables list Logitech receivers and devices and to what degree their features are supported by Solaar. The information in these tables is incomplete, based on what devices users have been able to test Solaar with. If your device works with Solaar, but its supported features are not specified here, please open an issue on the [Solaar github repository][solaar] with the pleasant news.
The HID++ column specifies the device's HID++ version.
@ -55,79 +17,108 @@ 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`).
The reprog(rammable) keys feature is currently not fully supported by Solaar.
You are able to read this feature using solaar-cli, but it is not possible to
assign different keys.
You are able to read this feature using command-line interface of Solaar, but it is not possible to assign different keys.
Keyboards (Unifying):
### Receivers:
| Device | HID++ | Battery | Other supported features |
|------------------|-------|---------|-----------------------------------------|
| K230 | 2.0 | yes | |
| K270 | 1.0 | yes | |
| K270 | 2.0 | yes | reprog keys |
| K340 | 1.0 | yes | |
| K350 | 1.0 | yes | |
| K360 | 2.0 | yes | FN swap, reprog keys |
| K400 Touch | 2.0 | yes | FN swap |
| K400 Plus | 2.0 | | FN swap |
| K750 Solar | 2.0 | yes | FN swap, Lux reading, light button |
| K780 | 4.5 | yes | FN swap |
| K800 Illuminated | 1.0 | yes | FN swap, reprog keys |
| K800 [new ver] | 4.5 | yes | FN swap |
| K830 Illuminated | 2.0 | yes | FN swap |
| TK820 | 2.0 | yes | FN swap |
| MK700 | 1.0 | yes | FN swap, reprog keys |
[new ver]: New version of K800 keyboard, with HID++ 4.5 and WPID 0x406E
| USB ID | Kind | Max Paired Devices |
------------|------------|--------------------|
| 046d:c52b | Unifying | 6 |
| 046d:c52f | Nano | 2(?) |
| 046d:c532 | Unifying | 6 |
| 064d:c534 | Nano(?) | 2 |
| 064d:c539 | Lightspeed | 6 |
| 064d:c53a | Lightspeed | 6 |
| 064d:c53f | Lightspeed | 6 |
Mice (Unifying):
### Keyboards (Unifying):
| Device | HID++ | Battery | DPI | Other supported features |
|------------------|-------|---------|-------|---------------------------------|
| M317 | | | | |
| M325 | 2.0 | yes | 1000 | smooth scrolling |
| M345 | 2.0 | yes | - | smooth scrolling |
| M350 | 1.0 | yes | | |
| M505 | 1.0 | yes | | smooth scrolling |
| M510 | 1.0 | yes | | smooth scrolling |
| M515 Couch | 2.0 | yes | - | smooth scrolling |
| M525 | 2.0 | yes | - | smooth scrolling |
| M560 | 2.0 | yes | - | smooth scrolling |
| M585 | 4.5 | yes | - | |
| M590 | 4.5 | yes | - | |
| M600 Touch | 2.0 | yes | | |
| M705 Marathon | 1.0 | yes | - | smooth scrolling |
| T400 Zone Touch | 2.0 | yes | | smooth scrolling |
| T620 Touch | 2.0 | yes | | |
| Performance MX | 1.0 | yes | R/W | smooth scrolling |
| Anywhere MX | 1.0 | yes | R/W | smooth scrolling |
| Anywhere MX 2 | 4.5 | yes | R/W | smooth scrolling |
| MX Master | 4.5 | yes | R/W | smart shift |
| Cube | 2.0 | yes | | |
| Device | WPID | HID++ | Battery | Other supported features |
|------------------|------|-------|---------|-----------------------------------------|
| K230 | 400D | 2.0 | yes | |
| K270 | 4003 | 2.0 | yes | |
| K340 | 2007 | 1.0 | yes | |
| K350 | 200A | 1.0 | yes | |
| K360 | 4004 | 2.0 | yes | FN swap, reprog keys |
| K375s | 4071 | | | FN swap |
| K400 Touch | 400E | 2.0 | yes | FN swap |
| K400 Touch | 4024 | 2.0 | yes | FN swap |
| K400 Plus | 404D | 2.0 | | FN swap |
| K520 | 2011 | 1.0 | yes | FN swap |
| K750 Solar | 4002 | 2.0 | yes | FN swap, Lux reading, light button |
| K780 | 405B | 4.5 | yes | FN swap |
| K800 Illuminated | 2010 | 1.0 | yes | FN swap, reprog keys, LEDs |
| K800 (new ver) | 406E | 4.5 | yes | FN swap |
| K830 Illuminated | 4032 | 2.0 | yes | FN swap |
| N545 | 2006 | | yes | |
| TK820 | | 2.0 | yes | FN swap |
| Craft | 4066 | 4.5 | | |
* The [K750 Solar Keyboard][K750] can be queried for its solar charge status.
Pressing the `Light-Check` button on the keyboard will pop-up the application
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.
Mice (Nano):
### Mice (Unifying):
| Device | HID++ | Battery | DPI | Other supported features |
|------------------|-------|---------|-------|---------------------------------|
| G700s | 1.0 | yes | - | smooth scrolling |
| G700 | 1.0 | yes | - | smooth scrolling |
| V450 Nano | 1.0 | yes | - | smooth scrolling |
| V550 Nano | 1.0 | yes | - | smooth scrolling |
| VX Nano | 1.0 | yes | - | smooth scrolling |
| M175 | | yes | | |
| M185 (old) | 4.5 | yes | R/W | smooth scrolling (note) |
| M185 (new) | 4.5 | no | R/W | smooth scrolling (note) |
| M187 | 2.0 | yes | | |
| M215 | 1.0 | yes | | |
| M235 | 4.5 | yes | | |
| M305 | 1.0 | yes | | |
| M310 | 1.0 | yes | | |
| M315 | | yes | | |
| M330 | ?.? | yes | ? | smooth scrolling |
| MX 1100 | 1.0 | yes | - | smooth scrolling, side scrolling|
| Device | WPID | HID++ | Battery | DPI | Other supported features |
|------------------|------|-------|---------|-------|---------------------------------|
| M150 | 4022 | 2.0 | | | |
| M185 | 4055 | 4.5 | | R/W | smooth scrolling |
| M310 | 4031 | 2.0 | yes | | |
| M310 | 4055 | 4.5 | | R/W | smooth scrolling |
| M317 | | | | | |
| M325 | 400A | 2.0 | yes | 1000 | smooth scrolling |
| M345 | 4017 | 2.0 | yes | - | smooth scrolling |
| M350 | 101C | 1.0 | yes | | |
| 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 |
| M585 | 406B | 4.5 | yes | R/W | smooth scrolling |
| M590 | 406B | 4.5 | yes | R/W | smooth scrolling |
| M600 Touch | 401A | 2.0 | yes | | |
| M705 Marathon | 101B | 1.0 | yes | - | smooth scrolling, side scrolling|
| M705 Marathon | 406D | 4.5 | yes | R/W | smooth scrolling |
| 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|
| Anywhere MX | 1017 | 1.0 | yes | R/W | smooth scrolling, side scrolling|
| Anywhere MX 2 | 404A | 4.5 | yes | R/W | smooth scrolling |
| MX Master | 4041 | 4.5 | yes | R/W | smooth scrolling, smart shift |
| MX Master 25 | 4069 | 4.5 | yes | R/W | smooth scrolling, smart shift |
| Cube | | 2.0 | yes | | |
### 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|
| M175 | 4008 | | yes | | |
| M185 (old) | 4038 | 4.5 | yes | R/W | smooth scrolling (note) |
| M185 (new) | 4054 | 4.5 | no | R/W | smooth scrolling (note) |
| M187 | 4019 | 2.0 | yes | | |
| M215 | 1020 | 1.0 | yes | | |
| M235 | 4055 | 4.5 | yes | R/W | smooth scrolling |
| M305 | 101F | 1.0 | yes | | side scrolling |
| M310 | 1024 | 1.0 | yes | | |
| M315 | | | yes | | |
| M330 | | ?.? | yes | ? | smooth scrolling |
| MX 1100 | 1014 | 1.0 | yes | - | smooth scrolling, side scrolling|
(old): M185 with P/N: 810-003496
@ -137,46 +128,55 @@ Mice (Nano):
setting is useful only to disable smooth scrolling.
Mice (Mini):
### Mice (Mini):
| Device | HID++ | Battery | DPI | Other supported features |
|------------------|-------|---------|-------|---------------------------------|
| MX610 | 1.0 | yes | | |
| MX610 lefthanded | 1.0 | yes | | |
| V400 | 1.0 | yes | | |
| V450 | 1.0 | yes | | |
| VX Revolution | 1.0 | yes | | |
| MX Air | 1.0 | yes | | |
| MX Revolution | 1.0 | yes | | |
| 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):
### Trackballs (Unifying):
| Device | HID++ | Battery | DPI | Other supported features |
|-------------------|-------|---------|-------|---------------------------------|
| M570 Trackball | 1.0 | yes | - | |
| MX Ergo Trackball | 4.5 | yes | - | |
| Device | WPID | HID++ | Battery | DPI | Other supported features |
|-------------------|------|-------|---------|-------|---------------------------------|
| M570 Trackball | | 1.0 | yes | - | |
| MX Ergo Trackball | | 4.5 | yes | - | |
Touchpads (Unifying):
### Touchpads (Unifying):
| Device | HID++ | Battery | DPI | Other supported features |
|------------------|-------|---------|-------|---------------------------------|
| Wireless Touch | 2.0 | yes | | |
| T650 Touchpad | 2.0 | yes | | smooth scrolling |
| Device | WPID | HID++ | Battery | DPI | Other supported features |
|------------------|------|-------|---------|-------|---------------------------------|
| Wireless Touch | 4011 | 2.0 | yes | | |
| T650 Touchpad | 4101 | 2.0 | yes | | smooth scrolling |
Mouse-Keyboard combos:
### Mice and Keyboards sold as combos:
| Device | HID++ | Battery | Other supported features |
|------------------|-------|---------|-----------------------------------------|
| MK220 | 2.0 | yes | |
| MK270 | 2.0 | yes | reprog keys |
| MK330 | | | |
| MK520 | M2/K1 | yes | FN swap, reprog keys |
| MK550 | | | |
| MK710 | 1.0 | yes | FN swap, reprog keys |
| Device | WPID | HID++ | Battery | Other supported features |
|------------------|------|-------|---------|-----------------------------------------|
| MK220 | | 2.0 | yes | |
| MK270 | 4023 | 2.0 | yes | reprog keys |
| MK320 | 200F | | | |
| MK330 | | | | |
| MK520 | | M2/K1 | yes | FN swap, reprog keys |
| MK550 | | | | |
| MK700 | 2008 | 1.0 | yes | FN swap, reprog keys |
| MK710 | | 1.0 | yes | FN swap, reprog keys |
[solaar]: https://github.com/pwr-Solaar/Solaar
[logitech]: https://www.logitech.com
[unifying]: https://en.wikipedia.org/wiki/Logitech_Unifying_receiver
[G700s]: https://gaming.logitech.com/en-us/product/g700s-rechargeable-wireless-gaming-mouse
[K360]: http://logitech.com/product/keyboard-k360

32
docs/index.md
View File

@ -3,17 +3,18 @@ title: Solaar
layout: default
---
**Solaar** is a Linux device manager for Logitech's [Unifying][unifying], Lightspeed, and
Nano receiver peripherals. It is able to pair/unpair devices with the
receiver and for most devices show battery status. Solaar can also control
**Solaar** is a Linux manager for Logitech's peripherals that connect via a USB [Unifying][unifying], Lightspeed, or Nano receiver . It is able to pair/unpair devices with
receivers and for most devices show battery status. Solaar can also control
some of the changeable features of the devices, such as smooth scrolling or
function key behavior. Solaar 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 are able to list the devices paired to a Unifying Receiver,
Both are able to list the devices paired to a receiver,
show detailed info for each device, and
also pair/unpair supported devices with the receiver.
pair/unpair supported devices with the receiver.
For more information on the capabilities of Solaar see
[docs/capabilities.md](https://pwr-solaar.github.io/Solaar/capabilities).
Solaar does not handle normal input from the peripherals. It is thus unable
to fix problems that arise from incorrect handling of mouse movements or keycodes
@ -21,7 +22,7 @@ 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
the current version.
the current version from [github](https://github.com/pwr-Solaar/Solaar).
[unifying]: https://en.wikipedia.org/wiki/Logitech_Unifying_receiver
@ -29,7 +30,7 @@ the current version.
**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][logo]
Solaar can pair and unpair a Logitech device showing the Unifying logo (Solaar's version of the [logo][logo])
with any Unifying receiver and can pair and unpair devices with Lightspeed receivers.
Solaar can pair some Logitech
devices with Logitech Nano receivers but not all Logitech devices can be
@ -37,7 +38,7 @@ 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 full 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).
[logo]: https://pwr-solaar.github.io/Solaar/assets/solaar.svg
@ -51,7 +52,6 @@ Pre-built packages are available for a few Linux distros.
* Ubuntu/Kubuntu 16.04+: use the `solaar-gnome3` and/or `solaar` package from [universe repository][universe repository]
* Ubuntu/Kubuntu stable packages: use `solaar-gnome3` and/or `solaar` package from [Solaar stable ppa][ppa2]
* Ubuntu/Kubuntu git build packages: use `solaar-gnome3` and/or `solaar` package from [Solaar git ppa][ppa1]
* an [Arch AUR solaar-git package][arch-git], courtesy of Maxime Poulin
* 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
@ -67,7 +67,6 @@ integration with *gnome-shell* or *Unity*, install `solaar-gnome3`.
[ppa1]: https://launchpad.net/~solaar-unifying/+archive/ubuntu/ppa
[ppa]: http://launchpad.net/~daniel.pavel/+archive/solaar
[arch]: https://www.archlinux.org/packages/community/any/solaar/
[arch-git]: https://aur.archlinux.org/packages/solaar-git/
[fedora]: https://apps.fedoraproject.org/packages/solaar
[gentoo]: https://packages.gentoo.org/packages/app-misc/solaar
[mageia]: http://mageia.madb.org/package/show/release/cauldron/application/0/name/solaar
@ -77,8 +76,7 @@ integration with *gnome-shell* or *Unity*, install `solaar-gnome3`.
## Manual installation
See [docs/installation.md](https://pwr-solaar.github.io/Solaar/installation) for the step-by-step
procedure for manual installation.
See [docs/installation.md](https://pwr-solaar.github.io/Solaar/installation) for the step-by-step procedure for manual installation.
## Known Issues
@ -86,15 +84,9 @@ procedure for manual installation.
- KDE/Kubuntu: if some icons appear broken in the application, make sure you've
properly configured the Gtk theme and icon theme in KDE's control panel.
- For details on devices using the Nano receiver see
[docs/devices.md](https://pwr-solaar.github.io/Solaar/devices).
- Running the command-line application (`bin/solaar-cli`) while the GUI
- Running the command-line application while the GUI
application is also running *may* occasionally cause either of them to become
confused about the state of the devices. I haven't encountered this often
enough to be able to be able to diagnose it properly yet.
[nano]: http://support.logitech.com/en_us/parts
confused about the state of the devices.
## License