Enhanced Keyboards and Windows

On This Page

	Enhanced Keyboards: New HID Usages and Legacy Issues
	Standard USB HID Keyboard Implementation
	Improper or Missing BIOS Support for HID Keyboards
	Windows Security and HID Keyboards
	New USB HID Usages for Enhanced Keyboard Features
	New PS/2 Scan Codes for Enhanced Keyboard Features
	Software Application Support
	Design Guidelines for USB HID Keyboards
	Sample Report Descriptors for USB HID Keyboard with Enhanced Features
	APPCOMMANDs and Windows Me
	Call to action for Windows support for enhanced keyboard features:

Enhanced Keyboards: New HID Usages and Legacy Issues

Over the last few years, there has been a trend in the industry toward adding enhanced features to the standard keyboard. These new features--typically related to multimedia, web browsing, application launch, and power management capabilities--represent a departure from the traditional use of a simple keyboard. They present certain challenges in terms of device firmware design, BIOS support, and operating system support.

To support new enhanced features on a keyboard in a standardized fashion, the USB Human Interface Device (HID) Working Group has adopted several new HID usages. This firmware standardization paves the way for standardized operating system support. Similarly, Microsoft and other vendors have defined PS/2 Set 1 and Set 2 scan codes for legacy keyboard keys that correspond to a number of these new USB HID usages.

This article presents the challenges and suggested solutions for implementing new enhanced keyboard features under Microsoft Windows 2000, Windows XP, and Windows Millennium Edition (Windows Me). It is assumed that the reader is familiar with the USB HID Class and HID Usage Tables specifications (version 1.11), and with the keyboard HID report descriptor examples in these specifications.

NOTE: For the reference sources cited in this article, see the "Call to Action" at the end of the article.

Top of page

Standard USB HID Keyboard Implementation

A standard USB HID keyboard implementation is best described by the keyboard boot report descriptor in the HID firmware specification. This report descriptor defines a Keyboard Application Collection that declares keyboard controls defined by usages in the Keyboard Page and the LED Page. When Windows 2000 or Windows Me enumerates this type of device for the first time:

The following sections describe special considerations for adding enhanced features to a USB HID keyboard.

Top of page

Improper or Missing BIOS Support for HID Keyboards

For a HID keyboard to work prior to operating system startup, in operating system safe mode, and so on, the system BIOS must provide support for the keyboard. To simplify the amount of code in the BIOS, special boot protocols have been specified for HID keyboards and mice (see the HID Class specification for details about these boot protocols).

HID keyboards that support the boot protocol indicate this in their USB descriptors. A USB HID-aware BIOS that enumerates connected keyboards should issue a HID Set_Protocol request to tell the keyboards to use the special keyboard boot protocol instead of the default report protocol.

For a simple keyboard, the default report protocol is typically identical to the boot protocol, so this request has little effect on the overall operation of the keyboard. If the keyboard is equipped with enhanced features, then the default report protocol may not be the same as the boot protocol, so the keyboard must receive the special Set_Protocol request in order to work properly with the BIOS.

There are cases when BIOSes in many USB-capable systems either do not support USB HID keyboards and mice properly, or they do not support them at all, but upgrades are becoming available. A USB HID-aware BIOS should be able to enumerate both the USB input devices connected directly to the USB root ports and also those connected by way of USB hubs. In addition, the BIOS should always issue the proper HID Set_Protcol requests to set the input devices to the respective boot protocols.

However, there is a HID firmware solution that will work with a USB HID-aware BIOS that does not issue the HID Set_Protocol request. The solution is to implement two HID interfaces on separate endpoints in a USB composite-device fashion. One HID interface implements a standard HID keyboard with identical report and boot protocols; the other HID interface implements all the new enhanced keyboard features--for example, the multimedia and web browsing keys, the power keys, and so on. If done this way, the standard HID keyboard on the first interface will always work, regardless of whether the BIOS issues a Set_Protocol request.

Top of page

Windows Security and HID Keyboards

Note: These system security requirements do not apply to Windows Me.

In Windows 2000/Windows XP, system security requirements mandate that the keyboard HID mapper driver, Kbdhid.sys, be the only driver allowed access to input reports from Keyboard Application Collections. This means that if the translation from a particular HID usage to a PS/2 Set 1 scan code fails, then no other software in the system can be made aware of this input event. As a result, the event will be lost.

The solution to this problem is also to declare the enhanced keyboard features in separate HID Application Collections, but not in the Keyboard Application Collection.

Hardware and software vendors should be aware that the Windows security restrictions apply to all Keyboard, Keypad, Mouse, and Pointer Application Collections. The security restrictions do not apply to any other types of HID Application Collections.

Top of page

New USB HID Usages for Enhanced Keyboard Features

For a complete list of current HID usages that are appropriate for enhanced multimedia, web browsing, and application launch functionality, see the Consumer Page (Page 0x0C) in the HID Usage Tables, Version 1.11 specification. A number of new usages have been added since publication of the HID Usage Tables, Version 1.0 specification.

Windows 2000, Windows XP, and Windows Me provide built-in support for a certain number of Consumer Page audio control usages (see the details in HID Audio Controls and Windows).

These versions of Windows, however, also provide built-in support for additional enhanced keyboard features by supporting a certain number of the new Version 1.11 Consumer Page usages as well. Note that in order for Windows to interpret Consumer Page HID controls correctly, these must be specified in a Usage Page (Consumer), Usage (Consumer Control) Application Collection.

Table 1 provides the complete list of Consumer Page HID controls that Windows supports.

Top of page

New PS/2 Scan Codes for Enhanced Keyboard Features

To support enhanced features in PS/2 keyboards, new scan codes must be allocated in both Scan Set 1 and Scan Set 2. PS/2 keyboards send Scan Set 2 scan codes to the i8042 keyboard controller in the host system, and the controller then translates these scan codes into Scan Set 1 scan codes for consumption by the BIOS and the operating system.

Table 2 specifies the equivalent PS/2 scan codes Microsoft has allocated for a number of the HID usages in Table 1.

Table 1. Consumer Page HID Controls Supported in Windows 2000/Windows XP and Windows Me

*These controls are currently supported in Windows Me only.

IMPORTANT: Several standards exist for PS/2 scan codes. In addition to the IBM standard, the Open Architecture Developer's Group (OADG) has published standards for the DOS/V keys on Japanese keyboards, and Microsoft has published standards for the Windows keys and for Power Management keys (Sleep, Wake-up, Power down). Details on the Power Management keys are provided in Input Device Class Power Management Reference Specification.

Table 2. PS/2 Scan Codes Supported in Windows 2000/Windows XP and Windows Me

*These controls are currently supported in Windows Me only.

For a list of keyboard HID usages and related PS/2 scan codes, see "Key Support, Keyboard Scan Codes, and Windows".

Top of page

Software Application Support

The new HID usages and PS/2 scan codes specified in this article will, under Windows, work within the context of a supporting software application. For example, Internet Explorer must be the application in focus for the web-browsing buttons to work, and so on.

Supporting software applications need to respond to new WM_APPCOMMAND messages that were introduced in Windows 2000 and Windows Me and are now used to notify applications of application-specific command events. The following applications provided with Windows are WM_APPCOMMAND-enabled:

Software application developers should consult the Microsoft Platform SDK for additional information and details about WM_APPCOMMAND.

Top of page

Design Guidelines for USB HID Keyboards

To summarize, the following design guidelines are recommended for keyboard manufacturers developing new USB/HID keyboards with enhanced features:

Note that if the keys from one report share a physical matrix with another, complications arise regarding Rollover Errors. Rollover Errors are typically only reported in the Keyboard report for the standard keyboard keys, but if the matrix is constructed such that keys not in the Keyboard Application Collection can cause a Rollover Error in the Keyboard report, or vice-versa, special handling is necessary.

Microsoft recommends that controls in non-Keyboard Application Collections be designed such that Rollover Errors cannot occur. If this is not feasible, Rollover Errors should be reported in the Keyboard report, and ignored (no data sent) in the non-Keyboard report.

If the non-Keyboard HID interface receives a HID Get_Report request, or if it supports the optional Get_Idle and Set_Idle requests and is required to send a report, then the report sent should be the last known valid state of the controls prior to the Rollover Error condition.

Top of page

Sample Report Descriptors for USB HID Keyboard with Enhanced Features

The following design sample is for a USB composite device that implements a standard keyboard on the first HID interface and enhanced keyboard features on a second HID interface.

Notice that two top-level Application Collections are implemented on the second HID interface: a Consumer Control collection that implements Volume Up, Volume Down, Mute, and WWW Home buttons, and a System Control collection that implements Sleep and Wake-up buttons.

First HID Interface Report Descriptor (keyboard report identical to the boot protocol):

Usage Page (Generic Desktop)
Usage (Keyboard)
Collection (Application)
        Report Size (1)
        Report Count (8)
        Usage Page (Keyboard)
        Usage Minimum (Keyboard LeftControl)
        Usage Maximum (Keyboard RightGUI)
        Logical Minimum (0)
        Logical Maximum (1)
    Input (Data, Variable, Absolute)
        Report Count (1)
        Report Size (8)
    Input (Constant)
        Report Count (5)
        Report Size (1)
        Usage Page (LEDs)
        Usage Minimum (Num Lock)
        Usage Maximum (Kana)
    Output (Data, Variable, Absolute)
        Report Count (1)
        Report Size (3)
    Output (Constant)
        Report Count (6)
        Report Size (8)
        Logical Minimum (0)
        Logical Maximum (255)
        Usage Page (Keyboard)
        Usage Minimum (0)
        Usage Maximum (255)
    Input (Data, Array)
End Collection

This first HID interface will issue 8-byte input reports that are identical to the standard keyboard boot protocol report as documented in the HID Class Version 1.11 specification. This interface also allows the host system to turn the respective LED state indicators on and off as appropriate, as specified by the 1-byte output report.

Table 3. Keyboard Input Report

Table 4. Keyboard Output Report

Second HID Interface Report Descriptor:

Usage Page (Consumer)
Usage (Consumer Control)
Collection (Application)
        Report ID (1)
        Usage (Volume Increment)
        Usage (Volume Decrement)
        Logical Minimum (0)
        Logical Maximum (1)
        Report Size (1)
        Report Count (2)
    Input (Data, Variable, Absolute, Preferred)
        Usage (Mute)
        Logical Minimum (0)
        Logical Maximum (1) 
        Report Size (1)
        Report Count (1)
    Input (Data, Variable, Relative, Preferred)
        Usage (AC Home)
    Input (Data, Variable, Relative, Preferred)
        Report Count (4)
    Input (Constant)
End Collection

Usage Page (Generic Desktop)
Usage (System Control)
Collection (Application)
        Report ID (2)
        Usage Minimum (System Sleep)
        Usage Maximum (System Wake Up)
        Report Count (2)
    Input (Data, Variable, Relative, Preferred)
        Report Count (6)
    Input (Constant)
End Collection

This second HID interface will issue one of two possible input reports, each distinguished by a unique Report ID, depending on what control the user is manipulating.

Table 5. Consumer Control Input Report

Table 6. System Control Input Report

Top of page

APPCOMMANDs and Windows Me

A number of APPCOMMANDs have been defined in Windows Me. A list of these can be found in Winuser.h. These APPCOMMANDs have special registry keys associated with each of them. Each key defines an application associated with a particular APPCOMMAND. These keys are stored in the following location.

HKLM\ Software\ Microsoft\ Windows\ CurrentVersion\ Explorer\ AppKey \<NUM>
HKCU\ Software\ Microsoft\ Windows\ CurrentVersion\ Explorer\ AppKey \< NUM>

Replace <NUM> with the appropriate numeric value for the APPCOMMAND as defined in Winuser.h. The value name stored inside each key should correspond to one of the following three choices:

This data stored in the registry value field must be in the form of a string (REG_SZ). The registry keys are searched in the current user hive of the registry first. If a match is not found in this section, the local machine section is searched. It must be ensured that the registry keys do not contain incorrect values, which might cause the key to become useless.

Changing the value stored inside one of these registry keys does not require a reboot. Windows Millennium Edition, by default, contains five keys stored under the local machine hive. These keys contain the defaults associated with the corresponding APPCOMMAND and must not be removed.

Vendors can write their own user interface to program the registry keys or use INF files to install special entries as defaults.

Top of page

Call to action for Windows support for enhanced keyboard features:

Keyboard vendors should implement the design guidelines for USB HID keyboards described in this article.

OEMs should ensure that every BIOS is USB HID-aware.

References:

Top of page