├── README.rst └── hidpp20 ├── README.rst └── features └── 0x0000-IRoot.rst /README.rst: -------------------------------------------------------------------------------- 1 | Logitech Documentation 2 | ====================== 3 | 4 | This repository holds public documentation for the protocols used to 5 | interact with some Logitech devices. 6 | 7 | Protocol index: 8 | - `HID++ 2.0 `_ 9 | 10 | The final goal of this repository is to expose the documentation in a 11 | uniform format. While we achieve this, some documentation is 12 | available albeit in various shapes. Hoping that they will be 13 | useful 'as is' they can be obtained from this `Google Drive 14 | folder`_. 15 | 16 | .. _Google Drive folder: https://drive.google.com/drive/u/0/folders/0BxbRzx7vEV7eWmgwazJ3NUFfQ28 17 | -------------------------------------------------------------------------------- /hidpp20/README.rst: -------------------------------------------------------------------------------- 1 | HID++ 2.0 2 | ========= 3 | 4 | HID++ 2.0 is a self descriptive protocol built on top of the USB HID 5 | specification. The goal is to be able to interact with the device 6 | without having any knowledge about it beforehand. 7 | 8 | Packet Structure 9 | ~~~~~~~~~~~~~~~~ 10 | 11 | 12 | .. table:: Table 1 - Packet structure 13 | 14 | +-------------+-----------+--------------+---------------+------------------------+------------+ 15 | | byte | 0 | 1 | 2 | 3 | 4 .. End | 16 | +-------------+-----------+--------------+---------------+----------+-------------+------------+ 17 | | bit | | 15 .. 8 | 7 .. 0 | | 18 | +=============+===========+==============+===============+==========+=============+============+ 19 | | description | Report ID | Device Index | Feature Index | Function | Software ID | Parameters | 20 | +-------------+-----------+--------------+---------------+----------+-------------+------------+ 21 | 22 | 23 | Report ID 24 | The first byte of the report as defined in the HID specification. Supported 25 | report types by the device can be found in the HID report descriptor. 26 | 27 | There following report types are supported: 28 | 29 | .. table:: Table 2 - Supported report types 30 | 31 | =========== ======== ======== 32 | Report Type Value Lenght 33 | =========== ======== ======== 34 | Short ``0x10`` 7 bytes 35 | Long ``0x11`` 20 bytes 36 | =========== ======== ======== 37 | 38 | Device Index 39 | Target device index. ``0xff`` is reserved for corded devices and receivers. 40 | 41 | Feature Index 42 | Each device has a feature table. It resolves the feature ID (see below) to 43 | the internal feature index. The IRoot feature is **required** to be present 44 | and have the index **0**. 45 | 46 | To read the feature table, you can use the ``GetFeature`` function from the 47 | |IRoot|_ feature. 48 | 49 | .. table:: Table 3 - Example device feature table 50 | 51 | =============================== ===== 52 | Feature ID Index 53 | =============================== ===== 54 | ``0x0000`` **(IRoot)** **0** 55 | ``0x0002`` (IFeatureInfo) 1 56 | ``0x0003`` (Device Information) 2 57 | ``0x40a0`` (Fn Inversion) 3 58 | =============================== ===== 59 | 60 | Function 61 | Each HID++ feature can define a list of functions. To access a function you 62 | send a request with the desired feature index and the function ID. 63 | 64 | Software ID 65 | This ID is used in case multiple applications want to interact with the 66 | device. When you send a request with a software ID, the reponse's software 67 | ID will have the same value. You can use it to make sure a reply is meant 68 | for you. 69 | 70 | Parameters 71 | The parameters hold arbitrary data to interact with the functions. For 72 | requests they hold function arguments, and for responses, they hold return 73 | values. 74 | 75 | 76 | .. table:: Table 4 - Short packet structure 77 | 78 | +-------------+------+--------------+---------------+------------------------+----+---+---+ 79 | | byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 80 | +-------------+------+--------------+---------------+----------+-------------+----+---+---+ 81 | | bit | | 15 .. 8 | 7 .. 0 | | 82 | +=============+======+==============+===============+==========+=============+============+ 83 | | description | 0x10 | Device Index | Feature Index | Function | Software ID | Parameters | 84 | +-------------+------+--------------+---------------+----------+-------------+------------+ 85 | 86 | 87 | .. table:: Table 5 - Long packet structure 88 | 89 | +-------------+------+--------------+---------------+------------------------+---+---+---+---+---+---+----+----+----+----+----+----+----+----+----+----+ 90 | | byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 91 | +-------------+------+--------------+---------------+----------+-------------+---+---+---+---+---+---+----+----+----+----+----+----+----+----+----+----+ 92 | | bit | | 15 .. 8 | 7 .. 0 | | 93 | +=============+======+==============+===============+==========+=============+=========================================================================+ 94 | | description | 0x11 | Device Index | Feature Index | Function | Software ID | Parameters | 95 | +-------------+------+--------------+---------------+----------+-------------+-------------------------------------------------------------------------+ 96 | 97 | 98 | Feature List 99 | ~~~~~~~~~~~~ 100 | 101 | 00 - Important 102 | - ``0x0000`` `IRoot `_ 103 | - ``0x0001`` IFeatureSet 104 | - ``0x0002`` IFeatureInfo 105 | 106 | 01 - Common 107 | - ``0x0003`` Device Information 108 | - ``0x0004`` Unit ID 109 | - ``0x0005`` Device Name and Type 110 | - ``0x0006`` Device Groups 111 | - ``0x0007`` Device Friendly Name 112 | - ``0x0008`` Keep-Alive 113 | - ``0x0020`` Config Change 114 | - ``0x0021`` 32-byte Unique Random Identifier 115 | - ``0x0030`` Target Software 116 | - ``0x0080`` Wireless Signal Strength 117 | - ``0x00c0`` DFU Control Legacy 118 | - ``0x00c1`` DFU Control Unsigned 119 | - ``0x00c2`` DFU Control Signed 120 | - ``0x00d0`` DFU 121 | - ``0x1000`` Battery Unified Level Status 122 | - ``0x1001`` Battery Voltage 123 | - ``0x1010`` Charging Control 124 | - ``0x1814`` Change Host 125 | - ``0x1981`` Backlight 1 126 | - ``0x1982`` Backlight 2 127 | - ``0x1a00`` PresenterControl 128 | - ``0x1b00`` Keyboard reprogrammable keys and Mouse buttons 1 129 | - ``0x1b01`` Keyboard reprogrammable Keys and Mouse buttons 2 130 | - ``0x1b02`` Keyboard reprogrammable Keys and Mouse buttons 3 131 | - ``0x1b03`` Keyboard reprogrammable Keys and Mouse buttons 4 132 | - ``0x1b04`` Keyboard reprogrammable Keys and Mouse buttons 5 133 | - ``0x1bc0`` Report HID Usages 134 | - ``0x1c00`` Persistent Remappable Action 135 | - ``0x1d4b`` Wireless Device Status 136 | - ``0x1df0`` Remaining Pairings 137 | 138 | 02 - Mouse 139 | - ``0x2001`` Swap left/right button 140 | - ``0x2005`` Button Swap Cancel 141 | - ``0x2006`` Pointer Axes Orientation 142 | - ``0x2100`` Vertical Scrolling 143 | - ``0x2110`` SmartShift wheel 144 | - ``0x2120`` High-Resolution Scrolling 145 | - ``0x2121`` HiRes Wheel 146 | - ``0x2130`` Ratchet Wheel 147 | - ``0x2150`` Thumbwheel 148 | - ``0x2200`` Mouse Pointer 149 | - ``0x2201`` Adjustable DPI 150 | - ``0x2205`` Pointer Motion Scaling 151 | - ``0x2230`` Sensor angle snapping 152 | - ``0x2240`` Surface Tuning 153 | - ``0x2400`` Hybrid Tracking Engine 154 | 155 | 04 - Keyboard 156 | - ``0x40a0`` Fn Inversion 157 | - ``0x40a2`` Fn Inversion, with default state 158 | - ``0x40a3`` Fn Inversion, for multi-host devices 159 | - ``0x4100`` Encryption 160 | - ``0x4220`` Lock Key State 161 | - ``0x4301`` Solar Keyboard Dashboard Feature 162 | - ``0x4520`` Keyboard Layout 163 | - ``0x4521`` Disable Keys 164 | - ``0x4522`` Disable Keys By Usage 165 | - ``0x4530`` Dual Platform 166 | - ``0x4540`` Keyboard International Layouts 167 | - ``0x4600`` Crown 168 | 169 | 06 - Touchpad 170 | - ``0x6010`` Touchpad FW items 171 | - ``0x6011`` Touchpad SW Items 172 | - ``0x6012`` Touchpad Win8 FW items 173 | - ``0x6020`` TAP enable 174 | - ``0x6021`` TAP enable Extended 175 | - ``0x6030`` Cursor Ballistic 176 | - ``0x6040`` Touchpad resolution divider 177 | - ``0x6100`` TouchPad Raw XY 178 | - ``0x6110`` TouchMouse Raw TouchPoints 179 | - ``0x6120`` BT TouchMouse Settings 180 | - ``0x6500`` Gestures1 181 | - ``0x6501`` Gestures2 182 | 183 | 08 - Gaming Devices 184 | - ``0x8010`` Gaming G-Keys 185 | - ``0x8020`` Gaming M-keys 186 | - ``0x8030`` MacroRecord, MR Key 187 | - ``0x8040`` Brightness control 188 | - ``0x8060`` Adjustable Report Rate 189 | - ``0x8070`` Color LED Effects 190 | - ``0x8071`` RGB Effects 191 | - ``0x8080`` Per Key Lighting 192 | - ``0x8090`` Mode status 193 | - ``0x8100`` Onboard Profiles 194 | - ``0x8110`` Mouse Button Filter 195 | 196 | 197 | .. |IRoot| replace:: ``IRoot`` 198 | .. _IRoot: features/0x0000-IRoot.rst 199 | -------------------------------------------------------------------------------- /hidpp20/features/0x0000-IRoot.rst: -------------------------------------------------------------------------------- 1 | ****************** 2 | IRoot (``0x0000``) 3 | ****************** 4 | 5 | .. table:: Table 1 - Functions 6 | 7 | == ====================== ======================================================= 8 | ID Name Description 9 | == ====================== ======================================================= 10 | 0 ``GetFeature`` Returns the feature index from a desired feature ID 11 | 1 ``GetProtocolVersion`` Returns the protocol version / Replies to a ping action 12 | == ====================== ======================================================= 13 | 14 | .. table:: Table 2 - Events 15 | 16 | == =============== ===================================================================================== 17 | ID Name Description 18 | == =============== ===================================================================================== 19 | 0 ``NoOperation`` This event may be sent by a device to prevent the device from entering low power mode 20 | == =============== ===================================================================================== 21 | 22 | 23 | Versions: 24 | - 1 25 | - Add ``featureVersion`` field to ``GetFeature`` 26 | 27 | 28 | Functions 29 | ========= 30 | 31 | 32 | ``GetFeature`` 33 | ~~~~~~~~~~~~~~ 34 | 35 | Arguments 36 | - featureId 37 | 38 | .. table:: Table 3 - ``GetFeature`` argument parameters 39 | 40 | +-------------+-----------------+-----------------+ 41 | | byte | 0 | 1 | 42 | +=============+=================+=================+ 43 | | description | featureId (MSB) | featureId (LSB) | 44 | +-------------+-----------------+-----------------+ 45 | 46 | Return 47 | - featureIndex 48 | - featureType 49 | - obsolete 50 | - hidden 51 | - featureVersion 52 | The feature version always starts at 0. New versions may introduce New 53 | functionallity but must be backwards compatible. 54 | 55 | .. table:: Table 4 - ``GetFeature`` return parameters 56 | 57 | +-------------+--------------+----------------------------+----------------+ 58 | | byte | 0 | 1 | 2 + 59 | +-------------+--------------+----------+--------+--------+----------------+ 60 | | bit | | 7 | 6 | 5 .. 0 | | 61 | +=============+==============+==========+========+========+================+ 62 | | | | obsolete | hidden | | | 63 | | description | featureIndex +----------+--------+--------+ featureVersion | 64 | | | | featureType | | 65 | +-------------+--------------+----------------------------+----------------+ 66 | 67 | .. table:: Table 5 - `obsolete` value 68 | 69 | ===== ================= 70 | Value Description 71 | ===== ================= 72 | 0 supported feature 73 | 1 obsolete feature 74 | ===== ================= 75 | 76 | .. table:: Table 6 - `hidden` value 77 | 78 | ===== ================= 79 | Value Description 80 | ===== ================= 81 | 0 supported feature 82 | 1 hidden feature 83 | ===== ================= 84 | 85 | 86 | ``GetProtocolVersion`` 87 | ~~~~~~~~~~~~~~~~~~~~~~ 88 | 89 | Arguments 90 | - pingData (optional, you can ignore when getting the version) 91 | 92 | .. table:: Table 7 - ``GetProtocolVersion`` argument parameters 93 | 94 | +-------------+---+---+----------+ 95 | | byte | 0 | 1 | 2 | 96 | +=============+===+===+==========+ 97 | | description | | | pingData | 98 | +-------------+---+---+----------+ 99 | 100 | Return 101 | - protocolMajor 102 | - protocolMinor 103 | - pingData 104 | ``pingData`` returns the same value as specified in the arguments 105 | 106 | .. table:: Table 8 - ``GetProtocolVersion`` return parameters 107 | 108 | +-------------+---------------+---------------+----------+ 109 | | byte | 0 | 1 | 2 | 110 | +=============+===============+===============+==========+ 111 | | description | protocolMajor | protocolMinor | pingData | 112 | +-------------+---------------+---------------+----------+ 113 | 114 | .. table:: Table 9 - `protocolMajor` value 115 | 116 | ===== ========================== 117 | Value Description 118 | ===== ========================== 119 | 0x8f HID++ 1.0 120 | 0x02 HID++ 2.0 - legacy devices 121 | 0x04 HID++ 2.0 122 | ===== ========================== 123 | 124 | 125 | Events 126 | ====== 127 | 128 | 129 | ``NoOperation`` 130 | ~~~~~~~~~~~~~~~ 131 | 132 | This event may be sent by a device, as needed, to prevent the device from 133 | entering low power mode. If sent following a HID response this may allow the 134 | device to respond quicker to the next HID command. This event is a no-op and 135 | contains no data. The host software can safely ignore this event. 136 | --------------------------------------------------------------------------------