Either documentation or behavior with a second Unifying Receiver - How to specify?

Created by: thx1111

Arch Linux solaar-git 1.0.5rc2.r0.g8d01e281-1 2021 Feb 20

Suppose you have, for instance, a second Unifying Receiver that you want to pair with a particular device, perhaps before moving the second receiver and the paired device to another machine.

To specify and pair that particular device with a specific Unifying Receiver, when there is more than one receiver, and consulting the embedded documentation, compare:

$ solaar pair --help
usage: solaar pair [-h] [receiver]

positional arguments:
  receiver    select a certain receiver when more than one is present

optional arguments:
  -h, --help  show this help message and exit

The Logitech Unifying Receiver supports up to 6 paired devices at the same time.1 Feb 20

versus:

$ solaar --help
usage: solaar [-h] [-d] [-D PATH] [--restart-on-wake-up] [-w {show,hide,only}] [-b {regular,symbolic,solaar}] [-V] [--help-actions] ...

positional arguments:
  {show,probe,config,pair,unpair}
                        optional actions to perform

optional arguments:
  -h, --help            show this help message and exit
  -d, --debug           print logging messages, for debugging purposes (may be repeated for extra verbosity)
  -D PATH, --hidraw PATH
                        unifying receiver to use; the first detected receiver if unspecified. Example: /dev/hidraw2
  --restart-on-wake-up  restart Solaar on sleep wake-up (experimental)
  -w {show,hide,only}, --window {show,hide,only}
                        start with window showing / hidden / only (no tray icon)
  -b {regular,symbolic,solaar}, --battery-icons {regular,symbolic,solaar}
                        prefer regular battery / symbolic battery / solaar icons
  -V, --version         show program's version number and exit
  --help-actions        print help for the optional actions

Note that, currently, the first approach fails - assuming that the receiver is selected using its Serial number, found with solaar show - giving:

$ solaar pair xxxxxxxx
solaar: error: Traceback (most recent call last):
  File "/usr/lib/python3.9/site-packages/solaar/cli/__init__.py", line 202, in run
    m.run(c, args, _find_receiver, _find_device)
  File "/usr/lib/python3.9/site-packages/solaar/cli/pair.py", line 35, in run
    receiver = find_receiver(receiver_name)
TypeError: _find_receiver() missing 1 required positional argument: 'name'

Well, no, the "1 required positional argument" was not "missing", it was just not recognized. Using "Device path" as the name, instead of "Serial", produces the same failed result.

Instead, the second approach does work:

$ solaar -D /dev/hidraw0 pair
Pairing: turn your new device on (timing out in 20 seconds).
Paired device 1: Wireless Mouse M525 (M525) [4013:xxxxxxxx]

So, what is the preferred behavior? If the device path switch approach is preferred, then the solaar pair --help usage message should be revised. If, instead, the original solaar pair [-h] [receiver] approach is preferred, then that would suggest that the device path switch approach should be reverted. I expect that there was a good reason to implement the device path switch approach, which maybe implies that the original solaar pair [-h] [receiver] approach is now deprecated.

It just seems that /usr/lib/python3.9/site-packages/solaar/cli/pair.py is still expecting find_receiver(receiver_name), so, a little confusing. I haven't tried to grok the code, but I do notice there is still:

/usr/lib/python3.9/site-packages/solaar/cli/__init__.py
def _find_receiver(receivers, name):
    assert receivers
    assert name

    for r in receivers:
        if name in r.name.lower() or (r.serial is not None and name == r.serial.lower()):
            return r

Maybe someone can take a look at all this and see what is going on?