From d7a7f1e63797107716f9abb86847942f77aea479 Mon Sep 17 00:00:00 2001 From: "Peter F. Patel-Schneider" Date: Thu, 25 Aug 2022 14:39:00 -0400 Subject: [PATCH] docs: add information on enhancement requests to add new devices --- docs/devices.md | 77 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 56 insertions(+), 21 deletions(-) diff --git a/docs/devices.md b/docs/devices.md index bb49c1f7..cef2a03a 100644 --- a/docs/devices.md +++ b/docs/devices.md @@ -27,15 +27,69 @@ open an enhancement issue requesting that it be supported. The directory https://github.com/pwr-Solaar/Solaar/tree/master/docs/devices contains +## Adding new devices + +Most new HID++ devices do not need to be known to Solaar to work. +You should be able to just run Solaar and the device will show up + +If your device does not show up, +either it doesn't use HID++ or the interface it uses isn't the one Solaar normally uses. +To start the process of support for a Logitech device open an enhancement issue for Solaar and +follow these steps: + +1. Make sure the receiver or device is connected and active. + +2. Look at output of `grep -H . /sys/class/hidraw/hidraw*/device/uevent` to find +where information about the device is kept. +You are looking for a line like `/sys/class/hidraw/hidrawN/device/uevent:HID_NAME=` +where is the name of your receiver or device. +`N` is the current HID raw number of your receiver or device. + +3. Provide the contents of the file `/sys/class/hidraw/hidrawN/device/uevent` where N was found +above in the enhancement issue. + +4. Also attach contents of the file `/sys/class/hidraw/hidrawN/device/report_descriptor` +to the enhancement request. +You will have to copy the contents to a file with txt extension before attaching it. +Or, better, install hidrd-convert and attach output of +`hidrd-convert -o spec /sys/class/hidraw/hidrawN/device/report_descriptor` +(To install hidrd on Fedora use `sudo dnf install hidrd`.) + +5. If your device or receiver connects via USB, look at the output of `lsusb` +to find the ID of device or receiver and also provide output of +`lsusb -vv -d xxxx:yyyy` where xxxx:yyyy is ID of device or receiver. + +If your device can connect in multiple ways - via a receiver, via USB (not just charging via a USB cable), +via Bluetooth - do this for each way it can connect. + +### Adding information about a new device to the Solaar code + +The _D function in `../lib/logitech_receiver/descriptors.py` makes a device known to Solaar. +The usual arguments to the _D function are the device's long name, its short name +(codename), and its HID++ protocol version. +Devices that use HID++ 1.0 need a tuple of known registers (registers) and settings (settings). +Settings can be provided for Devices that use HID++ 2.0 or later, +but Solaar can determine these from the device. +If the device can connect to a receiver, provide its wireless product ID (wpid), +If the device can connect via Bluetooth, provide its Bluetooth product ID (btid). +If the device can connect via a USB cable, provide its USB product ID (usbid), +and the interface it uses to send and receiver HID++ messages (interface - default 2). +The use of a non-default USB interface is the main reason for requiring information about +modern devices to be added to Solaar. + + ## Adding new receivers Adding a new receiver requires knowing whether the receiver is a regular Unifying receiver, a Nano receiver, a Bolt receiver, or a Lightspeed receiver. -Add a line to `../lib/logitech_receiver/base_usb.py` defining the receiver as one of these. +This can generally be found using `lsusb`. + +To add a new receiver to the Solaar code +add a line to `../lib/logitech_receiver/base_usb.py` defining the receiver as one of these. If the receiver has an unusual number of pairing slots, then this also needs to be specified. Then add the receiver to the tuple of receivers (ALL). -## Supported Receivers +### Supported Receivers | USB ID | Kind | Max Paired Devices | ------------|------------|--------------------| @@ -73,25 +127,6 @@ The receiver with USB ID 046d:c517 is an old 27 MHz receiver, supporting only subset of HID++ 1.0 protocol. Only hardware pairing is supported. -## Adding new devices - -Most new devices do not need to be known to Solaar to work. - - -The _D function in `../lib/logitech_receiver/descriptors.py` makes a device known to Solaar. -The usual arguments to the _D function are the device's long name, its short name -(codename), and its HID++ protocol version. -Devices that use HID++ 1.0 need a tuple of known registers (registers) and settings (settings). -Settings can be provided for Devices that use HID++ 2.0 or later, -but Solaar can determine these from the device. -If the device can connect to a receiver, provide its wireless product ID (wpid), -If the device can connect via Bluetooth, provide its Bluetooth product ID (btid). -If the device can connect via a USB cable, provide its USB product ID (usbid), -and the interface it uses to send and receiver HID++ messages (interface - default 2). -The use of a non-default USB interface is the main reason for requiring information about -modern devices to be added to Solaar. - - ## Supported Devices