1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> 4<META name="GENERATOR" content="Microsoft FrontPage 5.0"> 5<META http-equiv="Content-Style-Type" content="text/css"> 6<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css"> 7<base target="main"> 8<title>KBD API Introduction</title> 9</head> 10 11<body> 12 13<h1>KBD API Introduction</h1> 14 15<h2>Introduction</h2> 16<p> 17The KBD library provides an API to interface with USB keyboards connected to the Wii console. It provides both synchronous (polling) and asynchronous (interrupt callback) methods of retrieving keystrokes. The keystroke API provides access both to generated Unicode (UTF-16) characters and to low-level USB HID key codes.</p> 18<p><font color="ff0000"><b>This library makes use of the USB HID library. With SDK 3.2 and later versions, programs that use this library must use the extended firmware.</b></font></p> 19<p> 20The KBD library provides support for the following. 21<ul> 22<li>Synchronous and asynchronous access to Unicode characters generated by simple keystrokes (e.g., "a", "A"). For complex keystrokes such as accented characters, see the Key Processing (KPR) library. 23<li>Synchronous and asynchronous access to HID codes generated by physical key presses and releases. 24<li>Asynchronous calls for keyboard events such as keyboard connection (attach) and disconnection (detach). 25<li>Keyboards from different countries. 26<li>Up to four keyboard channels. A unique channel is associated with each attached keyboard. 27<li>Keyboard LED support. 28<li>Keyboard repeat rate support. 29<li>Accessibility option to make Shift, Control, and other keys work as toggles. 30</ul> 31</p> 32<p>We have included sample demo programs that demonstrate how to use the KBD library under the path <code>$REVOLUTION_SDK_ROOT/build/demos/kbddemo/</code>.</p> 33<p>API function declarations, function types, and constants are in the <code>$REVOLUTION_SDK_ROOT/include/revolution/kbd.h</code> header file.</p> 34<p> The kbd.h header file includes the support header files <code>$REVOLUTION_SDK_ROOT/include/revolution/kbd/kbd_key_defs.h</code> and <code>$REVOLUTION_SDK_ROOT/include/revolution/kbd/kbd_hid_codes.h</code>.</p> 35 36 37<h2>Architecture</h2> 38<p>The following diagram describes the main architecture of the keyboard library.</p> 39<center><img src="kbd_architecture.gif" width="455" height="398"></center> 40<ol> 41<li><p>Starting at the bottom, when a key is pressed or released on the keyboard, the <i>USB HID driver</i> calls the <i>KBD Driver</i> and passes it a HID report.</p></li> 42<li><p>The <i>KBD Driver</i> module processes the report and turns it into one or more up/down key (<code>KBDHIDCode</code>) events.</p></li> 43<li><p>For each key event, the <i>KBD Driver</i> module calls the <i>HID-to-Unicode Translate</i> module, the <i>Mod Processing</i> module, and the <i>User Key Callback</i> (in that order).</p></li> 44<li><p>Given the current keyboard <i>Mod State</i> and country setting, the <i>HID-to-Unicode Translate</i> module converts the <code>KBDHIDCode</code> into a <code>KBDUnicode</code>.</p></li> 45<li><p>The <i>Mod Processing</i> module looks to see if the <code>KBDUnicode</code> represents a modifier <i>action</i> and changes the current keyboard <i>Mod State</i> accordingly.</p> 46<p>As an example, if the key code 0xE1 (<code>KBD_HID_Left_Shift</code>) is pressed, it is translated into the (private) Unicode value <code>KBK_Mod_Shift</code>, and <i>Mod Processing</i> sees this Unicode value and then makes sure the <code>KBD_MS_SHIFT</code> modifier is turned on in the <i>Mod State</i>.</p> 47</li> 48<li><p>The <i>KBD Driver</i> handles key repeat processing. Key repeat sets a timer to send additional key down events through the <i>KBD Driver</i>.</p> 49<li><p>The <i>User Key Callback</i> is called with both the <code>KBDHIDCode</code> and the <code>KBDUnicode</code>. In addition, it is also given the key up/down state (<code>KBDKeyMode</code>) as well as the current keyboard <i>Mod State</i> (<code>KBDModState</code>).<p></li> 50<li><p>The <i>User Key Callback</i> may also use the <i>Translate</i> module as well as access or change the current <i>Mod State</i>. It can even alter the key event fields.</p></li> 51<li><p>The <i>KBD Driver</i> finally stores the key event in an internal queue for use by the synchronous character API.<p></li> 52</ol> 53<p>Not shown in the diagram are keyboard attach/detach event processing or the synchronous keyboard API.</p> 54<p>The KBD library does not maintain the keyboard LED state. The LEDs may be set to match the current keyboard modifier state by calling the <code><a href="KBDSetLeds.html">KBDSetLeds</a></code>, <code><a href="KBDSetLedsAsync.html">KBSetLedsAsync</a></code>, or <code><a href="KBDSetLedsRetry.html">KBDSetLedsRetry</a></code> function. The modifier state <code>KBD_MS_SCROLL_LOCK</code> is included to allow for setting the scroll lock LED. It is normally toggled by the key mapped to <code>KBK_Scroll_Lock</code>.</p> 55<h2>High-Level Unicode Interface</h2> 56<p> 57The keyboard driver may be used at a high level by ignoring the HID codes returned and paying attention only to the Unicode values returned. In addition, the application should ignore key up events and modifier key presses. To simplify this processing, use existing macros. Refer to <a href="KBDKeyEvent.html"><code>KBDKeyEvent</code></a> for more details.</p> 58<p>When a synchronous call is made to the <code><a href="KBDGetKey.html">KBDGetKey</a></code> function, all keys pressed since its last invocation are returned. If no keys have been pressed since it was last called, NULL is returned. We also provide a function, <code><a href="KBDSetKeyCallback.html">KBDSetKeyCallback</a></code>, to register a callback function that will be called with a pointer to a <code><a href="KBDKeyEvent.html">KBDKeyEvent</a></code> that contains key event information.</p> 59<p>Keyboard modifier HID keys are mapped to special Unicode values that affect the modifier state. Some modifier states, such as <code>KBD_MS_SHIFT</code> and <code>KBD_MS_NUM_LOCK</code>, then affect how other keys are looked up in the keymaps. Other modifier states, such as <code>KBD_MS_ALT</code> and <code>KBD_MS_GUI</code>, are just passed along with the base character. The modifier state <code>KBD_MS_SHIFTED_KEY</code> determines whether the unshifted (base) or shifted key is sent when a combination of modifier keys is pressed (for example, Shift and Alt). This is off by default, and the application should set this modifier bit if it requires the shifted key. This bit also overrides the Num Lock state when set.</p> 60<h3><a name="KBDUnicode">KBDUnicode Values</a></h3> 61<p>All keys are provided with a <code>KBDUnicode</code> value. For the function keys, editing keys, arrow keys, and other special keys, custom (private) Unicode values are used. These private Unicode values are all in the range <code>0xf000-0xf1ff</code>, and they should <I>never</I> be used for external data exchange. They should also not be confused with private Unicode values that may be used elsewhere in the Revolution SDK or other SDKs. The KBD private Unicode values should only be used with keyboard-related functions.</p> 62<p>You may use the macro <code>KBD_UC_IS_PRIVATE</code> to determine if a <code>KBDUnicode</code> value is in the <code>0xf00-0xf1ff</code> range.</p> 63<code><pre>#define KBD_UC_IS_PRIVATE(uc) (((uc)>=0xf000 && (uc)<=0xF1FF) || ((uc)==0xFFFF))</pre></code> 64<p>For broader application, you may also define macros such as these below (they are not defined in <code>kbd.h</code>).</p> 65<code><pre>// Indicate if a generic Unicode value is private (according to Unicode standard) or not 66#define UNICODE_IS_PRIVATE(uc) (((uc)>=0xE000 && (uc)<=0xF8FF) || ((uc)>=0xFFF0)) 67#define UNICODE_IS_REGULAR(uc) (((uc)<0xE000) || ((uc)>0xF8FF && (uc)<0xFFF0)) 68</pre></code> 69<p>The KBD private Unicode values are defined in <code>kbd_key_defs.h</code>. Regular Unicode values can be found at the <a target="new" href="http://www.unicode.org/charts/lastresort.html">Unicode</a> website.</p> 70<p>The keys on the numeric keypad (the operator symbols and the numbers when Num Lock is on) use Unicode values that are the normal ASCII/Unicode value plus <code>0xf100</code>. Use the <code>KBD_UC_IS_KP_REG_KEY</code> macro to check if a key is within this range. Also, use the <code>KBD_KP_REG_KEY_TO_ASCII</code> macro to convert it into an ASCII/Unicode value.</p> 71<code><pre>#define KBD_UC_IS_KP_REG_KEY(uc) (((uc)>=0xf100) && ((uc)<=0xf13f)) 72#define KBD_KP_REG_KEY_TO_ASCII(uc) ((uc)&0x3f)</pre></code> 73<p>The arrow and editing keys on the keypad are also distinguished from those that are stand-alone keys. The stand-alone keys are in the range <code>0xf180-0xf1bf</code>, and the keypad versions are in the range <code>0xf140-0xf17f</code> (a difference of <code>0x40</code>). For example:</p> 74<code><pre>KBK_Insert: 0xf1b0 75KBK_Keypad_Insert: 0xf170 (0x40 less) 76KBK_Keypad_0: 0xf130 (0x40 less) (KBK_Keypad_0 is same key as KBK_Keypad_Insert) 77'0': 0x0030 (0xf100 less)</pre></code> 78<p>The keys <code>KBK_Keypad_0</code> - <code>KBK_Keypad_9</code> and <code>KBK_Keypad_Period</code> are all mapped in a similar way. Note that while <code>KBK_Keypad_Comma</code> is also defined (for use in country maps where it applies), the code for <code>KBK_Keypad_Delete</code> (on the same key) and <code>KBK_Delete</code> are still based on the ASCII code for period.</p> 79<p>The <code>KBD_UC_IS_KP_NUM_NL_KEY</code> macro indicates if a key is on the numeric keypad <I>and</I> was pressed while Num Lock was on. Also, <code>KBD_UC_IS_KP_NUM_UL_KEY</code> indicates if a key is on the numeric keypad <I>and</I> was pressed while Num Lock was off. The macro <code>KBD_KP_NUM_UL_KEY_TO_KP_NUM_NL_KEY</code> can be used to convert the second to the first.</p> 80<code><pre>#define KBD_UC_IS_KP_NUM_NL_KEY(uc) (((uc)>=KBK_Keypad_0 && ((uc)<=KBK_Keypad_9))) 81#define KBD_UC_IS_KP_NUM_UL_KEY(uc) (((uc)>=KBK_Keypad_Insert && ((uc)<=KBK_Keypad_Page_Up))) 82#define KBD_KP_NUM_UL_KEY_TO_KP_NUM_NL_KEY(uc) ((KBDUnicode)((uc)-0x40))</pre></code> 83<p>The Backspace, Tab, and Escape keys are assigned to private Unicode values. These values are the standard ASCII/Unicode values plus <code>0xf1c0</code>. <code>KBD_UC_IS_CTRL_KEY</code> indicates whether a given key is such a value. Additionally, <code>KBD_CTRL_KEY_TO_ASCII</code> converts values into ASCII/Unicode.</P> 84<code><pre>#define KBD_UC_IS_CTRL_KEY (((uc)>=0xf1c0) && ((uc)<=0xf1df)) 85#define KBD_CTRL_KEY_TO_ASCII(uc) ((uc)&0x1f)</pre></code> 86 87<h2>Low-Level USB HID Key Code Interface</h2> 88<p> 89For applications that would like to deal with the keyboard at a lower-level and access individual physical key presses and release, this can be done as well, since all events are passed through using the APIs described above.</p> 90<p>The application can take over some functions normally done by the KBD Driver. It can interpret the HID codes (either by using its own maps or by calling <code><a href="KBDTranslateHidCode.html">KBDTranslateHidCode</a></code>). It can also independently track and alter the modifier state. (Call the <code><a href="KBDSetLockProcessing.html">KBDSetLockProcessing</a></code> function to disable modifier key processing for the driver.) When key event information has been changed by a callback, the changed information will be placed in the internal queue and used by the synchronous API.</p> 91<p>USB HID codes are intended to be mostly device-independent, meaning that the key in a given position should return the same code regardless of what is printed on that key, but there are some exceptions. The following diagram and table summarize the differences between these codes and a normal keyboard. However, be aware that exceptions not included here may occur.</p> 92<p><img src="kbd_usb_layout.gif" width="874" height="254"></p> 93<TABLE BORDER=1 CELLPADDING=3 CELLSPACING=0> 94<TR bgcolor="#c0c0c0"> 95<TD>Keyboard Model</TD> 96<TD>HID codes unique to this keyboard</TD> 97<TD>HID codes missing from this keyboard</TD></TR> 98<TD bgcolor="#ff9966">US</TD> 99<TD><code>0x31</code> (backslash/vertical bar)</TD> 100<TD><code>0x32</code>, <code>0x64</code>, <code>0x66-0xDF</code></TD></TR> 101<TD bgcolor="#00ff00">European</TD> 102<TD><code>0x32</code> (near enter key; symbols vary)<br> <code>0x64</code> (near left shift key; symbols vary)</TD> 103<TD><code>0x31</code>, <code>0x66-0xDF</code></TD></TR> 104<TD bgcolor="#ffff00">Japanese</TD> 105<TD><code>0x32</code> (right bracket/right brace)<br> <code>0x87</code> (backslash/underline/ro/broken bar)<br> <code>0x88</code> (katakana/hiragana)<br> <code>0x89</code> (yen/vertical bar)<br> <code>0x8A</code> (henkan)<br> <code>0x8B</code> (muhenkan)<br> <code>0x94</code> (see <b>note</b> below)</TD> 106<TD><code>0x31</code> (see <b>note</b> below)<br> <code>0x64</code></TD></TR> 107</TABLE> 108<p><b>Note:</b> 109<ul> 110<li>We have found a model of Japanese keyboard that provides code <code>0x31</code> in place of code <code>0x32</code>, as well as code <code>0x94</code> in place of code <code>0x35</code> (hankaku/zenkaku/kanji, light blue <img src="lightbluebox.bmp"> key above). These keys are remapped to their expected values internally in the KBD Driver.</li> 111<li>Although codes <code>0x92</code> (katakana) and <code>0x93</code> (hiragana) are defined in the HID specification, we've not yet observed any keyboards that transmit these codes.</li> 112<li>HID modifier keys are shown in purple <img src="purplebox.bmp" width="12" height="12">. They are assigned the above codes within the KBD driver.</li> 113</ul> 114<p>For a description of individual HID codes, refer to <CODE>kbd_hid_codes.h</CODE> or to the HID Usage Table for keyboards at <a target="new" href="http://www.usb.org/developers/hidpage/">http://www.usb.org/developers/hidpage/</a>.</p> 115<p>To avoid these irregularities, an application key callback should perhaps immediately translate HID key codes into <code>KBKUnicode</code> values using the function <CODE><a href="KBDTranslateHidCode.html">KBDTranslateHidCode</a></CODE>. There are few situations in which raw HID key codes are absolutely required.</p> 116<p>When mapping user input to key presses, an application designer must consider whether multiple keys may be pressed simultaneously and whether or not a keyboard can recognize such key presses without problems. A problem known as "ghosting" will sometimes occur when three or more keys are pressed at once. This problem will cause the keyboard to recognize keypresses that are not made by the user. Also, some multiple key combinations may be undetectable by the keyboard electronics. Different keyboards will have different issues with multiple key presses. For most normal keyboard input, this should not be a problem. However, this can be a problem when you attempt to use the keyboard as a controller pad, or when you try to detect an unsupported combination of modifier keys.</p> 117<h2>Library Flow</h2> 118<p> 119The KBD library is dependent on the HID library. Initialize the HID library by calling the <code>HIDOpenAsync</code> function prior to making any KBD API calls. 120<p> 121After the HID library has been initialized, call the <a href="KBDInit.html"><CODE>KBDInit</CODE></a> function to initialize the KDB library. You must call this function before using the USB keyboard library. After you have called <a href="KBDInit.html"><CODE>KBDInit</CODE></a>, you must call one of the region initialization functions (<a href="KBDInitRegionUS.html"><code>KBDInitRegionUS</code></a>, <a href="KBDInitRegionJP.html"><code>KBDInitRegionJP</code></a>, or <a href="KBDInitRegionEU.html"><code>KBDInitRegionEU</code></a>) to configure the keyboard map that is appropriate for the given market (region). You must call at least one of these region initialization functions , but it is acceptable to call more than one. 122<p> 123Once callbacks have been registered, keyboard events will result in interrupts and the appropriate application callback will be called. Note that because callbacks run with interrupts disabled, they should not do anything that requires a significant amount of time. If necessary, they can trigger a thread to handle any procedures that cannot run with interrupts disabled.</p> 124<p> 125Alternatively, you may call a synchronous API to examine keyboard input. The synchronous API should be called frequently enough to prevent queue overflow. It may be a good idea to call this API in a loop until it returns with a null key value.</p> 126<p> 127To exit the KBD library, the <a href="KBDExit.html"><code>KBDExit</code></a> function should be called. Calling this function will disable the registered callback functions, and keyboard events will be ignored. We recommend turning off all keyboard LEDs before calling the <a href="KBDExit.html"><code>KBDExit</code></a> function. When the OS shuts down or resets, it will normally try to turn off all keyboard LEDs, but it cannot do this if the <a href="KBDExit.html"><code>KBDExit</code></a> function has already been called.</p> 128<p> 129After calling the <code>KBDExit</code> function, call the <code>HIDCloseAsync</code> function to close the HID library. 130</p> 131<h2>Notes</h2> 132<p>You must be careful when using the KBD library to avoid sending too many USB messages. If you saturate the USB bus, you may prevent other devices (such as the Wii Remote) from using USB, and you may also prevent key presses from getting through.</p> 133<p>The following functions may result in a call that sends an LED message over USB:</p> 134<ul> 135<li><code><a href="KBDSetLeds.html">KBDSetLeds</a></code></li> 136<li><code><a href="KBDSetLedsAsync.html">KBDSetLedsAsync</a></code></li> 137<li><code><a href="KBDSetLedsRetry.html">KBDSetLedsRetry</a></code></li> 138</ul> 139<p> 140Additionally, the <code>KBSSetLeds</code> function is not recommended because it will block if the keyboard fails to ACK on the USB bus. 141<p>For more details, refer to the documentation for these commands. 142</p> 143 144<h2>Limitations</h2> 145<p>These are the current limitations for keyboard support.</p> 146<ul> 147<li>The following languages are currently supported: International English, Canadian English, Canadian French, Danish, Finnish, French, German, Greek, Italian, Japanese, Latin American Spanish, Dutch, Norwegian, Portuguese, Spanish, Swedish, British English, and American English. 148</li> 149<li>The Num Lock mode of keypad keys generates a different Unicode from the normal numbered keys. Refer to <code><a href="KBDKeyEvent.html">KBDKeyEvent</a></code> for more details.</li> 150<li>The KBD library uses only the Boot-mode report protocol from the USB HID specification. As a result, non-standard keyboard keys, such as media control, are not recognized.</li> 151</ul> 152 153<h2>Revision History</h2> 154<p> 1552008/09/26 Changed the library flow so the functions are called in the order of <CODE>HIDOpenAsync</CODE>, then <CODE>KBDInit</CODE>, and then region initialization functions.<br> 156</p> 157<hr> 158 159<hr><p>CONFIDENTIAL</p></body> 160</HTML>
