diff options
Diffstat (limited to 'nuttx/Documentation/NuttxPortingGuide.html')
-rw-r--r-- | nuttx/Documentation/NuttxPortingGuide.html | 148 |
1 files changed, 147 insertions, 1 deletions
diff --git a/nuttx/Documentation/NuttxPortingGuide.html b/nuttx/Documentation/NuttxPortingGuide.html index 0408f82ac..ebb3eff4b 100644 --- a/nuttx/Documentation/NuttxPortingGuide.html +++ b/nuttx/Documentation/NuttxPortingGuide.html @@ -131,7 +131,8 @@ <a href="#pwmdrivers">6.3.12 PWM Drivers</a><br> <a href="#candrivers">6.3.13 CAN Drivers</a><br> <a href="#quadencoder">6.3.14 Quadrature Encoder Drivers</a><br> - <a href="#wdogdriver">6.3.15 Watchdog Timer Drivers</a> + <a href="#wdogdriver">6.3.15 Watchdog Timer Drivers</a><br> + <a href="#kbddriver">6.3.16 Keyboard/Keypad Drivers</a><br> </ul> <a href="#pwrmgmt">6.4 Power Management</a> <ul> @@ -3620,6 +3621,151 @@ extern void up_ledoff(int led); </li> </ul> +<h3><a name="kbddriver">6.3.16 Keyboard/Keypad Drivers</a></h3> +<p> + <b>"Out-of-Band" Commands</b>. + Keyboards and keypads are the same device for NuttX. + A keypad is thought of as simply a keyboard with fewer keys. + In NuttX, a keyboard/keypad driver is simply a character driver that may have an (optional) encoding/decoding layer on the data returned by the character driver. + A keyboard may return simple text data (alphabetic, numeric, and punctuaction) or control characters (enter, control-C, etc.). + We can think about this the normal "in-band" keyboard data stream. + However, in addition, most keyboards support actions that cannot be represented as text data. + Such actions include things like cursor controls (home, up arrow, page down, etc.), editing functions (insert, delete, etc.), volume controls, (mute, volume up, etc.) and other special functions. + We can think about this as special, "out-of-band" keyboard commands. + In this case, some special encoding may be required to multiplex the in-band text data and out-of-band command streams. +</p> +<p> + <b>Encoding/Decoding</b> Layer</b>. + An optional encoding/decoding layer can be used with the basic character driver to encode the out-of-band commands into the text data stream. + The function interfaces that comprise that encoding/decoding layer are defined in the header file <code>include/nuttx/input/kbd_code.h</code>. + These functions provide an matched set of (a) driver encoding interfaces, and (b) application decoding interfaces. +</p> +<ol> + <li> + <p> + <b>Driver Encoding Interfaces</b>. + </p> + <ul> + <li> + <p> + <b><code>kbd_puttext()</code></b> + </p> + <p><b>Function Prototype:</b></p> + <ul><pre> +#include <nuttx/streams.h> +#include <nuttx/input/kbd_codec.h> +void kbd_puttext(int ch, FAR struct lib_outstream_s *stream); +</pre></ul> + <p><b>Description:</b></p> + <ul> + Put one byte of normal, "in-band" ASCII data into the output stream. + </ul> + <p><b>Input Pameters:</b></p> + <ul> + <li> + <code>ch</code>: The character to be added to the output stream. + </li> + <li> + <code>stream</code>: An instance of <code>lib_outstream_s</code> to perform the actual low-level put operation. + </li> + </ul> + <p><b>Returned Value:</b></p> + <ul> + None. + </ul> + </li> + <li> + <p> + <b><code>kbd_putspecial()</code></b> + </p> + <p><b>Function Prototype:</b></p> + <ul><pre> +#include <nuttx/streams.h> +#include <nuttx/input/kbd_codec.h> +void kbd_putspecial(enum kbd_keycode_e keycode, FAR struct lib_outstream_s *stream); +</pre></ul> + <p><b>Description:</b></p> + <ul> + Put one special, "out-of-band" command into the output stream. + </ul> + <p><b>Input Pameters:</b></p> + <ul> + <li> + <code>keycode</code>: The command to be added to the output stream. + The enumeration <code>enum kbd_keycode_e keycode</code> identifies all commands known to the system. + </li> + <li> + <code>stream</code>: An instance of <code>lib_outstream_s</code> to perform the actual low-level put operation. + </li> + </ul> + <p><b>Returned Value:</b></p> + <ul> + None. + </ul> + </li> + </ul> + </li> + <li> + <p> + <b>Application Decoding Interfaces</b>. + </p> + <ul> + <li> + <p> + <b><code>kbd_get()</code></b> + </p> + <p><b>Function Prototype:</b></p> + <ul><pre> +#include <nuttx/streams.h> +#include <nuttx/input/kbd_codec.h> +int kbd_get(FAR struct lib_instream_s *stream, FAR struct kbd_getstate_s *state, FAR uint8_t *pch); +</pre></ul> + <p><b>Description:</b></p> + <ul> + Get one byte of data or special command from the driver provided input buffer. + </ul> + <p><b>Input Pameters:</b></p> + <ul> + <li> + <code>stream</code>: An instance of <code>lib_instream_s</code> to perform the actual low-level get operation. + </li> + <li> + <code>pch</code>: The location character to save the returned value. + This may be either a normal, "in-band" ASCII characer or a special, "out-of-band" command (i.e., a value from <code>enum kbd_getstate_s</code>. + </li> + <li> + <code>state</code>: A user provided buffer to support parsing. + This structure should be cleared the first time that <code>kbd_get</code> is called. + </li> + </ul> + <p><b>Returned Value:</b></p> + <ul> + <li> + <b>1</b>: + Indicates the successful receipt of a special, "out-of-band" command. + The returned value in <code>pch</code> is a value from <code>enum kbd_getstate_s</code>. + </li> + <li> + <b>0</b>: + Indicates the successful receipt of normal, "in-band" ASCII data. + The returned value in <code>pch</code> is a simple byte of text or control data. + </li> + <li> + <b><code>EOF</code></b>: + An error has getting the next character (reported by the <code>stream</code>). + Normally indicates the end of file. + </li> + </ul> + </li> + </ul> + </li> +</ol> +<p> + <b>I/O Streams</b>. + Notice the use of the abstract I/O streams in these interfaces. + These stream interfaces are defined in <code>include/nuttx/streams.h</code>. +</p> + <h2><a name="pwrmgmt">6.4 Power Management</a></h2> <h3><a name="pmoverview">6.4.1 Overview</a></h3> |