This is an automated email from the ASF dual-hosted git repository. xiaoxiang781216 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit a073c2f9c105041564a7d5d9124c2f007e26c585 Author: Jorge Guzman <[email protected]> AuthorDate: Thu Jul 30 18:09:54 2026 -0300 Documentation: follow the keyboard change in the application docs The lvglterm page still told the reader to pick the input source that matches the hardware, which was the whole thing being removed: it has one physical keyboard variant now, and reads whatever is registered. The hidkbd page pointed at HIDKBD_ENCODED, which no longer exists. What produces that byte stream now is INPUT_KEYBOARD_BYTESTREAM. system/kbd had no page at all. Signed-off-by: Jorge Guzman <[email protected]> --- .../applications/examples/hidkbd/index.rst | 12 ++- .../applications/examples/lvglterm/index.rst | 80 ++++++++++------- Documentation/applications/system/kbd/index.rst | 99 ++++++++++++++++++++++ 3 files changed, 158 insertions(+), 33 deletions(-) diff --git a/Documentation/applications/examples/hidkbd/index.rst b/Documentation/applications/examples/hidkbd/index.rst index a95266e57be..0ffb131bbf4 100644 --- a/Documentation/applications/examples/hidkbd/index.rst +++ b/Documentation/applications/examples/hidkbd/index.rst @@ -14,5 +14,13 @@ This is a simple test to ``debug/verify`` the USB host HID keyboard class driver in ``include/nuttx/input/kbd_codec.h`` to decode the returned keyboard data. These special keys include such things as up/down arrows, home and end keys, etc. If this not defined, only 7-bit printable and control ASCII characters - will be provided to the user. Requires ``CONFIG_HIDKBD_ENCODED`` and - ``CONFIG_LIBC_KBDCODEC``. + will be provided to the user. Requires + ``CONFIG_INPUT_KEYBOARD_BYTESTREAM`` and ``CONFIG_LIBC_KBDCODEC``. + +.. note:: + + This example reads the byte stream that the USB HID keyboard driver used + to deliver on its own, which now comes from + ``CONFIG_INPUT_KEYBOARD_BYTESTREAM``. New work should use ``kbd`` + instead: it reads any keyboard, in either format, and reports key + releases as well. diff --git a/Documentation/applications/examples/lvglterm/index.rst b/Documentation/applications/examples/lvglterm/index.rst index 18e93d34b86..5ca60f2b8e8 100644 --- a/Documentation/applications/examples/lvglterm/index.rst +++ b/Documentation/applications/examples/lvglterm/index.rst @@ -4,8 +4,8 @@ LVGL application that runs an interactive NuttShell (NSH) on the display. NSH is started with its standard streams redirected through pipes, its output is -rendered in an LVGL text area, and the input comes from one of three sources -selected at build time. +rendered in an LVGL text area, and the input comes from either a touchscreen +or a keyboard, selected at build time. The shared code lives in ``lvglterm.c`` (NSH startup, output rendering, main loop); ``lvglterm_touch.c`` and ``lvglterm_kbd.c`` implement the input @@ -15,9 +15,7 @@ Input variants ============== The input source is chosen with the *LVGL Terminal input source* Kconfig -choice (only one is built at a time). The physical-keyboard options differ in -the data the keyboard device returns on ``read()``, so the one that matches the -hardware must be selected. +choice (only one is built at a time). On-screen keyboard (touch) ``CONFIG_EXAMPLES_LVGLTERM_INPUT_TOUCH`` (default). An LVGL keyboard @@ -31,39 +29,60 @@ On-screen keyboard (touch) On-screen keyboard (touch) variant -Matrix / upper-half keyboard - ``CONFIG_EXAMPLES_LVGLTERM_INPUT_KBD_MATRIX``. ``struct - keyboard_event_s`` events are read from a keyboard registered through the - ``CONFIG_INPUT_KEYBOARD`` upper half (for example the M5Stack Cardputer - matrix keyboard on ``/dev/kbd0``) and streamed to the shell; the output - fills the whole screen. The Fn Up/Down cursor keys scroll the output. +Physical keyboard + ``CONFIG_EXAMPLES_LVGLTERM_INPUT_KBD``. Keys are read from a keyboard + registered with ``keyboard_register()`` and streamed to the shell; the + output fills the whole screen. The Up and Down cursor keys scroll the + output. Any keyboard works, and the terminal does not need to know which + kind it is: USB HID, a matrix, the simulator, virtio. .. figure:: lvglterm-kbd.png :align: center :width: 500px :alt: LVGL Terminal driven by a matrix keyboard - Matrix / upper-half keyboard variant - -USB HID keyboard - ``CONFIG_EXAMPLES_LVGLTERM_INPUT_KBD_USB``. A USB HID keyboard (for - example on ``/dev/kbda`` with ``CONFIG_USBHOST_HIDKBD``) delivers a byte - stream that is decoded with the keyboard codec and streamed to the shell. - When the driver is built with ``CONFIG_HIDKBD_ENCODED`` the Up/Down cursor - keys scroll the terminal. + Physical keyboard variant, driven by a matrix keyboard .. figure:: lvglterm-usb.png :align: center :width: 500px :alt: LVGL Terminal driven by a USB HID keyboard - USB HID keyboard variant + The same variant, driven by a USB HID keyboard + +The keyboard defaults to ``CONFIG_EXAMPLES_LVGLTERM_KBD_DEV`` and can be +overridden at run time by passing the path as the first argument +(``lvglterm /dev/kbd1``) when more than one keyboard is present. Note that +the USB HID driver names its devices ``/dev/kbda`` onwards, since they come +and go as keyboards are plugged in, while the option defaults to +``/dev/kbd0``. + +The terminal reads ``struct keyboard_event_s`` events unless the kernel was +built with ``CONFIG_INPUT_KEYBOARD_BYTESTREAM``, in which case it reads the +byte stream that the keyboard codec defines. That is a property of the build +rather than of the hardware, so it is not something to configure here. + +Driving the terminal without a keyboard +--------------------------------------- + +Because the terminal reads a keyboard device and does not care which one, it +can be driven from the serial console with nothing plugged in. Enable +``CONFIG_UINPUT_KEYBOARD``, which registers a virtual keyboard on +``/dev/ukeyboard``, and ``CONFIG_SYSTEM_KBD``, which injects into it:: + + nsh> lvglterm /dev/ukeyboard & + nsh> kbd -i /dev/ukeyboard + +Everything typed on the console appears on the display from that point on. +Forwarding a real keyboard into the same virtual one lets both drive the +terminal at once, which it cannot do by itself since it opens a single +device:: + + nsh> kbd -i /dev/ukeyboard /dev/kbda & -Both keyboard variants default the device to -``CONFIG_EXAMPLES_LVGLTERM_KBD_DEV`` (``/dev/kbd0`` for the matrix keyboard, -``/dev/kbda`` for USB) and can be overridden at run time by passing the path -as the first argument (``lvglterm /dev/kbd1``) when more than one keyboard is -present. +Raise ``CONFIG_UINPUT_KEYBOARD_BUFNUMBER`` when doing this. It counts events +rather than keys, so the default of eight holds four keystrokes, and a +console hands over a whole line at once. Font ==== @@ -81,13 +100,12 @@ Configuration - ``CONFIG_SYSTEM_NSH=y`` -- the NSH library must be enabled. - ``CONFIG_GRAPHICS_LVGL=y`` and ``CONFIG_LV_USE_NUTTX=y`` -- LVGL with its NuttX integration. -- A display (``CONFIG_LV_USE_NUTTX_LCD`` or a framebuffer). Each input variant +- A display (``CONFIG_LV_USE_NUTTX_LCD`` or a framebuffer). Each input variant also needs its own driver: a touchscreen - (``CONFIG_LV_USE_NUTTX_TOUCHSCREEN``) for the touch variant, - ``CONFIG_INPUT_KEYBOARD`` for the matrix variant, or - ``CONFIG_USBHOST_HIDKBD`` for the USB variant. The USB variant selects - ``CONFIG_LIBC_KBDCODEC`` automatically and, for the cursor keys, the driver - should be built with ``CONFIG_HIDKBD_ENCODED``. + (``CONFIG_LV_USE_NUTTX_TOUCHSCREEN``) for the touch variant, or + ``CONFIG_INPUT_KEYBOARD`` and a keyboard driver for the physical variant. + ``CONFIG_LIBC_KBDCODEC`` is selected automatically when the build delivers + the byte stream. - The selected font (``CONFIG_LV_FONT_UNSCII_8`` or ``CONFIG_LV_FONT_UNSCII_16``) is enabled automatically by the font choice. diff --git a/Documentation/applications/system/kbd/index.rst b/Documentation/applications/system/kbd/index.rst new file mode 100644 index 00000000000..0fd6698081b --- /dev/null +++ b/Documentation/applications/system/kbd/index.rst @@ -0,0 +1,99 @@ +=================================== +``kbd`` Keyboard dump and injection +=================================== + +Description +----------- + +The ``kbd`` application prints every event that a keyboard reports. Any +keyboard registered with ``keyboard_register()`` is read the same way, +whatever the hardware behind it is, so this works with a USB HID keyboard, +a matrix, the simulator, virtio or VNC without being told which. + +It is the first thing to run when bringing up a keyboard on a new board: +if the events look right here, every application that reads a keyboard +will see the same thing. + +It replaces the ``hidkbd`` and ``keyboard`` examples, which did this for +one kind of keyboard each and could not read the other. + +Usage +----- + +.. code-block:: bash + + kbd [<device>] [<count>] + kbd -i <device> [<source>] + +Without ``-i`` it reads ``<device>`` and prints what arrives, stopping +after ``<count>`` keys if one is given. The device defaults to +``CONFIG_SYSTEM_KBD_DEVPATH``. It waits for the device to appear rather +than failing, since a USB keyboard shows up when it is plugged in. + +With ``-i`` it writes instead of reading. See `Injecting keys`_ below. + +Output +------ + +A key that produces a character is reported with the character, and a key +that does not, such as an arrow or a modifier, with a value from +``enum kbd_keycode_e``. The two ranges overlap, so the event type is what +tells them apart:: + + nsh> kbd /dev/kbd0 + kbd: reading /dev/kbd0, keyboard events + press code 97 'a' + release code 97 'a' + specpress keycode 7 + specrel keycode 7 + +The four types are ``press`` and ``release`` for characters, ``specpress`` +and ``specrel`` for keycodes. A driver that reports its arrow keys as +plain presses is not following the contract, and its arrows will be +dropped by applications that do. + +The device delivers ``struct keyboard_event_s`` events unless the kernel +was built with ``CONFIG_INPUT_KEYBOARD_BYTESTREAM``, in which case it +delivers the byte stream that the keyboard codec defines. This follows +that setting rather than having a switch of its own, and says which one it +is on the first line. + +Injecting keys +-------------- + +With ``-i`` the tool goes the other way and writes into a virtual keyboard, +so that an application can be driven with no keyboard hardware at all. +This needs ``CONFIG_UINPUT_KEYBOARD``, which registers ``/dev/ukeyboard``. + +Given no source it injects what it reads from its own stdin, which is the +serial console:: + + nsh> kbd -i /dev/ukeyboard + kbd: injecting into /dev/ukeyboard, type to send, Ctrl-D to stop + +Given a source it forwards every key of one keyboard onto another:: + + nsh> kbd -i /dev/ukeyboard /dev/kbda & + kbd: forwarding /dev/kbda into /dev/ukeyboard + +Point an application at ``/dev/ukeyboard`` and both reach it at once, +which the application cannot do by itself since it opens a single device. + +.. note:: + + Raise ``CONFIG_UINPUT_KEYBOARD_BUFNUMBER`` before injecting. It counts + events rather than keys, so the default of eight holds four keystrokes, + and a console hands over a whole line at once. The keyboard upper half + overwrites the oldest event when the buffer is full, so a typed line + arrives with its beginning missing and nothing says so. + +Configuration +------------- + +- ``CONFIG_SYSTEM_KBD`` enables the application. +- ``CONFIG_SYSTEM_KBD_DEVPATH`` is the keyboard to read when none is named + on the command line. Default ``/dev/kbd0``. Note that the USB HID driver + names its devices ``/dev/kbda`` onwards, since they come and go as + keyboards are plugged in. +- ``CONFIG_SYSTEM_KBD_PROGNAME``, ``CONFIG_SYSTEM_KBD_PRIORITY`` and + ``CONFIG_SYSTEM_KBD_STACKSIZE`` are the usual task settings.
