diff --git a/docs/capabilities.md b/docs/capabilities.md index fe7fdd40..296d0b12 100644 --- a/docs/capabilities.md +++ b/docs/capabilities.md @@ -65,7 +65,8 @@ Solaar uses the HID++ protocol to pair devices to receivers and unpair devices from receivers. Solaar also uses the HID++ protocol to display features of receivers and devices. Solaar can modify some of the features of devices. Solaar currently only displays some features and can modify -even fewer. +even fewer. For more information on HID++ features and their support in +Solaar see [docs/features.md](https://pwr-solaar.github.io/Solaar/features). Solaar does not do anything beyond using the HID++ protocol to change the behavior of receivers and devices. In particular, Solaar cannot change how @@ -86,6 +87,7 @@ Solaar does keep track of some of the changeable state of a device between invocations. When Solaar starts it restores on-line devices to their previously-known state. Also, while running Solaar restores devices to their previously-known state when the device comes on line. +This information is stored in the file `~/.config/solaar/config.json`. Querying a device for its current state can require quite a few HID++ interactions. These interactions can temporarily slow down the device, so diff --git a/docs/devices.md b/docs/devices.md index 85edf158..2e341676 100644 --- a/docs/devices.md +++ b/docs/devices.md @@ -20,15 +20,30 @@ level. For mice, the DPI column specifies if the mouse's sensitivity is fixed (`-`), can only be read (`R`), or can be read and changed by Solaar (`R/W`). -The reprog(rammable) keys feature is currently not fully supported by Solaar. -You are able to read this feature using command-line interface of Solaar, -but it is not possible to assign different keys. - - If your device works with Solaar, but its supported features are not correctly specified here, please open an issue on the [Solaar github repository][solaar] with the pleasant news. +### Adding new receivers and devices + +Adding a new receiver requires knowing whether the receiver is a regular +Unifying receiver, a nano receiver, or a lightspeed receiver. 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). + +To let Solaar read and write to the receiver information on it needs to be +added to rules.d/42-logitech-unify-permissions.rules. Add a new line to +that file with the vendor and product ids, just like the other lines in the +file. Then this file has to be copied into /etc/udev/rules.d + +Most new devices do not need to be known to Solaar to work. However, an +entry in lib/logitech-receiver/descriptors.py can provide a better name for +the device and a feature list can speed up Solaar startup a bit. The +arguments to the _D function are the device's long name, its short name +(codename), its HID++ protocol version, its wireless product ID (wpid), and +a tuple of known feature settings (from lib/logitech/settings_templates.py). + ### Receivers: diff --git a/docs/features.md b/docs/features.md index 46aefeb9..2d2981fd 100644 --- a/docs/features.md +++ b/docs/features.md @@ -33,7 +33,7 @@ Feature | ID | Status | Notes `DEVICE_RESET` | `0x1802` | :x: | `OOBSTATE` | `0x1805` | :x: | `CONFIG_DEVICE_PROPS` | `0x1806` | :x: | -`CHANGE_HOST` | `0x1814` | :x: | +`CHANGE_HOST` | `0x1814` | :x: | :wrench: `HOSTS_INFO` | `0x1815` | :heavy_plus_sign: | `get_host_names`, partial listing only `BACKLIGHT` | `0x1981` | :x: | `BACKLIGHT2` | `0x1982` | :heavy_check_mark: | `_feature_backlight2` @@ -46,7 +46,7 @@ Feature | ID | Status | Notes `REPROG_CONTROLS_V3` | `0x1B03` | :x: | `REPROG_CONTROLS_V4` | `0x1B04` | :heavy_plus_sign: | `get_keys`, _feature_reprogrammable_keys `REPORT_HID_USAGE` | `0x1BC0` | :x: | -`PERSISTENT_REMAPPABLE_ACTION` | `0x1C00` | :x: | +`PERSISTENT_REMAPPABLE_ACTION` | `0x1C00` | :x: | :wrench: `WIRELESS_DEVICE_STATUS` | `0x1D4B` | :x: | status reporting from device `REMAINING_PAIRING` | `0x1DF0` | :x: | `FIRMWARE_PROPERTIES` | `0x1F1F` | :x: | @@ -75,8 +75,8 @@ Feature | ID | Status | Notes `KEYBOARD_LAYOUT` | `0x4520` | :x: | read only `KEYBOARD_DISABLE_KEYS` | `0x4521` | :heavy_check_mark: | `_feature_disable_keyboard_keys` `KEYBOARD_DISABLE_BY_USAGE` | `0x4522` | :x: | -`DUALPLATFORM` | `0x4530` | :x: | -`MULTIPLATFORM` | `0x4531` | :x: | +`DUALPLATFORM` | `0x4530` | :x: | :wrench: +`MULTIPLATFORM` | `0x4531` | :x: | :wrench: `KEYBOARD_LAYOUT_2` | `0x4540` | :x: | read only `CROWN` | `0x4600` | :x: | `TOUCHPAD_FW_ITEMS` | `0x6010` | :x: | @@ -110,7 +110,7 @@ Feature | ID | Status | Notes `EQUALIZER` | `0x8310` | :x: | `HEADSET_OUT` | `0x8320` | :x: | -"read only" in the notes column means that the state of the feature can be read, but not set. +"read only" in the notes column means that the feature is a read-only feature and cannot be changed. # Implementing a feature diff --git a/docs/hidpp-documentation.txt b/docs/hidpp-documentation.txt new file mode 100644 index 00000000..3a1abc02 --- /dev/null +++ b/docs/hidpp-documentation.txt @@ -0,0 +1,2 @@ +Documentation on HID++ can be found in the Google drive directory +https://drive.google.com/drive/folders/0BxbRzx7vEV7eWmgwazJ3NUFfQ28 diff --git a/docs/icons_names.txt b/docs/icons_names.txt deleted file mode 100644 index 867a1adf..00000000 --- a/docs/icons_names.txt +++ /dev/null @@ -1,34 +0,0 @@ -# battery icon names across various icon themes - -B = 'battery' -CG = 'charging' -GB = 'gpm-battery' - -theme (unknown) 0 0-CG 20 20-CG 40 40-CG 60 60-CG 80 80-CG 100 100-CG 100-full ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - -gnome B-missing B-empty - B-caution B-caution-CG B-low B-low-CG - - B-good B-good-CG B-full B-full-CG B-full-charged - -Humanity GB-missing GB-000 GB-000-CG GB-020 GB-020-CG GB-040 GB-040-CG GB-060 GB-060-CG GB-080 GB-080-CG GB-100 GB-100-CG GB-charged -(gnome) - B_empty - B-caution - B-low - B_two_thirds - B_third_fourth - B_full B_plugged B_charged - -elementary B-missing B-000 B-000-CG B-020 B-020-CG B-040 B-040-CG B-060 B-060-CG B-080 B-080-CG B-100 B-100-CG B-charged -(gnome) - B-empty - B-caution B-caution-CG B-low B-low-CG - - B-good B-good-CG B-full B-full-CG B-full-charged - - B_empty - - - - - B_two_thirds - B_third_fourth - B_full B_plugged B_charged - -faenza - GB-000 GB-000-CG GB-020 GB-020-CG GB-040 GB-040-CG GB-060 GB-060-CG GB-080 GB-080-CG GB-100 GB-100-CG GB-charged -(gnome) - B_empty - B_caution - B_low - B_two_thirds - B_third_fourth - B_full B_plugged B_charged - -ubuntu-mono GB-missing GB-000 GB-000-CG GB-020 GB-020-CG GB-040 GB-040-CG GB-060 GB-060-CG GB-080 GB-080-CG GB-100 GB-100-CG GB-charged -(Humanity) B-000 B-000-CG B-020 B-020-CG B-040 B-040-CG B-060 B-060-CG B-080 B-080-CG B-100 B-100-CG B-charged - B_empty - B-caution - B-low - - - - - B_full - B_charged - -oxygen B-missing B-low B-CG-low B-caution B-CG-caution B-040 B-CG-040 B-060 B-CG-060 B-080 B-CG-080 B-100 B-CG - - -moblin - - - B-low - B-caution - - - B-good - B-full B-charging - - -nuvola B-missing B-low - - - - - - - - - - B-charging - - - - -# weather icons (for lux) diff --git a/docs/index.md b/docs/index.md index cbe7014e..9ff49c7b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -101,8 +101,12 @@ See [docs/installation.md](https://pwr-solaar.github.io/Solaar/installation) for ## Known Issues -- 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. +- The icon in the system tray can show up as 'black on black' in dark + distributions. This is due to problems in many system tray + implementations. Changing to a different theme may help. + +- If some icons appear broken in the application, make sure you've properly + configured the Gtk theme and icon theme in your control panel. - Running the command-line application while the GUI application is also running *may* occasionally cause either of them to become diff --git a/docs/logitech/2200_mousepointer.pdf b/docs/logitech/2200_mousepointer.pdf deleted file mode 100644 index 301612cf..00000000 Binary files a/docs/logitech/2200_mousepointer.pdf and /dev/null differ diff --git a/docs/logitech/4301_k750_solarkeyboard_lightandbattery.pdf b/docs/logitech/4301_k750_solarkeyboard_lightandbattery.pdf deleted file mode 100644 index 8bebb91d..00000000 Binary files a/docs/logitech/4301_k750_solarkeyboard_lightandbattery.pdf and /dev/null differ diff --git a/docs/logitech/6100_touchpadraw.pdf b/docs/logitech/6100_touchpadraw.pdf deleted file mode 100644 index ab9e630b..00000000 Binary files a/docs/logitech/6100_touchpadraw.pdf and /dev/null differ diff --git a/docs/logitech/6110_touchmouseraw.pdf b/docs/logitech/6110_touchmouseraw.pdf deleted file mode 100644 index 209fbef9..00000000 Binary files a/docs/logitech/6110_touchmouseraw.pdf and /dev/null differ diff --git a/docs/logitech/Unifying_receiver_DJ_collection_specification_draft.pdf b/docs/logitech/Unifying_receiver_DJ_collection_specification_draft.pdf deleted file mode 100644 index 862ae947..00000000 Binary files a/docs/logitech/Unifying_receiver_DJ_collection_specification_draft.pdf and /dev/null differ diff --git a/docs/logitech/battery-level.txt b/docs/logitech/battery-level.txt deleted file mode 100644 index 719f058d..00000000 --- a/docs/logitech/battery-level.txt +++ /dev/null @@ -1,26 +0,0 @@ -The battery/charging level and status is reported only if the related -reporting flag in register 0x00 is enabled by the host. The -"Battery/Charging Level" byte indicates the battery level if the -"Charging State" indicates 0x00 ("Not Charging"). If "Charging State" -indicates 0x21 to 0x23 ("Charging"), the "Battery/Charging Level" byte -indicates the level of charging. - -10 ix 07 r0 r1 r2 00 -r0 -> Battery/Charging Level - 0x00 = Reserved/Unknown - 0x01 = Critical - 0x02 = Critical (legacy value, don't use) - 0x03 = Low - 0x04 = Low (legacy value, don't use) - 0x05 = Good - 0x06 = Good (legacy value, don't use) - 0x07 = Full - 0x08..0xFF = Reserved -r1 -> Charging state - 0x00 = Not charging - 0x01..0x1F = Reserved (not charging) - 0x20 = Unknown charging state - 0x21 = Charging - 0x22 = Charging complete - 0x23 = Charging error - 0x24..0xFF = Reserved diff --git a/docs/logitech/hid10.txt b/docs/logitech/hid10.txt deleted file mode 100644 index 4a91992e..00000000 --- a/docs/logitech/hid10.txt +++ /dev/null @@ -1,277 +0,0 @@ - *Read short register command* - -10 ix 81 02 00 00 00 - -ix - -Index 0x0n: Device #n - - 0xFF: Transceiver - -*Response to Read command (success)* - -10 ix 81 02 00 r1 r2 - -ix - -Index (same as command) - - - - - -r1 - -Number of Connected Devices - - bit 0..7: Number of connected devices (receivers only) - -r2 - -Number of Remaining Pairing Slots - - bit 0..7: Number of remaining pairing slots - - - *Read long register command* - -10 ix 83 B5 nn 00 00 - -ix - -Index 0xFF: Transceiver - -nn - -0x20 Device 1 - -0x21 Device 2 - -0x22 Device 3 - -0x23 Device 4 - -0x24 Device 5 - -0x25 Device 6 - -0x26..0x2F Reserved for future extensions - -*Response to Read command (success)* - -11 ix 83 B5 nn r1 r2 r3 r4 r5 r6 r7 r8 r9 ra rb rc rd 00 00 - -ix - -Index (same as command) - -nn - - (same format as above) - -r1 - -Destination ID - -r2 - -Reserved - -r3 - -Wireless PID MSB - -r4 - -Wireless PID LSB - -r5 - -Reserved - -r6 - -Reserved - -r7 - -Device type - -0 undefined - -1 keyboard - -2 mouse - -3 numpad - -4 presenter - -5 reserved - -6 reserved - -7 remote control - -8 trackball - -9 touchpad - -a tablet - -b gamepad - -c joystick - -r8 - -Reserved - -r9 - -Reserved - - - - - - - -Alternatively, if enabled, you can also receive a notification when a new -device is paired: - -This message is sent by a receiver to the host SW to report a freshly -connected device. Enable the HID++ connection reporting by setting the -corresponding bit in register 0x00 via HID++ Set Register command. - -*Notification* - -10 ix 41 r0 r1 r2 r3 - -ix - -Index - -r0 - -bits [0..2] Protocol type - - 0x03 = eQUAD - - 0x04 = eQuad step 4 DJ - -bits [3..7] Reserved - -r1 - -Device Info - - bit0..3 = Device Type - - 0x00 = Unknown - - 0x01 = Keyboard - - 0x02 = Mouse - - 0x03 = Numpad - - 0x04 = Presenter - - - r2 - -Wireless PID LSB - -r3 - -Wireless PID MSB - -To enable the notifications: -Enable HID++ Notifications: - -This register defines a number of flags that allow the SW to turn on or off -individual spontaneous HID++ reports. Not setting a flag means default -reporting. See the table below for more details on each flag. - -For all bits: *0 = disabled* (default value at power-up), 1 = enabled. - - - -*Read short register command* - -10 ix 81 00 00 00 00 - -ix - -Index 0x0n: Device #n - - 0xFF: Transceiver - -*Response to Read command (success)* - -10 ix 81 00 r0 r1 r2 - -ix - -Index (same as command) - -r0 - -HID++ Reporting Flags (Devices) - - bit 0..3. reserved - - bit 4: Battery Status - - bit 5..7 reserved - -r1 - -HID++ Reporting Flags (Receiver) - - bit 0: Wireless notifications - - bit 1..7 reserved - -r2 - - - - -*Write short register command* - -10 ix 80 00 p0 p1 p2 - -ix - -Index 0x0n: Device #n - - 0xFF: Transceiver - -p0 - -HID++ Reporting Flags (Devices) - - (same format as above) - -p1 - -HID++ Reporting Flags (Receiver) - - (same format as above) - -p2 - - - *Response to Write command (success)* - -10 ix 80 00 zz zz zz - -ix - -Index (same as command) - -zz - -(don't care, recommended to return 0) diff --git a/docs/logitech/logitech_hidpp10_specification_for_Unifying_Receivers.pdf b/docs/logitech/logitech_hidpp10_specification_for_Unifying_Receivers.pdf deleted file mode 100644 index 94f3df42..00000000 Binary files a/docs/logitech/logitech_hidpp10_specification_for_Unifying_Receivers.pdf and /dev/null differ diff --git a/docs/logitech/logitech_hidpp_2.0_specification_draft_2012-06-04.pdf b/docs/logitech/logitech_hidpp_2.0_specification_draft_2012-06-04.pdf deleted file mode 100644 index 1ee54640..00000000 Binary files a/docs/logitech/logitech_hidpp_2.0_specification_draft_2012-06-04.pdf and /dev/null differ diff --git a/docs/logitech/performance_mx_led_registers.pdf b/docs/logitech/performance_mx_led_registers.pdf deleted file mode 100644 index b58f128f..00000000 Binary files a/docs/logitech/performance_mx_led_registers.pdf and /dev/null differ diff --git a/docs/usb-ids.txt b/docs/usb-ids.txt deleted file mode 100644 index a5fe9b36..00000000 --- a/docs/usb-ids.txt +++ /dev/null @@ -1,14 +0,0 @@ -Unifying receiver: - 046d:c52b interface: 2 driver: logitech-djreceiver - 046d:c532 interface: 2 driver: logitech-djreceiver - - -Nano receiver, Advanced/Unifying ready: - 046d:c52f interface: 1 driver: hid-generic - - -Nano receiver: - 046d:c51a interface: 1 driver: hid-generic - 046d:c526 interface: 1 driver: hid-generic - 046d:c52e interface: 1 driver: hid-generic - 046d:c531 interface: 1 driver: hid-generic