Trace:

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
notes:hw:xencelabs-quickkeys [2023/04/24 16:43] – maffnotes:hw:xencelabs-quickkeys [2023/06/26 14:17] (current) – maff
Line 5: Line 5:
 ===== Hardware info ===== ===== Hardware info =====
  
-USB: VID 0x28bd PID 0x5202 - Manufacturer "HANVON UGEE", advertises no version or serial number.+USB: VID ''0x28bd'' PID ''0x5202'' - Manufacturer "HANVON UGEE", advertises no version or serial number.
  
 USB pcaps pending - currently on a mac machine and capturing USB traffic on a mac requires disabling system integrity protection. USB pcaps pending - currently on a mac machine and capturing USB traffic on a mac requires disabling system integrity protection.
Line 13: Line 13:
 Device appears to transmit only signals (ie., button press and rotary wheel moving +/- steps); although it appears to be using HID, it does not present as a regular input device and requires the driver components for actioning anything. Device appears to transmit only signals (ie., button press and rotary wheel moving +/- steps); although it appears to be using HID, it does not present as a regular input device and requires the driver components for actioning anything.
  
-The device seems to have an FCC ID - 2AYM6-K02A. The firmware version indicates it as K02-B, making me wonder if this device is not actually compliant with the FCC as it does not display the regulatory mark anywhere.+The device seems to have an FCC ID - ''2AYM6-K02A''. The firmware version indicates it as ''K02-B'', making me wonder if this device is not actually compliant with the FCC as it does not display the regulatory mark anywhere.
  
 ===== Software info ===== ===== Software info =====
Line 19: Line 19:
 Software seems to be a generic XenceLabs-branded application that works for both the QuickKeys and other products offered by the company. Software seems to be a generic XenceLabs-branded application that works for both the QuickKeys and other products offered by the company.
  
-The software is delivered as a DMG disk image, which contains an `xar` compressed `pkg` (on Mac). Within this, there is a set of preinstall and postinstall scripts (preinstall removes any existing copies of the software, and closes any running instances; postinstall runs a loop waiting for the driver and other software to be installed) and the actual software. The scripts and software are stored in gzipped `cpio` archives.+The software is delivered as a DMG disk image, which contains an ''xar'' compressed ''pkg'' (on Mac). Within this, there is a set of preinstall and postinstall scripts (preinstall removes any existing copies of the software, and closes any running instances; postinstall runs a loop waiting for the driver and other software to be installed) and the actual software. The scripts and software are stored in gzipped ''cpio'' archives.
  
-The software archive contains a `LaunchAgents` plist (`com.xencelabs.xencelabstablet.plist`) which registers a launch agent `com.ugee.XencelabsAgent` to be started during login and during a logged-in session, and launches `XencelabsAgent` with the command-line argument `/mini`. It registers the `com.ugee.Xencelabs` mach service.+The software archive contains a ''LaunchAgents'' plist (''com.xencelabs.xencelabstablet.plist'') which registers a launch agent ''com.ugee.XencelabsAgent'' to be started during login and during a logged-in session, and launches ''XencelabsAgent'' with the command-line argument ''/mini''. It registers the ''com.ugee.Xencelabs'' mach service.
  
 The software archive also contains a set of applications in a tree: The software archive also contains a set of applications in a tree:
Line 27: Line 27:
   * Xencelabs   * Xencelabs
     * .guide (contains a copy of LGPLv3, some images, and some plists)     * .guide (contains a copy of LGPLv3, some images, and some plists)
-      * Info.plist: `{"Mode": "0"}` +      * Info.plist: ''{"Mode": "0"}'' 
-      * com.xencelabs.config.plist: `{"guide": 0}` +      * com.xencelabs.config.plist: ''{"guide": 0}'' 
-      * com.xencelabs.config_run.plist: `{"guide": 1, "KeyBoard": 0}`+      * com.xencelabs.config_run.plist: ''{"guide": 1, "KeyBoard": 0}''
     * Xencelabs.app     * Xencelabs.app
     * UninstallXencelabs.app     * UninstallXencelabs.app
Line 41: Line 41:
 All applications appear to be universal binaries with both arm64 and amd64 builds. All applications appear to be universal binaries with both arm64 and amd64 builds.
  
-Going by the system permissions prompts that come up when various inputs from the device are received by the computer, XencelabsDriver handles scrolling and XencelabsAgent handles keypresses. This is known because both applications request the ability to control the system via accessibility features. Rudimentary binary analysis shows that if this is denied, the programs will execute `tccutil reset Accessibility` on themselves to ask again for the permission.+Going by the system permissions prompts that come up when various inputs from the device are received by the computer, ''XencelabsDriver'' handles scrolling and ''XencelabsAgent'' handles keypresses. This is known because both applications request the ability to control the system via accessibility features. Rudimentary binary analysis shows that if this is denied, the programs will execute ''tccutil reset Accessibility'' on themselves to ask again for the permission.
  
 ===== Firmware info ===== ===== Firmware info =====
  
-The device came loaded with firmware version K02-B 20210824, and the diagnostic tool states the "keyboard selection" is English.+The device came loaded with firmware version ''K02-B 20210824'', and the diagnostic tool states the "keyboard selection" is English.
  
 ===== Observations relating to the stock software and firmware ===== ===== Observations relating to the stock software and firmware =====
Line 79: Line 79:
 When first plugged in, the dongle appears to be identified by the system as a keyboard. When first plugged in, the dongle appears to be identified by the system as a keyboard.
  
-USB: VID 0x28bd PID 0x5203 - Manufacturer "HANVON UGEE", again advertising no serial number or version.+USB: VID ''0x28bd'' PID ''0x5203'' - Manufacturer "HANVON UGEE", again advertising no serial number or version.
  
 It has model number ACD12-A and FCC ID 2AYM6-ACD12A It has model number ACD12-A and FCC ID 2AYM6-ACD12A
  
-With the dongle plugged in, the software allows you to manage up to two "pairings" for the dongle. The device appears to be pre-paired to slot 2, and the software lists it as having ID (address?) `f483b3LLNNLL` (last three octets anonymised but available on request) - this looks very much like a bluetooth MAC address, making me wonder if the dongle is simply bluetooth.+With the dongle plugged in, the software allows you to manage up to two "pairings" for the dongle. The device appears to be pre-paired to slot 2, and the software lists it as having ID (address?) ''f483b3LLNNLL'' (last three octets anonymised but available on request) - this looks very much like a bluetooth MAC address, making me wonder if the dongle is simply bluetooth.
  
 The FCC-published information about this device indicates that yes - this is simply bluetooth/BLE. The detailed emissions report includes a screenshot of nRFgo Studio, which suggests a Nordic Semiconductor nRF is being used for BLE transmission (which would make sense). The FCC-published information about this device indicates that yes - this is simply bluetooth/BLE. The detailed emissions report includes a screenshot of nRFgo Studio, which suggests a Nordic Semiconductor nRF is being used for BLE transmission (which would make sense).
 +
 +Diagnostic information in the software reports the dongle's firmware as ''ACD12-B 20201214094214 15.3.0''
 +
 +===== Linux Drivers =====
 +
 +Somehow never occurred to me that the linux driver package might shed more light on how the software and hardware interact.
 +
 +The Linux download contains packages for RPM and dpkg-based distros, as well as a tarball with installation scripts - the most obvious point for examination. It contains normal XDG stuff for startup, application registration and so on, but also contains udev rules:
 +
 +<code text 10-xencelabs.rules>
 +KERNEL=="uinput",MODE:="0666",OPTIONS+="static_node=uinput"
 +SUBSYSTEMS=="usb",ATTRS{idVendor}=="28bd",MODE:="0666"
 +</code>
 +
 +It also contains the actual software and a set of Qt5 libraries. The application itself is invoked via a script which exports LD_LIBRARY_PATH beforehand.
 +
 +The application binary is (predictably) a dynamically-linked ELF built for amd64.
 +
 +===== Plans =====
 +
 +Get USB packet captures of:
 +
 +  * Initial communication between the software and the device itself
 +  * Initial communication between the software and the dongle
 +  * Configuring the pairing for the dongle and the device
 +  * Configuring the device
 +  * Changing the sleep time and screen brightness
 +
 +Check any network communications the software makes.
 +
 +  * Application has references to several hostnames/API servers, all ending with ''/api''
 +    * '' www,xencelabs,com''
 +    * '' www,newtest,xencelabs,com,cn''
 +    * '' www,xencelabs,com,cn''
 +    * '' www,xencelabs,com/ctrad''
 +    * '' www,xencelabs,com/{fr|de|jp|kr|it|es}''
 +    * '' www,zs,xencelabs,cc''
 +  * Checks for updates to itself by calling ''{API server}/getLatestDriver?system_sign={mac|win|linux}&language={en|?}'' - returns a JSON payload
 +  * Checks for firmware updates by calling ''{API server}/getLatestFirmware?project_sign={?}'' - presumably returns a JSON payload, no idea what ''project_sign'' is though
 +
 +===== Notes during reverse-engineering =====
 +
 +Both the dongle and the direct USB connection expose a USB Usage with page FF0Ah
 +
 +Not 100% on packet/HID report format, but..
 +
 +  * All writes are 32-byte packets
 +  * Bytes 10-15 inclusive are the MAC address of the device, or zeroes if connected via USB instead of the dongle
 +  * Byte 0 is always 0x02 - this is the endpoint I think
 +  * Data is only sent from the device once it has been subscribed to:
 +  * 02b410 - Subscribes to battery change events
 +  * 02b004 - Subscribes to button press and wheel events
 +  * 02b801 - Subscribes to dongle connection events
 +
 +Commands/opcodes are as follows (an ampersand followed by a number indicates an argument/parameter)
 +
 +  * 02b40801&0 - Set the idle timeout in minutes between 0 and 255
 +  * 02b4040101&0 - Set the velocity (poll rate?) of the wheel (5 = slowest, 1 = fastest)
 +  * 02b10a01&0 - Set the display brightness (0 = off, 3 = highest)
 +  * 02b1&0 - Set the display rotation (0 = 0º, 3 = 270º)
 +  * 02b40101&0&1&2 - Set the RGB colour value of the ring around the wheel (0-255, 0-255, 0-255)
 +  * 02b100&000&1000000000000000000000000000000&2... - Set the label for one of the eight macro keys (arg0 is the key number from 1 to 8, arg1 is the length of the label text * 2, arg2 is the label text encoded as unicode/utf16le) - the device seems able to take a label length up to 24 characters but i've not identified how it receives characters after the 8th.
 +  * 02b1&0&100&2&3 - Display an "overlay" message (arg0 indicates if it is the first message, 5, or a continuation of the message, 6. arg1
 +
 +===== Links =====
 +
 +[[https://github.com/julusian/node-xencelabs-quick-keys]] - NodeJS implementation of the HID interface
  
  
Navigation
  • Home