Friday, July 25, 2014

Logitech Unifying Receiver Pairing on Linux

This post is mostly for my future reference. Really simple to pair a new mouse with an existing receiver on Linux.

ltunify is a program resulting from the gathered knowledge on the Logitech HID++ protocol. It allows you to pair additional devices like keyboards and mice to your Unifying receiver, unpair existing devices and list information about connected devices. This section will show you how to install the ltunify program.

Besides a C compiler and a way to fetch sources (wget+tar or git), you will need Linux 3.2 or newer with the hid-logitech-dj module. On Debian and Ubuntu distributions, the required packages can be installed using:

sudo apt-get install git gcc

Fetch the sources and install ltunify to $HOME/bin/ using the next commands:

git clone https://git.lekensteyn.nl/ltunify.git
cd ltunify
make install-home

The following steps will assume that $HOME/bin is available in your path. If not, run:

export PATH="$HOME/bin:$PATH"

If everything went well, you should be able to run ltunify --help to show the available options:

Usage: ltunify [options] cmd [cmd options]
Logitech Unifying tool version dev
Copyright (C) 2013 Peter Wu <lekensteyn@gmail.com>

Generic options:
-d, --device path Bypass detection, specify custom hidraw device.
-D Print debugging information
-h, --help Show this help message

Commands:
list - show all paired devices
pair [timeout] - Try to pair within "timeout" seconds (1 to 255,
default 0 which is an alias for 30s)
unpair idx - Unpair device
info idx - Show more detailed information for a device
receiver-info - Show information about the receiver
In the above lines, "idx" refers to the device number shown in the
first column of the list command (between 1 and 6). Alternatively, you
can use the following names (case-insensitive):
Keyboard Mouse Numpad Presenter Trackball Touchpad

The below session shows you how to use a device index to unpair a mouse.

$ sudo ltunify list
Devices count: 1
Connected devices:
idx=1 Mouse M525

$ sudo ltunify unpair 1
Device 0x01 Mouse successfully unpaired

$ sudo ltunify list
Devices count: 0
Connected devices:

$ sudo ltunify pair
Please turn your wireless device off and on to start pairing.
Found new device, id=0x01 Mouse

$ sudo ltunify list
Devices count: 1
Connected devices:
idx=1 Mouse M525

It is also possible to select a device by device type (case-insensitive). When multiple devices of the same type are available, the first one will be selected.

$ sudo ltunify unpair mouse
Device 0x01 Mouse successfully unpaired