From 37e2da3332de942dfb728e7ee8f50cd31c9a2676 Mon Sep 17 00:00:00 2001
From: patacongo
- "Out-of-Band" Commands.
- Keyboards and keypads are the same device for NuttX.
+ Keypads vs. Keyboards
+ Keyboards and keypads are really the same devices for NuttX.
A keypad is thought of as simply a keyboard with fewer keys.
+
+ Special Commands.
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.
+ A keyboard may return simple text data (alphabetic, numeric, and punctuaction) or control characters (enter, control-C, etc.) when a key is pressed.
+ We can think about this the "normal" keyboard data stream.
+ However, in addition, most keyboards support actions that cannot be represented as text or control 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.
+ In this case, some special encoding may be required to multiplex the normal text data and special command key press data streams.
+
+ Key Press and Release Events
+ Sometimes the time that a key is released is needed by applications as well.
+ Thus, in addition to normal and special key press events, it may also be necessary to encode normal and special key release events.
Encoding/Decoding Layer.
- 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.
+ An optional encoding/decoding layer can be used with the basic character driver to encode the keyboard events into the text data stream.
The function interfaces that comprise that encoding/decoding layer are defined in the header file
Driver Encoding Interfaces.
+ These are interfaces used by the keyboard/keypad driver to encode keyboard events and data.
- Function Prototype: Description: Input Pameters:
- Function Prototype: Description: Input Pameters: Returned Value:
+ Function Prototype: Description: Input Pameters: Returned Value:
+ Function Prototype: Description: Input Pameters:
Application Decoding Interfaces.
- 6.3.16 Keyboard/Keypad Drivers
include/nuttx/input/kbd_code.h
.
These functions provide an matched set of (a) driver encoding interfaces, and (b) application decoding interfaces.
kbd_puttext()
+ kbd_press()
#include <nuttx/streams.h>
#include <nuttx/input/kbd_codec.h>
-void kbd_puttext(int ch, FAR struct lib_outstream_s *stream);
+void kbd_press(int ch, FAR struct lib_outstream_s *stream);
- Put one byte of normal, "in-band" ASCII data into the output stream.
+ Indicates a normal key press event.
+ Put one byte of normal keyboard data into the output stream.
@@ -3676,18 +3685,77 @@ void kbd_puttext(int ch, FAR struct lib_outstream_s *stream);
kbd_putspecial()
+ kbd_release()
+
+#include <nuttx/streams.h>
+#include <nuttx/input/kbd_codec.h>
+void kbd_release(uint8_t ch, FAR struct lib_outstream_s *stream);
+
+
+ Encode the release of a normal key.
+
+
+
+ ch
: The character associated with the key that was releared.
+ stream
: An instance of lib_outstream_s
to perform the actual low-level put operation.
+
+ None.
+
+ kbd_specpress()
#include <nuttx/streams.h>
#include <nuttx/input/kbd_codec.h>
-void kbd_putspecial(enum kbd_keycode_e keycode, FAR struct lib_outstream_s *stream);
+void kbd_specpress(enum kbd_keycode_e keycode, FAR struct lib_outstream_s *stream);
- Put one special, "out-of-band" command into the output stream.
+ Denotes a special key press event.
+ Put one special keyboard command into the output stream.
+
+
+
+ keycode
: The command to be added to the output stream.
+ The enumeration enum kbd_keycode_e keycode
identifies all commands known to the system.
+ stream
: An instance of lib_outstream_s
to perform the actual low-level put operation.
+
+ None.
+
+ kbd_specrel()
+
+#include <nuttx/streams.h>
+#include <nuttx/input/kbd_codec.h>
+void kbd_specrel(enum kbd_keycode_e keycode, FAR struct lib_outstream_s *stream);
+
+
+ Denotes a special key release event.
+ Put one special keyboard command into the output stream.
+
- kbd_get()
+ kbd_decode()
Function Prototype:
#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); +int kbd_decode(FAR struct lib_instream_s *stream, FAR struct kbd_getstate_s *state, FAR uint8_t *pch);
Description:
stream
: An instance of lib_instream_s
to perform the actual low-level get operation.
pch
: 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 enum kbd_getstate_s
.
+ pch
: The location to save the returned value.
+ This may be either a normal, character code or a special command (i.e., a value from enum kbd_getstate_s
.
state
: A user provided buffer to support parsing.
- This structure should be cleared the first time that kbd_get
is called.
+ This structure should be cleared the first time that kbd_decode()
is called.
Returned Value:
pch
is a value from enum kbd_getstate_s
.
+ KBD_PRESS
(0):
+ Indicates the successful receipt of normal, keyboard data.
+ This corresponds to a keypress event.
+ The returned value in pch
is a simple byte of text or control data.
pch
is a simple byte of text or control data.
+ KBD_RELEASE
(1):
+ Indicates a key release event.
+ The returned value in pch
is the byte of text or control data corresponding to the released key.
+ KBD_SPECPRESS
(2):
+ Indicates the successful receipt of a special keyboard command.
+ The returned value in pch
is a value from enum kbd_getstate_s
.
+ KBD_SPECREL
(3):
+ Indicates a special command key release event.
+ The returned value in pch
is a value from enum kbd_getstate_s
.
EOF
:
- An error has getting the next character (reported by the stream
).
- Normally indicates the end of file.
+ KBD_ERROR
(EOF
):
+ An error has getting the next character (reported by the stream
).
+ Normally indicates the end of file.