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

docs: update for USB and Bluetooth

This commit is contained in:
Peter F. Patel-Schneider 2020-09-23 23:14:20 -04:00
parent 84e0e74709
commit 3effccf390
6 changed files with 118 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
docs/capabilities.md
View File

@ -8,16 +8,22 @@ layout: page
[**Solaar**][solaar] reports on and controls [Logitech][logitech] devices
(keyboards, mice, and trackballs) that connect to your computer via a
Logitech USB receiver (a very small piece of hardware that plugs into one of
your USB ports) and communicate with the receiver using Logitech's HID++
protocol. It is designed to detect all devices paired with your
your USB ports)
It is designed to detect all devices paired with your
receivers, and at the very least display some basic information about them.
At this moment, all [Unifying][unifying] receivers are supported (devices
with USB ID `046d:c52b` or `046d:c532`) as are several Lightspeed Receivers
and a dozen Nano receivers.
Solaar also reports on and controls some Logitech devices that connect to your
computer using a USB cable or via Bluetooth.
At this moment only a few devices types that connect via a USB cable or Bluetooth
are supported in Solaar as information needs to be added to Solaar for each device type.
## HID++
The devices that Solaar handles use Logitech's HID++ protocol.
HID++ is a Logitech-proprietary protocol that extends the standard HID
protocol for interfacing with keyboards, mice, and so on. It allows
Logitech receivers to communicate with multiple devices and modify some
@ -36,10 +42,12 @@ Contrariwise, two different devices may appear different physically but
actually look the same to software. (For example, some M185 mice look the
same to software as some M310 mice.)
The software identity of a receiver can be determined by its USB id
The software identity of a receiver can be determined by its USB product ID
(reported by Solaar and also viewable in Linux using `lsusb`). The software
identity of a device can be determined by its Wireless PID as reported by
Solaar.
identity of a device that connects to a receiver can be determined by
its Wireless PID as reported by Solaar. The software identity of devices that
connect via a USB cable or via bluetooth can be determined by their USB or
Bluetooth product ID.
Even something as fundamental as pairing works differently for different
receivers. For Unifying receivers, pairing adds a new paired device, but
@ -64,7 +72,7 @@ that they were bought with.
Solaar uses the HID++ protocol to pair devices to receivers and unpair
devices from receivers, and also uses the HID++ protocol to display
features of receivers and devices. Currently it only displays some
features, but can modify even fewer. For more information on HID++ features
features, and can modify even fewer. For a list of HID++ features
and their support see [the features page](features).
Solaar does not do anything beyond using the HID++ protocol to change the
@ -82,7 +90,7 @@ WARNING: Updating firmware can cause a piece of hardware to become
permanently non-functional if something goes wrong with the update or the
update installs the wrong firmware.
Solaar does keep track of some changeable state of a device between
Solaar does keep track of some changeable settings of a device between
invocations. When it starts, it restores on-line devices to their
previously-known state, and while running it restores devices to
their previously-known state when the device itself comes on line.

13
docs/devices.md
View File

@ -5,9 +5,10 @@ layout: page
# Supported devices and receivers
These tables list Logitech receivers and devices and to what degree their
These tables provide a partial list of supported Logitech receivers and
devices and to what degree their
features are supported by Solaar. The information in these tables is
incomplete, based on what devices users have been able to test Solaar with.
based on what devices users have been able to test Solaar with.
The HID++ column specifies the device's HID++ version. Some devices report
version 4.5, but that is the same as version 2.0 as listed here.
@ -40,11 +41,15 @@ arguments to the _D function are the device's long name, its short name
(codename), its HID++ protocol version, its wireless product ID (wpid), and
a tuple of known feature settings (from `lib/logitech/settings_templates.py`).
If a device connects via a USB cable or via Bluetooth its USB or Bluetooth product ID
has to be added in `lib/logitech/descriptors.py`.
### Receivers
| USB ID | Kind | Max Paired Devices |
------------|------------|--------------------|
| 046d:c517 | 27MHz old | 2-4? |
| 046d:c517 | 27MHz old | 4 |
| 046d:c518 | Nano | 1 |
| 046d:c51a | Nano | 1 |
| 046d:c51b | Nano | 1 |
@ -214,7 +219,7 @@ setting is useful only to disable smooth scrolling.
| EX100 keyboard | 0065 | 1.0 | yes | |
| EX100 mouse | 003f | 1.0 | yes | |
* The EX100 is old, preunifying set, supporting only part of HID++ 1.0 features
* The EX100 is an old, preunifying receiver and device set, supporting only part of HID++ 1.0 features
[solaar]: https://github.com/pwr-Solaar/Solaar
[logitech]: https://www.logitech.com

8
docs/features.md
View File

@ -36,7 +36,7 @@ Feature | ID | Status | Notes
`DEVICE_RESET` | `0x1802` | :x: |
`OOBSTATE` | `0x1805` | :x: |
`CONFIG_DEVICE_PROPS` | `0x1806` | :x: |
`CHANGE_HOST` | `0x1814` | :wrench: |
`CHANGE_HOST` | `0x1814` | :heavy_check_mark: |
`HOSTS_INFO` | `0x1815` | :heavy_plus_sign: | `get_host_names`, partial listing only
`BACKLIGHT` | `0x1981` | :x: |
`BACKLIGHT2` | `0x1982` | :heavy_check_mark: | `_feature_backlight2`
@ -50,7 +50,7 @@ Feature | ID | Status | Notes
`REPROG_CONTROLS_V4` | `0x1B04` | :heavy_plus_sign: | `get_keys`, _feature_reprogrammable_keys
`REPORT_HID_USAGE` | `0x1BC0` | :x: |
`PERSISTENT_REMAPPABLE_ACTION` | `0x1C00` | :wrench: |
`WIRELESS_DEVICE_STATUS` | `0x1D4B` | :x: | status reporting from device
`WIRELESS_DEVICE_STATUS` | `0x1D4B` | :heavy_plus_sign: | status reporting from device
`REMAINING_PAIRING` | `0x1DF0` | :x: |
`FIRMWARE_PROPERTIES` | `0x1F1F` | :x: |
`ADC_MEASUREMENT` | `0x1F20` | :x: |
@ -93,7 +93,7 @@ Feature | ID | Status | Notes
`TOUCHMOUSE_RAW_POINTS` | `0x6110` | :x: |
`TOUCHMOUSE_6120` | `0x6120` | :x: |
`GESTURE` | `0x6500` | :x: |
`GESTURE_2` | `0x6501` | :wrench: | `_feature_gesture2_gestures`, `_feature_gesture2_params`
`GESTURE_2` | `0x6501` | :heavy_plus_sign: | `_feature_gesture2_gestures`, `_feature_gesture2_params`
`GKEY` | `0x8010` | :x: |
`MKEYS` | `0x8020` | :x: |
`MR` | `0x8030` | :x: |
@ -104,7 +104,7 @@ Feature | ID | Status | Notes
`PER_KEY_LIGHTING` | `0x8080` | :x: |
`PER_KEY_LIGHTING_V2` | `0x8081` | :x: |
`MODE_STATUS` | `0x8090` | :x: |
`ONBOARD_PROFILES` | `0x8100` | :x: |
`ONBOARD_PROFILES` | `0x8100` | :x: | in progress
`MOUSE_BUTTON_SPY` | `0x8110` | :x: |
`LATENCY_MONITORING` | `0x8111` | :x: |
`GAMING_ATTACHMENTS` | `0x8120` | :x: |

62
docs/index.md
View File

@ -3,33 +3,34 @@ title: Solaar
layout: default
---
**Solaar** is a Linux manager for Logitech's devices that connect via USB
[Unifying][unifying], Lightspeed, or Nano receivers.
It does not work with Logitech peripherals that
use Bluetooth or peripherals from other companies.
**Solaar** is a Linux manager for many Logitech keyboards, mice, and trackpads
that connect wirelessly to a USB [Unifying][unifying], Lightspeed, or Nano receiver,
connect directly via a USB cable, or connect via Bluetooth.
Solaar does not work with peripherals from other companies.
Solaar can be used as a GUI application or via its command-line interface.
Both interfaces are able to list the devices paired to a receiver and
show information about each device, including battery status for devices that support this feature.
Solaar's GUI normally uses an icon in the system tray and starts with its main window hidden.
The program can be invoked in several ways
Both interfaces are able to list the connected devices and
show information about each device, often including battery status.
Solaar is able to pair and unpair devices with
receivers as supported by the device and receiver.
Solaar can also control some changeable features of devices,
such as smooth scrolling or function key behavior.
For more information on how to use Solaar see
[the usage page](https://pwr-solaar.github.io/Solaar/usage),
and for more information on its capabilities see
[the capabilities page](https://pwr-solaar.github.io/Solaar/capabilities).
- `--window=show` (the default) starts with its main window visible
- `--window=hide` starts with its main window hidden
- `--window=only` do not use the system tray, but start with main window visible
Solaar's GUI normally uses an icon in the system tray and starts with its main window visible.
The GUI can be started in several ways
- `--window=show` (the default) starts with its main window visible,
- `--window=hide` starts with its main window hidden,
- `--window=only` do not use the system tray, and start with main window visible.
For more information on Solaar's command-line interface use the help option,
as in `solaar --help`.
Solaar is able to pair and unpair devices with
receivers as supported by the receiver. Solaar can also control
some changeable features of devices, such as smooth scrolling or
function key behavior. For more information on how to use Solaar see
[the usage page](https://pwr-solaar.github.io/Solaar/usage),
and for more information on the capabilities see
[the capabilities page](https://pwr-solaar.github.io/Solaar/capabilities).
Solaar does not process normal input from the devices. It is thus unable
Solaar does not process normal input from devices. It is thus unable
to fix problems that arise from incorrect handling of mouse movements or keycodes
by Linux drivers or other software.
@ -45,18 +46,26 @@ Please report such experiences by creating an issue in
[unifying]: https://en.wikipedia.org/wiki/Logitech_Unifying_receiver
## Supported Devices
Solaar will detect all devices paired with your Unifying, Lightspeed, or Nano
receiver, and at the very least display some basic information about them.
It can pair and unpair a Logitech device showing the Unifying logo (Solaar's version of the [logo][logo])
with any Unifying receiver and can pair and unpair devices with Lightspeed receivers.
Solaar will detect some Logitech devices that connect via a USB cable or Bluetooth.
Solaar can pair and unpair a Logitech device showing the Unifying logo
(Solaar's version of the [logo][logo])
with any Unifying receiver and
can pair and unpair Lightspeed devices with Lightspeed receivers for the same model.
Solaar can pair some Logitech devices with Logitech Nano receivers but not all Logitech
devices can be paired with Nano receivers. Logitech devices without a Unifying logo
devices can be paired with Nano receivers.
Logitech devices without a Unifying logo
generally cannot be paired with Unifying receivers.
For some devices, extra settings (usually not available through the standard
Linux system configuration) are supported. For a list of supported devices
Solaar does not handle connecting or disconnecting via Bluetooth,
which is done using the usual Bluetooth mechanisms.
For a partial list of supported devices
and their features, see [the devices page](https://pwr-solaar.github.io/Solaar/devices).
[logo]: assets/solaar.svg
@ -105,6 +114,9 @@ for the step-by-step procedure for manual installation.
distributions. This is due to problems in many system tray
implementations. Changing to a different theme may help.
- Sometimes the system tray icon does not show up. The cause of this is unknown.
Either wait a while and try again or try with the `--window=hide` option.
- If some icons appear broken in the application, make sure you've properly
configured the Gtk theme and icon theme in your control panel.

18
docs/installation.md
View File

@ -22,7 +22,7 @@ most likely good to go.
Solaar requires Python 3.6+
and the `python3-pyudev` package.
To run the GUI, solaar also requires Gtk3, and its GObject
To run the GUI Solaar also requires Gtk3, and its GObject
introspection bindings.
The Debian/Ubuntu packages that need to be installed are
`python3-gi` and `gir1.2-gtk-3.0`;
@ -30,9 +30,9 @@ in Fedora you need `gtk3` and `python3-gobject`;
if you're using another
distribution the required packages are most likely named something similar.
If the desktop notifications bindings are also installed
If desktop notifications bindings are also installed
(`gir1.2-notify-0.7` for Debian/Ubuntu),
you will also get desktop notifications when devices come online/go offline.
you will also see desktop notifications when devices come online/go offline.
For GNOME Shell/Budgie Desktop/KDE/XFCE support, you also need to have
`gir1.2-ayatanaappindicator3-0.1` installed in Debian/Ubuntu. Although it is
recommended to install and use `gir1.2-ayatanaappindicator3-0.1` if it is
@ -48,14 +48,16 @@ that gives seated users write access to the HID devices for Logitech receiver an
You can install this rule by copying, as root,
`rules.d/42-logitech-unify-permissions.rules` from Solaar to
`/etc/udev/rules.d`.
The udev daemon will automatically pick up this file using inotify.
You will probably also have to tell udev to reload its rule via
`sudo udevadm control --reload-rules`.
For this rule to set up the correct permissions for your receiver
you will then need to either physically remove the receiver and
re-insert it or reboot your computer.
For this rule to set up the correct permissions for your receivers and devices
you will then need to either disconnect your receivers and
any USB-connected or Bluetooth-connected devices and
re-connect them or reboot your computer.
You only need to install Solaar's udev rule if it is not already installed
on your system or you have a receiver that is not in the installed rule.
on your system or the rule has changed.
## Running from the Download Directories

46
docs/usage.md
View File

@ -7,12 +7,13 @@ layout: page
Under normal usage Solaar creates an icon in your system tray. This icon is
usually a battery icon showing the approximate battery level for your device
with the lowest known battery level. If there are no battery information,
with the lowest known battery level. If there are no devices with battery information,
then the icon is one of the Solaar icons.
Solaar also has a main window. When it is invisible,
Solaar also has a main window. When the main window is invisible,
click on the icon in the system tray to bring up the menu, and then
click on a receiver or device in the menu.
click on a receiver or device in the menu to see information about
that receiver or device.
The following is an image of the Solaar menu and the icon (the battery
symbol is in the system tray at the left of the image). The icon can
@ -49,11 +50,14 @@ about the selected receiver or device (useful for debugging).
When a receiver is selected in the main window, you can pair a new device by
clicking on the “Pair new device” button.
Then turn on the device and it should pair with the receiver if that is possible.
For multi-host devices first select the host position that you want.
Some Lightspeed devices may pair by pressing a special pairing button.
![Solaar-main-window-receiver](Solaar-main-window-receiver.png)
Some receivers can only pair with certain kinds of devices, other receivers
pair a new device by replacing an existing paired device of the same kind, and even other receivers can only pair a limited number of times.
pair a new device by replacing an existing paired device of the same kind,
and even other receivers can only pair a limited number of times.
A receiver with the Unifying logo should be able to pair with any device
with the Unifying logo. If there are no open pairing slots, however, you may
not be able to pair a new device. In this case to pair a new device you
@ -110,3 +114,37 @@ Solaar also has a command line interface that can do most of what can be
done using the main window. For more information on the
command line interface, run `solaar --help` to see the commands and
then `solaar <command> --help` to see the arguments to any of the commands.
## Solaar settings
Solaar supports the following settings:
Setting | Description
---------------------------------|------------
Hand Detection | Turn on backlight when your hands hover over the keyboard
Scroll Wheel Smooth Scrolling | Higher-speed vertical scrolling
Side Scrolling | When off, side scrolling sends custom button events
Scroll Wheel High Resolution | Higher-speed vertical scrolling
Scroll Wheel HID++ Scrolling | When on, vertical scrolling uses HID++ events
Scroll Wheel Direction | Reverse direction of vertical scrolling
Scroll Wheel Resolution | Higher-speed vertical scrolling
Scroll Wheel Rachet | Shift wheel ratchet on and off based on wheel speed
Thumb Wheel HID++ Scrolling | When on, thumb-wheel scrolling uses HID++ events
Thumb Wheel Direction | Reverse direction of thumb-wheel scrolling
Sensitivity (DPI) | Mouse movement sensitivity
Sensitivity (Pointer Speed) | Mouse movement sensitivity
Backlight | Turn on backlight
Swap Fx function | Change Fn keys to normally do their special action
Key/Button Actions | Change what a key or button does
Disable keys | Disable one or more keys
Set OS | Change keys to match OS
Change Host | Connect to a different host
Gestures | Turn on and off various (mostly touchpad) gestures
Gesture params | Modify parameters for gestures
HID++ events are mostly not processed by Linux input drivers.
Settings that involve sending HID++ events exist so that they can be
turned off under Linux.
Different Logitech devices may implement the same functionality in different ways,
thus the different settings that do the same thing.