From 9087f4187cb75f2a3f8fbad55be573a9ccf53a27 Mon Sep 17 00:00:00 2001 From: "Peter F. Patel-Schneider" Date: Tue, 24 Dec 2019 07:13:58 -0500 Subject: [PATCH] docs: adjust documentation to new changes --- docs/devices.md | 24 +++++++++++----------- docs/index.md | 46 +++++++++++++++++++++++++++++-------------- docs/installation.md | 47 +++++++++++++++++++++++++++++++++++++------- 3 files changed, 83 insertions(+), 34 deletions(-) diff --git a/docs/devices.md b/docs/devices.md index 239346d0..672d390c 100644 --- a/docs/devices.md +++ b/docs/devices.md @@ -8,10 +8,10 @@ layout: page **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] Receiver are supported (devices with -USB ID `046d:c52b` or `046d:c532`), but only some newer Nano Receiver (devices -with USB ID `046d:c52f` and `046d:c52b`). You can check your connected Logitech -devices by running `lsusb -d 046d:` in a console. +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: @@ -78,7 +78,6 @@ Keyboards (Unifying): | TK820 | 2.0 | yes | FN swap | | MK700 | 1.0 | yes | FN swap, reprog keys | - Mice (Unifying): | Device | HID++ | Battery | DPI | Other supported features | @@ -115,8 +114,8 @@ Mice (Nano): | 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] | +| 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 | | | @@ -126,12 +125,12 @@ Mice (Nano): | M330 | ?.? | yes | ? | smooth scrolling | | MX 1100 | 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 +(new): M185 with P/N: 810-005238 or 810-005232 -[note]: Currently, smooth scrolling events does not processed in xfce and this -setting useful only for disable smooth scrolling +(note): Currently, smooth scrolling events are not processed in xfce and this +setting is useful only to disable smooth scrolling. Mice (Mini): @@ -167,13 +166,14 @@ Mouse-Keyboard 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 | -[unifying]: http://logitech.com/promotions/6072 +[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 [K700]: http://logitech.com/product/wireless-desktop-mk710 diff --git a/docs/index.md b/docs/index.md index 9a9c4427..4d742d23 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,25 +3,44 @@ title: Solaar layout: default --- -**Solaar** is a Linux device manager for Logitech's [Unifying][unifying] Receiver -peripherals. It is able to pair/unpair devices to the receiver, and for most -devices read battery status. +**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 +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. -It comes in two flavors, command-line and GUI. Both are able to list the -devices paired to a Unifying Receiver, show detailed info for each device, and +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, +show detailed info for each device, and also pair/unpair supported devices with the receiver. -[unifying]: http://logitech.com/promotions/6072 +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 +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. + +[unifying]: https://en.wikipedia.org/wiki/Logitech_Unifying_receiver ## Supported Devices -**Solaar** will detect all devices paired with your Unifying Receiver, and at -the very least display some basic information about them. +**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] +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 +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 and their features, see [docs/devices.md](https://pwr-solaar.github.io/Solaar/devices). +[logo]: https://pwr-solaar.github.io/Solaar/assets/solaar.svg ## Pre-built packages @@ -30,13 +49,8 @@ Pre-built packages are available for a few Linux distros. * 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-gnome3` and/or `solaar` package from [universe repository][universe repository] -* Ubuntu/Kubuntu 12.04 to 14.04: use `solaar` package from [ppa:daniel.pavel/solaar][ppa] * 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] - -The `solaar` package uses a standard system tray implementation; to ensure -integration with *gnome-shell* or *Unity*, install `solaar-gnome3`. - * 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 @@ -44,6 +58,9 @@ integration with *gnome-shell* or *Unity*, install `solaar-gnome3`. * an [OpenSUSE rpm][opensuse], courtesy of Mathias Homann * an [Ubuntu/Kubuntu git and stable ppa][ppa3], courtesy of [gogo][ppa4] +The `solaar` package uses a standard system tray implementation; to ensure +integration with *gnome-shell* or *Unity*, install `solaar-gnome3`. + [ppa4]: https://launchpad.net/~trebelnik-stefina [ppa3]: https://launchpad.net/~solaar-unifying [ppa2]: https://launchpad.net/~solaar-unifying/+archive/ubuntu/stable @@ -69,8 +86,7 @@ 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. -- Some devices using the [Nano Receiver][nano] (which is very similar to the - Unifying Receiver) are supported, but not all. For details, see +- 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 diff --git a/docs/installation.md b/docs/installation.md index b3c0b40a..2958a928 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -7,16 +7,15 @@ layout: page ### Requirements -You should have a reasonably new kernel (3.2+), with the `logitech-djreceiver` -driver enabled and loaded (kernel module `hid-logitech-dj`) or Linux 3.19+ -(kernel module `hid-logitech-hidpp`); also, the `udev` package must be installed -and the daemon running. If you have a modern Linux distribution (2011+), you're +You should have a reasonably new kernel (4.0+), with kernel modules `hid-logitech-dj` +and `hid-logitech-hidpp` loaded. Also, the `udev` package must be installed +and the daemon running. If you have a recent Linux distribution (2017+), you are most likely good to go. -The command-line application (`bin/solaar-cli`) requires Python 2.7.3 or 3.2+ -(either version should work), and the `python-pyudev`/`python3-pyudev` package. +Solaar requires Python 2.7.3 or 3.2+ (either version should work), +and the `python-pyudev`/`python3-pyudev` package. -The GUI application (`bin/solaar`) also requires Gtk3, and its GObject +To run the GUI, solaar also requires Gtk3, and its GObject Introspection bindings. The Debian/Ubuntu package names are `python-gi`/`python3-gi` and `gir1.2-gtk-3.0`; if you're using another distribution the required packages are most likely named something similar. @@ -27,6 +26,21 @@ For gnome-shell/Unity support, you also need to have `gir1.2-appindicator3-0.1` installed. +### Downloading + +Clone solaar from GitHub via `git clone https://github.com/pwr-Solaar/Solaar.git` + + +### Running from the Download Directories + +To access the USB devices you may need to run solaar as super user. +Go to the solaar directory and `sudo bin/solaar` for the GUI +or `sudo bin/solaar ` for the CLI. + +If you are running a security-enhanced Linux (RedHat or Fedora) +you may have to turn off enforcing mode. + + ### Installation Normally USB devices are not accessible for r/w by regular users, so you will @@ -57,3 +71,22 @@ root user: 3. Make sure your desktop users are part of the `plugdev` group, by running `gpasswd -a plugdev`. If these users were not assigned to the group before, they must re-login for the changes to take effect. + + +Then solaar can be run from the download directory without using sudo. + +Python programs are usually installed using [pip][pip]. +The pip instructions for solaar are in `setup.py`, the standard place to put such instructions. + +To install solaar for yourself only run `pip install --user .` from the solaar directory. +This tells pip to install into your `.local` directory. You can then run solaar as + `~/.local/bin/solaar`. + +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 +`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. + +[pip]: https://en.wikipedia.org/wiki/Pip_(package_manager) \ No newline at end of file