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 to both the generated Unicode (UTF-16) characters and to low-level USB HID key codes.</p> 18<p> 19The KBD library provides support for the following. 20<ul> 21<li>Synchronous and asynchronous access to Unicode characters generated by simple keystrokes (for example, "a", "A"). For complex keystrokes such as accented characters, see the Key Processing (KPR) library. 22<li>Synchronous and asynchronous access to HID codes generated by physical key presses and releases. 23<li>Asynchronous calls for keyboard events such as keyboard connection (attach) and disconnection (detach). 24<li>Keyboards from different countries. 25<li>Up to four keyboard channels. A unique channel is associated with each attached keyboard. 26<li>Keyboard LED support. 27<li>Keyboard repeat rate support. 28<li>Accessibility option to make shift, control and others work as toggles. 29</ul> 30</p> 31<p>We have included sample demo programs that demonstrate how to use the KBD library under the $REVOLUTION_SDK_ROOT/build/demos/kbddemo/ path.</p> 32<p>API function declarations, types, and constants are in the <code>$REVOLUTION_SDK_ROOT/include/revolution/kbd.h</code> header file.</p> 33<p> <CODE>kbd.h</CODE> header file includes the <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> support header files.</p> 34 35 36<h2>Architecture</h2> 37<p>The following diagram describes the keyboard library's main architecture.</p> 38<center><img src="kbd_architecture.gif" width="455" height="398"></center> 39<ol> 40<li><p>Starting at the bottom, when a key is pressed or released on the keyboard, the USB HID driver calls the KBD Driver and passes it a HID report.</p></li> 41<li><p><i>KBD Driver</i> module processes the report and turns it into one or more up/down key (KBDHIDCode) events.</p></li> 42<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> 43<li><p>Given the current keyboard <i>Mod State</i> and country setting, the <i>HID-to-Unicode Translate</i> module converts <code>KBDHIDCode</code> into a <code>KBDUnicode</code>.</p></li> 44<li><p>The <i>Mod Processing</i> module checks that <code>KBDUnicode</code> represents a modifier <i>action</i> and changes the current keyboard <i>Mod State</i> accordingly.</p> 45<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>; <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> 46</li> 47<li><p>The KBD Driver handles key repeat processing. Key repeat sets a timer to send additional key down events through the <i>KBD Driver</i>.</p> 48<li><p><i>User Key Callback</i> is called with both <code>KBDHIDCode</code> and <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> 49<li><p><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> 50<li><p><i>KBD Driver</i> finally stores the key event in an internal queue for use by the synchronous character API.<p></li> 51</ol> 52<p>Not shown in the diagram are the keyboard attach/detach event processing and synchronous keyboard API.</p> 53<p>KBD library does not maintain the keyboard LED 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, it is possible to set the LEDs to match the current state of the keyboard modifier keys. The modifier state <code>KBD_MS_SCROLL_LOCK</code> is included to allow setting the scroll lock LED. It is normally toggled by the key mapped to <code>KBK_Scroll_Lock</code>.</p> 54<h2>High-level Unicode Interface</h2> 55<p> 56The keyboard driver may be utilized at a high-level by ignoring the returned HID codes and only paying attention to the returned Unicode values. In addition, the application should ignore key up events and modifier key presses. A macro has been prepared to simplify this processing. For more details, refer to <a href="KBDKeyEvent.html"><code>KBDKeyEvent</code></a>.</p> 57<p>When the <code><a href="KBDGetKey.html">KBDGetKey</a></code> function is called synchronously, the key that was pressed since the last invocation of the function is returned. NULL is returned if no key was pressed since the last invocation. 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> 58<p>Keyboard modifier HID keys are mapped to special Unicode values that affect the modifier state. Some modifier states (for example, <code>KBD_MS_SHIFT</code>, <code>KBD_MS_NUM_LOCK</code> and others) then affect how other keys are looked up in the keymaps. Other modifier states (for example, <code>KBD_MS_ALT</code>, <code>KBD_MS_GUI</code> and others) 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 (for example, Shift and Alt) is pressed. This is off by default, and the application should set this modifier bit if it wants the shifted key. This bit also overrides the Num Lock state when set.</p> 59<h3><a name="KBDUnicode">KBDUnicode Values</a></h3> 60<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 of <code>0xf000-0xf1ff</code>, and they should <b>never</b> 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. KBD private Unicode values should only be used with keyboard-related functions.</p> 61<p>You may use the <code>KBD_UC_IS_PRIVATE</code> macro to determine if a <code>KBDUnicode</code> value is in the <code>0xf000-0xf1ff</code> range.</p> 62<code><pre>#define KBD_UC_IS_PRIVATE(uc) (((uc)>=0xf000 && (uc)<=0xF1FF) || ((uc)==0xFFFF))</pre></code> 63<p>For broader application, you may also define macros such as those below (these are not defined in <code>kbd.h</code>).</p> 64<code><pre>// Indicate if a generic Unicode value is private (according to Unicode standard) or not 65#define UNICODE_IS_PRIVATE(uc) (((uc)>=0xE000 && (uc)<=0xF8FF) || ((uc)>=0xFFF0)) 66#define UNICODE_IS_REGULAR(uc) (((uc)<0xE000) || ((uc)>0xF8FF && (uc)<0xFFF0)) 67</pre></code> 68<p>KBD private Unicode values are defined in <code>kbd_key_defs.h</code>. Regular Unicode values may be found at the <a target="new" href="http://www.unicode.org/charts/lastresort.html">Unicode</a> website.</p> 69<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>. The <code>KBD_UC_IS_KP_REG_KEY</code> macro is used to check whether keys are within this range. Furthermore, the <code>KBD_KP_REG_KEY_TO_ASCII</code> macro is used to convert to an ASCII/Unicode value.</p> 70<code><pre>#define KBD_UC_IS_KP_REG_KEY(uc) (((uc)>=0xf100) && ((uc)<=0xf13f)) 71#define KBD_KP_REG_KEY_TO_ASCII(uc) ((uc)&0x3f)</pre></code> 72<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 of <code>0xf180-0xf1bf</code>, while the keypad versions are in the range of <code>0xf140-0xf17f</code> (a difference of <code>0x40</code>). As an example:</p> 73<CODE>KBK_Insert </CODE> is <CODE>0xf1b0</CODE>, and 74<CODE>KBK_Keypad_Insert</CODE> is <CODE>0xf170</CODE> (<CODE>0x40</CODE> less), and 75<CODE>KBK_Keypad_0</CODE> is <CODE>0xf130</CODE> (<CODE>0x40</CODE> less) (<CODE>KBK_Keypad_0</CODE> is on the same key with <CODE>KBK_Keypad_Insert</CODE>), and 76<CODE>'0'</CODE> is<CODE> 0x0030</CODE> (<CODE>0xf100</CODE> less). 77<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> 78<p>The <code>KBD_UC_IS_KP_NUM_NL_KEY</code> macro indicates whether a given key is a keypad number key with NumLock on. The <code>KBD_UC_IS_KP_NUM_UL_KEY</code> macro indicates whether a given key is a keypad number key with NumLock 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> 79<code><pre>#define KBD_UC_IS_KP_NUM_NL_KEY(uc) (((uc)>=KBK_Keypad_0 && ((uc)<=KBK_Keypad_9))) 80#define KBD_UC_IS_KP_NUM_UL_KEY(uc) (((uc)>=KBK_Keypad_Insert && ((uc)<=KBK_Keypad_Page_Up))) 81#define KBD_KP_NUM_UL_KEY_TO_KP_NUM_NL_KEY(uc) ((KBDUnicode)((uc)-0x40))</pre></code> 82<p>Backspace, Tab, Enter, and Esc 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. Also, these values are converted to ASCII/Unicode by <code>KBD_CTRL_KEY_TO_ASCII</code>.</P> 83<code><pre>#define KBD_UC_IS_CTRL_KEY (((uc)>=0xf1c0) && ((uc)<=0xf1df)) 84#define KBD_CTRL_KEY_TO_ASCII(uc) ((uc)&0x1f)</pre></code> 85 86<h2>Low-level USB HID Key Code Interface</h2> 87<p> 88For 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, because all events are passed through using the APIs described above.</p> 89<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>). Unique tracking and alteration of modifier key state is also possible. (To disable the driver's modifier key processing, call the <code><a href="KBDSetLockProcessing.html">KBDSetLockProcessing</a></code> function.) When key event information is changed by a callback, the modified information is placed in an internal queue and used by the synchronous API.</p> 90<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 diagram and chart below summarize the discrepancies with common keyboards. Be aware that there may be exceptions not included here.</p> 91<p><img src="kbd_usb_layout.gif" width="874" height="254"></p> 92<TABLE BORDER=1 CELLPADDING=3 CELLSPACING=0> 93<TR bgcolor="#c0c0c0"> 94<TD>Keyboard Model</TD> 95<TD>HID codes unique to this keyboard</TD> 96<TD>HID codes missing on this keyboard</TD></TR> 97<TD bgcolor="#ff9966">US</TD> 98<TD><code>0x31</code> (backslash/vertical bar)</TD> 99<TD><code>0x32</code>, <code>0x64</code>, <code>0x66-0xDF</code></TD></TR> 100<TD bgcolor="#00ff00">EU</TD> 101<TD><code>0x32</code> (near enter key; symbols vary)<br> <code>0x64</code> (near left shift key; symbols vary)</TD> 102<TD><code>0x31</code>, <code>0x66-0xDF</code></TD></TR> 103<TD bgcolor="#ffff00">Japan</TD> 104<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> 105<TD><code>0x31</code> (see <b>note</b> below)<br> <code>0x64</code></TD></TR> 106</TABLE> 107<p><strong>Note: </strong> 108<ul> 109<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" width="12" height="12"> key above). These keys are remapped to their expected values internally in the KBD Driver.</li> 110<li>Although codes <code>0x92</code> (katakana) and <code>0x93</code> (hiragana) are defined in the HID specification, we have not yet observed any keyboards that transmit these codes.</li> 111<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> 112</ul> 113<p>For a description of individual HID codes, refer to <CODE>kbd_hid_codes.h</CODE>; for keyboards at <a target="new" href="http://www.usb.org/developers/hidpage/">http://www.usb.org/developers/hidpage/</a>, refer to the HID Usage Table .</p> 114<p>To avoid these irregularities, an application key callback should perhaps immediately translate HID key codes into <code>KBKUnicode</code> values using the <CODE><a href="KBDTranslateHidCode.html">KBDTranslateHidCode</a></CODE> function. There are few situations in which raw HID key codes are absolutely required.</p> 115<p>When mapping user input to key presses, an application designer must consider whether multiple keys may be pressed simultaneously and whether a keyboard can recognize such key presses without problems. If three or more keys are pressed simultaneously, a problem known as "ghosting" may occur. This problem will cause keyboard keys that are not being pressed by the user to be perceived as key presses. 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. It may 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> 116<h2>Library Flow</h2> 117<p> 118First, you must call <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 set up the keyboard maps for the appropriate region. As long as one of these functions is always called, calling multiple functions does not pose a problem. A callback handler may be registered before calling the <code><a href="KBDInit.html">KBDInit</a></code> function. Finally, call <code><a href="KBDInit.html">KBDInit</a></code> to initialize the KBD library.</p> 119<p> 120Once callbacks have been registered, keyboard events will result in interrupts and the appropriate application callback will be called. Note that since 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> 121<p> 122Alternately, 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> 123<p> 124To exit the KBD library, <a href="KBDExit.html"><code>KBDExit</code></a> should be called. When this function is called, registered callbacks are invalidated and keyboard events will be ignored. It is recommended that all keyboard LEDs be turned off 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 <a href="KBDExit.html"><code>KBDExit</code></a> has been called.</p> 125</p> 126<h2>Cautions</h2> 127<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> 128<p>The following functions may result in a call that sends an LED message over USB:</p> 129<ul> 130<li><code><a href="KBDSetLeds.html">KBDSetLeds</a></code></li> 131<li><code><a href="KBDSetLedsAsync.html">KBDSetLedsAsync</a></code></li> 132<li><code><a href="KBDSetLedsRetry.html">KBDSetLedsRetry</a></code></li> 133</ul> 134<p>For more details, refer to the documentation for these commands. 135</p> 136 137<h2>Limitations</h2> 138<p>These are the current limitations for keyboard support.</p> 139<ul> 140<li>The currently-supported languages are: International United States, Canadian Bilingual, Canadian French, Danish, Finnish, French, German, Greek, Italian, Japanese, Latin American, Netherlands Dutch, Norwegian, Portuguese, Spanish, Swedish, United Kingdom English, and United States English. 141</li> 142<li>In Num Lock mode, the Unicode value generated by the numerical keypad keys differs from the value generated by the normal numbered keys. For more details, refer to <code><a href="KBDKeyEvent.html">KBDKeyEvent</a></code>.</li> 143<li>The KBD library uses only the Boot-mode report protocol from the USB HID specification. As a result, such non-standard keyboard keys as media control keys are not recognized.</li> 144</ul> 145 146<h2>Revision History</h2> 147<P>2007/07/10 Initial version.</p> 148 149<hr><p>CONFIDENTIAL</p></body> 150</HTML>
