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

docs: add information on enhancement requests to add new devices

This commit is contained in:
Peter F. Patel-Schneider 2022-08-25 14:39:00 -04:00
parent 72dbf1c32f
commit d7a7f1e637
1 changed files with 56 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
docs/devices.md
View File

@ -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 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=<NAME>`
where <NAME> 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 new receivers
Adding a new receiver requires knowing whether the receiver is a regular Adding a new receiver requires knowing whether the receiver is a regular
Unifying receiver, a Nano receiver, a Bolt receiver, or a Lightspeed receiver. 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 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). to be specified. Then add the receiver to the tuple of receivers (ALL).
## Supported Receivers ### Supported Receivers
| USB ID | Kind | Max Paired Devices | | 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. 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 ## Supported Devices