Logitech Hidpp 2.0 Specification Draft 2012-06-04
Logitech Hidpp 2.0 Specification Draft 2012-06-04
0 Draft Specification
04 June, 2012
Contents
Disclaimer.......................................................................................................................................................................... 1
Introduction........................................................................................................................................................................ 1
Protocol Versioning .......................................................................................................................................................... 1
Ping same as Protocol versioning ................................................................................................................................. 2
Protocol HID++2.0 essential features ........................................................................................................................... 2
0x0000 IRoot: the entry point feature............................................................................................................................ 3
0x0001 IFeatureSet: Get list of device Features ......................................................................................................... 4
0x0003 LONG Get FW version, build + protocol_specific_info................................................................................. 7
0x0005 Device Name and Type..................................................................................................................................... 8
0x1000 Battery Unified Level Status ............................................................................................................................. 9
0x1B00 KBD reprogrammable Keys and MSE buttons (Rev1)............................................................................... 10
0x1D4B Wireless Device Status .................................................................................................................................. 14
HID++2.0 Device transaction example ........................................................................................................................... 14
Disclaimer
THIS SPECIFICATION IS LICENSED AND PROVIDED BY LOGITECH "AS IS" AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL LOGITECH OR ANY OF ITS
AFFILIATED COMPANIES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SPECIFICATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
Introduction
Logitech’s HID++2.0 is the protocol over HID used to access most of Logitech HID devices.
This document describes the basics of HID ++ 2.0 protocol, including versioning, the structure of functions and the
following features: entry point, retrieving firmware information such as version and build numbers and device name and
type (such as keyboard, mouse, etc.). An example device transaction concludes this document.
Protocol Versioning
HID++ protocol should have a versioning support to allow forward compatibility and versioning API should be obviously
independent of the various protocols.
Since version 1.0 of the protocol does not have explicit versioning support, we need a way to discriminate version 1.0 from 2.0 and
further.
Version 1.0 of the protocol does not implement RegisterAccessID 0x00. Sending a request with this value generates an error
message, One solution is to use this particularity to implement a GetProtocolVersion function.
version = GetProtocolVersion()
Request: 0x10.DeviceIndex.0x00.0x1n.0x00.0x00.0xUU
n in 0x1n is SwID
0xUU is "ping data" defined by SW
Response:
HID++ 1.0: 0x10.DeviceIndex.0x8F.0x00.0xFn.0x01.0x00 (ERR_INVALID_SUBID response)
HID++ 2.0: 0x10.DeviceIndex.0x00.0x1n,0x02.0x00.0xUU
HID++ XX.YY: 0x10.DeviceIndex.0x00.0x1n,0xXX.0xYY.0xUU
response = Ping(0xXX)
Request: 0x10.DeviceIndex.0x00.0x1n.0x00.0x00.0xUU
Response:
HID++ 2.0: 0x10.DeviceIndex.0x00.0x1n,0x02.0x00.0xUU
This makes the ping request appear as a hidden 0xE function of the IRoot feature so that firmware and software can use the normal
feature/function dispatch mechanism to handle it.
to simplify implementation in both FW and SW is to make the ping request "look" like a normal feature request by putting the SwId in its
normal place. The "n" in 0xEn below would be the SwId. The change in the high nibble from F to E is to avoid conflict with the
GetProtocolVersion request.
Functions
A function is composed of a request sent by the host PC followed by one or more responses returned by the HID++ 2.0 device/receiver.
Within a given feature, each function is defined by a function identifier (assigned from a pool of 16 identifiers shared with ASEs, see
below). Requests can have up to 3 or 16 bytes of parameters, while responses return the same quantity of results. Most functions will
be read or write functions (although functions which do both or neither are also allowed).
Unless otherwise specified, the protocol is big-endian, meaning that a 16bits value sent on bytes 4 and 5, will have its MSB in byte 4
and its LSB in byte 5.
Requests
0 1 2 3 4 5 6
Dev. index Feature index Fctn/ASE Sw. id.
0x10 Parameters
[1 .. 255] [1 .. 254] id. [0 .. 15] [1 .. 15]
0 1 2 3 4 5 6 ... 19
Fctn/ASE
Dev. index Feature index Sw. id.
0x11 id. [0 .. Parameters
[1 .. 255] [1 .. 254] [1 .. 15]
15]
Responses
0 1 2 3 4 5 6 ... 19
Fctn/ASE
Dev. index Feature index Sw. id.
0x11 id. [0 .. Results
[1 .. 255] [1 .. 254] [1 .. 15]
15]
0 1 2 3 4 5 6 ... 19
Fctn/ASE
Dev. index Feature index Sw. id.
0x11 id. [0 .. Results
[1 .. 255] [1 .. 254] [1 .. 15]
15]
The device index, feature index, function identifier, and software identifier are always returned unchanged.
Note that there is no requirement to implement partial support. Each feature designer is free to decide if "partially correct" parameters
should return and error or be "partially supported." However, if partial support is implemented, then the parameters must be returned
as supported.
Broadcast events
A broadcast event is an notification sent by an HID++ 2.0 device/receiver, which is not destined to any particular software
(note that it might or might not be linked to a previously-received function). Within a given feature, each broadcast event
is defined by an broadcast event identifier. Broadcast events have up to 3 or 16 bytes of data.
IRoot
The entry point feature which is always at index 0.
GetFeature
Summary
Given a desired feature ID, returns its index (reference) in the feature table.
Parameters
featureID [16bits] The ID of the desired feature. The ID 0 is forbidden (root feature ID)
Returns
featureIndex [8bits] The one based feature index in the feature table, 0 if not found
featureType [2bits] This value is also provided in IFeatureSet.
Errors
No specific error
Remarks
The feature table is one based. Index 0 is forbidden (root index or not found value)
An obsolete feature is a feature that has been replaced by a newer one, but is advertized in order for older SWs to still
be able to support the feature (in case the old SW does not know yet the newer one).
A SW hidden feature is a feature that should not be known/managed/used by standard user SW
Request
0 1 2
featureID:MSB featureID:LSB N/A
Response
0 1 2
featureIndex featureType N/A
SW Description:
The Root feature is used by the software to determine if an unknown device is HID++ 1.0 or 2.0. The GetProtocolVersion is a feature of
the RootFeature.
Once HID++ 2.0 is confirmed there are 2 main types of software implementations which will use the Root feature to interface with a
device :
IFeatureSet
The feature set feature which enumerates features.
GetCount
Summary
Returns the number of features contained in the set, not including the root feature.
Parameters
None
Returns
count [8bits] The number of features in the set, not including the root feature.
Errors
No specific error
GetFeatureID
Summary
Given a feature index returns its ID
Parameters
featureIndex [8bits] The one based feature index in the feature table.
Returns
featureID [16bits] The ID of the feature
featureType [2bits] This value is also provided in IRoot.
Errors
OutOfRange [8bits] If index > Count
Remarks
An obsolete feature is a feature that has been replaced by a newer one, but is advertized in order for older SWs to still
be able to support the feature (in case the old SW does not know yet the newer one).
A SW hidden feature is a feature that should not be known/managed/used by standard user
Request
0 1 2
featureIndex N/A
Response
0 1 2
featureID:MSB featureID:LSB featureType
Example
SW Description:
- Features which are flagged with the "SW hidden" features are completely ignored (skipped) unless a an override for a specific feature
ID (and possible device model) becomes necessary.
Typical implementation will first query the # of features and then call GetFeatureID for each index from 1 to Count. Software will store
this information in a file (cache) and will only repeat this when the cache is no longer in synch with the device (e.g. if the device
firmware version has changed since the creation of the current cache).
0x0003 LONG Get FW version, build + protocol_specific_info
[0x0003]IFirmwareInfo
entityCount = [0]GetEntityCount()
entity, protocol, version, build, dynamic_FWconf, transportLayer_specific_info = [1]GetFwInfo(entity)
IFirmwareInfo
The firmware info feature
The firmware entities represent different codes running on the same processor (main firmware and bootloader, etc.) or on
different processors.
Shall also be used by SW with FwType=0 for CacheID as information in this function represents a unique ID for a given
device/build/etc...
GetEntityCount
Summary
Returns the number of firmware and hardware entities
Parameters
None
Returns
entityCount [8bits] The number of firmware entities
Errors
None
Remarks
Response
0 1 2
entityCount N/A
GetFwInfo
Summary
Returns the firmware version. Shall also be used by SW with FwType=0 for CacheID as information in this function
represents a unique ID for a given device/build/etc...
Parameters
FwHWEntity [8bits] The firmware or hardware entity for which we want the version
Returns
FwType [4bits] The FW type parameter
enum FirmwareType:
Main application = 0 (the one that talks thru HIDpp2.0)
BootLoader =1
Hardware = 2 (used to know HW version)
Other = 3..15
FwPrefix [24bits] The ASCII prefix of the firmware entity
FwVersion [16bits] The BCD version number of the firmware entity
FwBuild [16bits] The build number of the firmware entity
XX [8bits]
transportLayer_Specific_info [up to 9 bytes] Transport layer (USB, Unifying) specific info (such as UnifyingID/PID for
instance)
Errors
OutOfRange [8bits] If index > entityCount
Remarks
Result in BCD (by analogy with the USB "bcdDevice" and for consistency with HID++ 1.0) [TBD]
Request
0 1 2
FwHwEntity N/A
[0x0005]GetDeviceNameType
nameLength = [0]GetCount()
DeviceName = [1]GetDeviceName(CharIndex)
DeviceType, deviceInterface(s) = [2]GetDeviceType()
GetDeviceNameType
get device name and type. name is also done at Unifying level.
GetCount
Summary
Returns the length of the device name that should appear in the SW. Note this does not include any termination zeros.
Parameters
None
Returns
count [8bits] The length of the device name that should appear in the SW.
Errors
No specific error
GetDeviceName
Summary
Returns a chunk of characters of the name starting from the index specified in the requested.
The size of the chunk is the entire payload of the transport packet used by the device to respond (HPPLong : 16
characters, HPPShort : 3 characters)
Parameters
CharIndex [8bits]
Returns
DeviceName Device name chunk starting at charindex.
Errors
OutOfRange (if Char Index > device name length)
Remarks
To query the device name the host first queries the length (GetCount)
GetDeviceType
Summary
Returns device type
Parameters
None
Returns
type enum:
Keyboard = 0
RemoteControl =1
NUMPAD = 2
Mouse = 3
Touchpad = 4
Trackball = 5
Presenter = 6
Receiver = 7
Errors
None
[0x1000]BatteryLevelStatus
BatteryLevel = [0]GetBatteryLevelStatus()
LevelList[] = [1]GetBatteryCapability()
Event
BatteryLevel = [0]BatteryLevelStatusBroadcastEvent()
GetBatteryLevelStatus
Returns battery status to SW
BatteryLevelStatusBroadcastEvent
Reports battery status to SW spontaneously
Report
BatteryDischargeLevel [8bits] The current level expressed in %. 0 means unknown.
BatteryDischargeNextLevel [8bits] The next level to be reported in % as the device battery discharges. If the
current level is the lowest level or if the device is charging this value is set to 0.
BatteryStatus [8bits] Enum :
0 = discharging (in use)
1 = recharging
2 = charge in final stage
3 = charge complete
4 = recharging below optimal speed
5 = invalid battery type
6 = thermal error
7 = other charging error
8..255 : invalid
Remarks
Report
byte 0 byte 1 byte 2 byte 3..15
BatteryDischargeLevel BatteryDischargeNextLevel BatteryStatus n/a
GetBatteryCapability
Summary
Returns the static capability information about the device.
Parameters
None
Returns
NumberOfLevels [8bits] The number of levels the device is capable of reporting to the SW. Min : 2 - Max :
100.
If number of levels < 10 or if mileage is disabled then report are mapped to 4 levels this
way.
0%->10% critical
11%->30% low
31%->80% good
81%->100% full
i.e. to report battery low, FW send 25%, to report battery good, FW send 50%.
Flags [8bits]
bit 0 : Disable battery OSD
bit 1 : Enable mileage calculation. This flag is ignored by the SW if NumberOfLevels is
less than 10.
bit 2 : Rechargeable
bit 3 - 7 : must be set to zero.
NominalBatteryLife [16bits] Defined as Duration Type . As of today, this is only used when battery
mileage is enabled.
This could be the advertized battery life.
BatteryCriticalLevel [8bits] in % only used when battery mileage is enabled.
[0x1B00]SpecialKeysMSEButtons
ctrlIDCount = [0]GetCount()
ctrlIDIndex+flags list = [1]GetCtrlIDInfo(ctrlIDIndex)
Event
ctrlIDIndexPressedList = [0]ControlIDBroadcastEvent()
SpecialKeysMSEButtons
manages all SpecialKeys listed here:
Control ID table
Control Task Assignments
This feature is the engine enabling to manage of all FnKeys, HotKeys & MSE buttons.
GetCount
Summary
Returns the number of Keys and/or MSE Buttons defined.
Parameters
None
Returns
count [8bits] The number of Control IDs in the list.
Errors
No specific error
GetCtrlIDInfo
Summary
Returns a ctrl_ID and ctrl_Task indexes pointing towards tables defined below.
Concretely, let's assume a device with 7 controls which I will call A,B,C,D,E,F,G :
- GetCtrlIDInfo( 0 ) returns A
- GetCtrlIDInfo( 3 ) returns D
- GetCtrlIDInfo( 6 ) returns G
Parameters
ctrlIDIndex [8bits]
Returns
ctrl_ID_Index [16bits] ctrl_ID_Indexes
ctrl_Task_Index [16bits] ctrl_Task_Indexes
flags [8bits] field
*(1): Use this bit for any function trigged by a mouse button, so it will appear in the mouse TAB of SetPoint. This
includes volume +/-, Search, etc...
For bits 3 to 0 only the following values are valid : 0001 (Mouse button), 0010 (Fn Key), 0100 (Hot key), 1010 (Fn
Key invertible).
Note : A control ID wich would have the re-programmable bit to NO and the task ID "generic control" 72 () would
be equivalent to not report this control ID in the list.
Errors
OutOfRange (if CtrlID Index > keymsebuttoncount)
Request
byte 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 byte
15
Control
ID index N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A
Response
byte 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 byte
15
Desired/ Desired/
Sent/FW Sent/FW SW SW
Control_I Control_ Control_ Control_ Flags N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A
D MSB ID LSB Task Task
MSB LSB
ControlIDBroadcastEvent
Summary
This event is used to only report the following specific control IDs for which the native report is not sufficient or
does not exist :
Control ID's which do not have a make/break type of HID report (LC type. See : ). Note that in this case the
device must report both the linear control HID usage and this notification.
Control ID's mapped to generic HID buttons (Usage Page 0x09) except if they are generic mouse buttons or if
the device does not have any HID++ interface.
e.g. :
If Gadgets (d33) is used on a Unifying device or a corded device which has HID++ collections it should report
0x0021 (d33) in the ControlIDBroadcastEvent notification.
If Gadgets (d33) is used on a USB corded keyboard which does NOT have any HID++ collection (standard
PID) then it should report this key as generic button 0x019F
All other control IDs should NOT use this notification and always be reported in their respective HID interface as
defined in the control ID specification table.
Event data
The report contains an array of the applicable (see above) control IDs of the currently pressed controls
(keys/buttons). Each control ID is encoded on 2 bytes in big endian (MSB first).
When a control is released a report where this control ID is no longer present. Inactive value is 0x0000.
A maximum of 4 special control IDs can be pressed simultaneously.
All bytes outside of the array should be ignored.
The example below shows a sequence of reports with 2 control IDs pressed and released :
byte 0 1 2 3 4 5 6 7 bytes
8..15
Control 1 ID
Control 1 ID MSB 0 0 0 0 0 0 n/a
LSB
byte 0 1 2 3 4 5 6 7 bytes
8..15
Control 1 ID Control 2 ID Control 2 ID
Control 1 ID MSB 0 0 0 0 n/a
LSB MSB LSB
byte 0 1 2 3 4 5 6 7 bytes
8..15
Control 2 ID
Control 2 ID MSB 0 0 0 0 0 0 n/a
LSB
Control ID 2 released (break)
byte 0 1 2 3 4 5 6 7 bytes
8..15
n/a
0 0 0 0 0 0 0 0
Event
Status, Request, Reason = [0]WirelessDeviceStatusBroadcastEvent()
WirelessDeviceStatusBroadcastEvent
Sent by the device after a power-on reset
Report
Status [8bits] 0x00 no status
0x01 reconnection
0x02..0xFF reserved
Request [8bits] 0x00 no request
0x01 software reconfiguration needed
0x02..0xFF reserved
Reason [8bits] 0x00 unknown
0x01 power-switch activated
0x02..0xFF reserved
Remarks
This notification is always enabled since it must be sent by a device after a power-on reset.
Report
0 1 2
Status Request Reason