Fixes and improvements (#620)

- Standardized keyboard input using Unicode-based key codes across supported devices and the simulator. Keyboards don't emit `LV_KEY_*` anymore.
- Refactored lilygo encoder driver into a reusable GPIO rotary encoder driver (see `Drivers/gpio-encoder-module/`). Added more features to the config file.
- Improved LVGL keyboard device management, including duplicate prevention and reliable reconnects.
- LVGL file mutex now registers with lvgl start/stop
- Improved LVGL startup/shutdown stability and memory allocation reliability.
- Increased simulator LVGL memory capacity and improved USB device-class handling.

Drivers/button-control-module/source/button_control.cpp

@@ -12,8 +12,6 @@
 #include <tactility/log.h>
 #include <tactility/time.h>
 
-#include <lvgl.h>
-
 #include <cstdlib>
 
 #define TAG "ButtonControl"
@@ -105,8 +103,8 @@ static error_t start(Device* device) {
 
     error_t error = acquire_button(
         config->pin_primary,
-        two_button_mode ? LV_KEY_ENTER : LV_KEY_NEXT,
-        two_button_mode ? LV_KEY_ESC : LV_KEY_ENTER,
+        two_button_mode ? (uint32_t)CODEPOINT_ENTER : (uint32_t)CODEPOINT_ARROW_DOWN,
+        two_button_mode ? (uint32_t)CODEPOINT_ESCAPE : (uint32_t)CODEPOINT_ENTER,
         &internal->primary
     );
     if (error != ERROR_NONE) {
@@ -114,7 +112,7 @@ static error_t start(Device* device) {
         return error;
     }
 
-    error = acquire_button(config->pin_secondary, LV_KEY_NEXT, LV_KEY_PREV, &internal->secondary);
+    error = acquire_button(config->pin_secondary, CODEPOINT_ARROW_DOWN, CODEPOINT_ARROW_UP, &internal->secondary);
     if (error != ERROR_NONE) {
         if (internal->primary.in_use) {
             gpio_descriptor_release(internal->primary.descriptor);
@@ -176,7 +174,7 @@ static void poll_button(const ButtonControlConfig* config, ButtonControlInternal
     }
 
     // Release: decide short vs. long press by elapsed hold duration, then queue a synthetic
-    // key tap (press followed by release) for the LVGL key this gesture maps to.
+    // key tap (press followed by release) for the key this gesture maps to.
     uint32_t held_ms = now - state->press_start_time;
     uint32_t key = held_ms < config->long_press_ms ? state->short_press_key : state->long_press_key;
     push_pending(internal, key, true);

Drivers/gpio-encoder-module/CMakeLists.txt

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.20)
+
+include("${CMAKE_CURRENT_LIST_DIR}/../../Buildscripts/module.cmake")
+
+file(GLOB_RECURSE SOURCE_FILES "source/*.c*")
+
+tactility_add_module(gpio-encoder-module
+    SRCS ${SOURCE_FILES}
+    INCLUDE_DIRS include/
+    REQUIRES TactilityKernel driver
+    PRIV_REQUIRES esp_driver_pcnt
+)

Drivers/gpio-encoder-module/LICENSE-Apache-2.0.md

@@ -0,0 +1,195 @@
+Apache License
+==============
+
+_Version 2.0, January 2004_  
+_&lt;<http://www.apache.org/licenses/>&gt;_
+
+### Terms and Conditions for use, reproduction, and distribution
+
+#### 1. Definitions
+
+“License” shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+“Licensor” shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+“Legal Entity” shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, “control” means **(i)** the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the
+outstanding shares, or **(iii)** beneficial ownership of such entity.
+
+“You” (or “Your”) shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+“Source” form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+“Object” form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+“Work” shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+“Derivative Works” shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+“Contribution” shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+“submitted” means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as “Not a Contribution.”
+
+“Contributor” shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+#### 2. Grant of Copyright License
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+#### 3. Grant of Patent License
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable (except as stated in this section) patent license to make, have
+made, use, offer to sell, sell, import, and otherwise transfer the Work, where
+such license applies only to those patent claims licensable by such Contributor
+that are necessarily infringed by their Contribution(s) alone or by combination
+of their Contribution(s) with the Work to which such Contribution(s) was
+submitted. If You institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+Contribution incorporated within the Work constitutes direct or contributory
+patent infringement, then any patent licenses granted to You under this License
+for that Work shall terminate as of the date such litigation is filed.
+
+#### 4. Redistribution
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+* **(a)** You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+* **(b)** You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+* **(c)** You must retain, in the Source form of any Derivative Works that You distribute,
+all copyright, patent, trademark, and attribution notices from the Source form
+of the Work, excluding those notices that do not pertain to any part of the
+Derivative Works; and
+* **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any
+Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+#### 5. Submission of Contributions
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify the terms of
+any separate license agreement you may have executed with Licensor regarding
+such Contributions.
+
+#### 6. Trademarks
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+#### 7. Disclaimer of Warranty
+
+Unless required by applicable law or agreed to in writing, Licensor provides the
+Work (and each Contributor provides its Contributions) on an “AS IS” BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+including, without limitation, any warranties or conditions of TITLE,
+NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
+solely responsible for determining the appropriateness of using or
+redistributing the Work and assume any risks associated with Your exercise of
+permissions under this License.
+
+#### 8. Limitation of Liability
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law (such as deliberate
+and grossly negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special, incidental,
+or consequential damages of any character arising as a result of this License or
+out of the use or inability to use the Work (including but not limited to
+damages for loss of goodwill, work stoppage, computer failure or malfunction, or
+any and all other commercial damages or losses), even if such Contributor has
+been advised of the possibility of such damages.
+
+#### 9. Accepting Warranty or Additional Liability
+
+While redistributing the Work or Derivative Works thereof, You may choose to
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations and/or rights consistent with this License. However,
+in accepting such obligations, You may act only on Your own behalf and on Your
+sole responsibility, not on behalf of any other Contributor, and only if You
+agree to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+_END OF TERMS AND CONDITIONS_
+
+### APPENDIX: How to apply the Apache License to your work
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets `[]` replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same “printed page” as the copyright notice for easier identification within
+third-party archives.
+
+    Copyright [yyyy] [name of copyright owner]
+    
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+    
+      http://www.apache.org/licenses/LICENSE-2.0
+    
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+

Drivers/gpio-encoder-module/bindings/tactility,gpio-encoder.yaml

@@ -0,0 +1,33 @@
+description: >
+  GPIO-attached rotary encoder wheel - a 2-phase quadrature encoder (decoded via the ESP32
+  hardware PCNT peripheral) plus an optional separate click/enter button. Exposes a
+  KEYBOARD_TYPE device: each wheel detent is translated to an arrow up/down key, and the
+  button (if present) press/release is translated to the enter key.
+
+compatible: "tactility,gpio-encoder"
+
+properties:
+  pin-a:
+    type: phandles
+    required: true
+    description: Quadrature phase A GPIO pin
+  pin-b:
+    type: phandles
+    required: true
+    description: Quadrature phase B GPIO pin
+  pin-enter:
+    type: phandles
+    default: GPIO_PIN_SPEC_NONE
+    description: Optional click/enter button GPIO pin (active low)
+  pulses-per-detent:
+    type: int
+    min: 1
+    max: 255
+    default: 4
+    description: Quadrature pulses per mechanical detent
+  pending-capacity:
+    type: int
+    min: 2
+    max: 255
+    default: 16
+    description: Capacity of the queue buffering key events between read_key() polls. Must be at least 2 to hold one wheel press/release pair.

Drivers/gpio-encoder-module/devicetree.yaml

@@ -0,0 +1,3 @@
+dependencies:
+  - TactilityKernel
+bindings: bindings

Drivers/gpio-encoder-module/include/bindings/gpio_encoder.h

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <tactility/bindings/bindings.h>
+#include <drivers/gpio_encoder.h>
+
+DEFINE_DEVICETREE(gpio_encoder, struct GpioEncoderConfig)

Drivers/gpio-encoder-module/include/drivers/gpio_encoder.h

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <tactility/drivers/gpio.h>
+
+struct GpioEncoderConfig {
+    // First pin of encoder wheel
+    struct GpioPinSpec pin_a;
+    // Second pin of encoder wheel
+    struct GpioPinSpec pin_b;
+    // "Button" pin of encoder wheel. Optional: GPIO_PIN_SPEC_NONE when the wheel has no click/enter button.
+    struct GpioPinSpec pin_enter;
+    // Quadrature pulses per mechanical detent (x4 decode gives 4 pulses/detent for a standard EC11-style encoder).
+    uint8_t pulses_per_detent;
+    // Capacity of the queue buffering key events between read_key() polls.
+    uint8_t pending_capacity;
+};
+
+#ifdef __cplusplus
+}
+#endif

Drivers/gpio-encoder-module/include/gpio_encoder_module.h

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <tactility/module.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+extern struct Module gpio_encoder_module;
+
+#ifdef __cplusplus
+}
+#endif

Drivers/gpio-encoder-module/source/gpio_encoder.cpp

@@ -0,0 +1,337 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <drivers/gpio_encoder.h>
+
+#include <tactility/device.h>
+#include <tactility/driver.h>
+#include <tactility/drivers/gpio.h>
+#include <tactility/drivers/gpio_controller.h>
+#include <tactility/drivers/gpio_descriptor.h>
+#include <tactility/drivers/keyboard.h>
+#include <tactility/log.h>
+
+#include <driver/pulse_cnt.h>
+
+#include <new>
+
+#define TAG "gpio_encoder"
+#define GET_CONFIG(device) (static_cast<const GpioEncoderConfig*>((device)->config))
+#define GET_INTERNAL(device) (static_cast<GpioEncoderInternal*>(device_get_driver_data(device)))
+
+struct GpioEncoderPendingEvent {
+    uint32_t key;
+    bool pressed;
+};
+
+struct GpioEncoderInternal {
+    pcnt_unit_handle_t pcnt_unit = nullptr;
+    GpioDescriptor* pin_a = nullptr;
+    GpioDescriptor* pin_b = nullptr;
+    GpioDescriptor* pin_enter = nullptr;
+    int32_t pulse_remainder = 0;
+    bool button_pressed = false;
+    int32_t pulses_per_detent = 0;
+    GpioEncoderPendingEvent* pending = nullptr;
+    uint32_t pending_capacity = 0;
+    uint32_t pending_head = 0;
+    uint32_t pending_count = 0;
+};
+
+static bool push_pending(GpioEncoderInternal* internal, uint32_t key, bool pressed) {
+    if (internal->pending_count >= internal->pending_capacity) {
+        LOG_W(TAG, "Pending event queue full, dropping event");
+        return false;
+    }
+    uint32_t tail = (internal->pending_head + internal->pending_count) % internal->pending_capacity;
+    internal->pending[tail] = { .key = key, .pressed = pressed };
+    internal->pending_count++;
+    return true;
+}
+
+static bool pop_pending(GpioEncoderInternal* internal, GpioEncoderPendingEvent* out_event) {
+    if (internal->pending_count == 0) {
+        return false;
+    }
+    *out_event = internal->pending[internal->pending_head];
+    internal->pending_head = (internal->pending_head + 1) % internal->pending_capacity;
+    internal->pending_count--;
+    return true;
+}
+
+extern "C" {
+
+// region Driver lifecycle
+
+// Accumulating count makes over-/underflow automatically compensated; requires watch points at
+// the low and high limits (see pcnt_unit_add_watch_point() below). Ported from the deprecated
+// HAL's TpagerEncoder::initEncoder().
+static constexpr int PCNT_LOW_LIMIT = -127;
+static constexpr int PCNT_HIGH_LIMIT = 126;
+
+static error_t init_pcnt_unit(int pin_a, int pin_b, pcnt_unit_handle_t* out_unit) {
+    pcnt_unit_config_t unit_config = {
+        .low_limit = PCNT_LOW_LIMIT,
+        .high_limit = PCNT_HIGH_LIMIT,
+        .intr_priority = 0,
+        .flags = { .accum_count = 1 },
+    };
+
+    pcnt_unit_handle_t unit = nullptr;
+    if (pcnt_new_unit(&unit_config, &unit) != ESP_OK) {
+        LOG_E(TAG, "Pulse counter initialization failed");
+        return ERROR_RESOURCE;
+    }
+
+    pcnt_glitch_filter_config_t filter_config = { .max_glitch_ns = 1000 };
+    if (pcnt_unit_set_glitch_filter(unit, &filter_config) != ESP_OK) {
+        LOG_E(TAG, "Pulse counter glitch filter config failed");
+        pcnt_del_unit(unit);
+        return ERROR_RESOURCE;
+    }
+
+    pcnt_chan_config_t chan_a_config = {
+        .edge_gpio_num = pin_b,
+        .level_gpio_num = pin_a,
+        .flags = {},
+    };
+    pcnt_chan_config_t chan_b_config = {
+        .edge_gpio_num = pin_a,
+        .level_gpio_num = pin_b,
+        .flags = {},
+    };
+
+    pcnt_channel_handle_t chan_a = nullptr;
+    pcnt_channel_handle_t chan_b = nullptr;
+    if (pcnt_new_channel(unit, &chan_a_config, &chan_a) != ESP_OK ||
+        pcnt_new_channel(unit, &chan_b_config, &chan_b) != ESP_OK) {
+        LOG_E(TAG, "Pulse counter channel config failed");
+        pcnt_del_unit(unit);
+        return ERROR_RESOURCE;
+    }
+
+    // Standard quadrature decode: each channel counts on its edge, direction decided by the
+    // other channel's level.
+    if (pcnt_channel_set_edge_action(chan_a, PCNT_CHANNEL_EDGE_ACTION_DECREASE, PCNT_CHANNEL_EDGE_ACTION_INCREASE) != ESP_OK ||
+        pcnt_channel_set_edge_action(chan_b, PCNT_CHANNEL_EDGE_ACTION_INCREASE, PCNT_CHANNEL_EDGE_ACTION_DECREASE) != ESP_OK) {
+        LOG_E(TAG, "Pulse counter edge action config failed");
+        pcnt_del_unit(unit);
+        return ERROR_RESOURCE;
+    }
+    if (pcnt_channel_set_level_action(chan_a, PCNT_CHANNEL_LEVEL_ACTION_KEEP, PCNT_CHANNEL_LEVEL_ACTION_INVERSE) != ESP_OK ||
+        pcnt_channel_set_level_action(chan_b, PCNT_CHANNEL_LEVEL_ACTION_KEEP, PCNT_CHANNEL_LEVEL_ACTION_INVERSE) != ESP_OK) {
+        LOG_E(TAG, "Pulse counter level action config failed");
+        pcnt_del_unit(unit);
+        return ERROR_RESOURCE;
+    }
+
+    if (pcnt_unit_add_watch_point(unit, PCNT_LOW_LIMIT) != ESP_OK ||
+        pcnt_unit_add_watch_point(unit, PCNT_HIGH_LIMIT) != ESP_OK) {
+        LOG_E(TAG, "Pulse counter watch point config failed");
+        pcnt_del_unit(unit);
+        return ERROR_RESOURCE;
+    }
+
+    if (pcnt_unit_enable(unit) != ESP_OK ||
+        pcnt_unit_clear_count(unit) != ESP_OK ||
+        pcnt_unit_start(unit) != ESP_OK) {
+        LOG_E(TAG, "Pulse counter could not be started");
+        pcnt_del_unit(unit);
+        return ERROR_RESOURCE;
+    }
+
+    *out_unit = unit;
+    return ERROR_NONE;
+}
+
+static error_t start(Device* device) {
+    const auto* config = GET_CONFIG(device);
+
+    // Backstop for values the devicetree compiler doesn't currently validate: 0 divides by
+    // zero in poll_wheel(), and a capacity below 2 can never hold one press/release pair.
+    if (config->pulses_per_detent == 0) {
+        LOG_E(TAG, "pulses_per_detent must be > 0");
+        return ERROR_INVALID_ARGUMENT;
+    }
+    if (config->pending_capacity < 2) {
+        LOG_E(TAG, "pending_capacity must be >= 2");
+        return ERROR_INVALID_ARGUMENT;
+    }
+
+    auto* internal = new (std::nothrow) GpioEncoderInternal();
+    if (internal == nullptr) {
+        return ERROR_OUT_OF_MEMORY;
+    }
+    internal->pulses_per_detent = static_cast<int32_t>(config->pulses_per_detent);
+    internal->pending_capacity = config->pending_capacity;
+
+    internal->pending = new (std::nothrow) GpioEncoderPendingEvent[internal->pending_capacity];
+    if (internal->pending == nullptr) {
+        delete internal;
+        return ERROR_OUT_OF_MEMORY;
+    }
+
+    internal->pin_a = gpio_descriptor_acquire(config->pin_a.gpio_controller, config->pin_a.pin, config->pin_a.flags | GPIO_FLAG_DIRECTION_INPUT, GPIO_OWNER_GPIO);
+    if (internal->pin_a == nullptr) {
+        LOG_E(TAG, "Failed to acquire pin_a");
+        delete[] internal->pending;
+        delete internal;
+        return ERROR_RESOURCE;
+    }
+
+    internal->pin_b = gpio_descriptor_acquire(config->pin_b.gpio_controller, config->pin_b.pin, config->pin_b.flags | GPIO_FLAG_DIRECTION_INPUT, GPIO_OWNER_GPIO);
+    if (internal->pin_b == nullptr) {
+        LOG_E(TAG, "Failed to acquire pin_b");
+        gpio_descriptor_release(internal->pin_a);
+        delete[] internal->pending;
+        delete internal;
+        return ERROR_RESOURCE;
+    }
+
+    int native_pin_a = 0;
+    int native_pin_b = 0;
+    if (gpio_descriptor_get_native_pin_number(internal->pin_a, &native_pin_a) != ERROR_NONE ||
+        gpio_descriptor_get_native_pin_number(internal->pin_b, &native_pin_b) != ERROR_NONE) {
+        LOG_E(TAG, "Failed to resolve native pin numbers");
+        gpio_descriptor_release(internal->pin_b);
+        gpio_descriptor_release(internal->pin_a);
+        delete[] internal->pending;
+        delete internal;
+        return ERROR_RESOURCE;
+    }
+
+    error_t error = init_pcnt_unit(native_pin_a, native_pin_b, &internal->pcnt_unit);
+    if (error != ERROR_NONE) {
+        gpio_descriptor_release(internal->pin_b);
+        gpio_descriptor_release(internal->pin_a);
+        delete[] internal->pending;
+        delete internal;
+        return error;
+    }
+
+    if (config->pin_enter.gpio_controller != nullptr) {
+        internal->pin_enter = gpio_descriptor_acquire(config->pin_enter.gpio_controller, config->pin_enter.pin, GPIO_FLAG_DIRECTION_INPUT | GPIO_FLAG_ACTIVE_LOW, GPIO_OWNER_GPIO);
+        if (internal->pin_enter == nullptr) {
+            pcnt_unit_stop(internal->pcnt_unit);
+            pcnt_del_unit(internal->pcnt_unit);
+            gpio_descriptor_release(internal->pin_b);
+            gpio_descriptor_release(internal->pin_a);
+            delete[] internal->pending;
+            delete internal;
+            return ERROR_RESOURCE;
+        }
+    }
+
+    device_set_driver_data(device, internal);
+    return ERROR_NONE;
+}
+
+static error_t stop(Device* device) {
+    auto* internal = GET_INTERNAL(device);
+
+    if (internal->pin_enter != nullptr) {
+        gpio_descriptor_release(internal->pin_enter);
+    }
+
+    if (pcnt_unit_stop(internal->pcnt_unit) != ESP_OK) {
+        LOG_W(TAG, "Failed to stop encoder");
+    }
+    if (pcnt_del_unit(internal->pcnt_unit) != ESP_OK) {
+        LOG_W(TAG, "Failed to delete encoder");
+    }
+
+    gpio_descriptor_release(internal->pin_b);
+    gpio_descriptor_release(internal->pin_a);
+
+    device_set_driver_data(device, nullptr);
+    delete[] internal->pending;
+    delete internal;
+    return ERROR_NONE;
+}
+
+// endregion
+
+// region KeyboardApi
+
+// Wheel rotation is a discrete notch, not a held key, so each detent is reported as an
+// immediate press+release pair rather than a persistent pressed state.
+static void poll_wheel(GpioEncoderInternal* internal) {
+    int pulses = 0;
+    pcnt_unit_get_count(internal->pcnt_unit, &pulses);
+    pcnt_unit_clear_count(internal->pcnt_unit);
+
+    int32_t total = internal->pulse_remainder + pulses;
+    int32_t detents = total / internal->pulses_per_detent;
+    internal->pulse_remainder = total % internal->pulses_per_detent;
+
+    uint32_t key = detents >= 0 ? CODEPOINT_ARROW_DOWN : CODEPOINT_ARROW_UP;
+    int32_t count = detents >= 0 ? detents : -detents;
+    for (int32_t i = 0; i < count; i++) {
+        // A press without its matching release would leave the consumer thinking the key
+        // is stuck down, so only enqueue the pair when both fit.
+        if (internal->pending_count + 2 > internal->pending_capacity) {
+            LOG_W(TAG, "Pending event queue full, dropping remaining wheel events");
+            break;
+        }
+        push_pending(internal, key, true);
+        push_pending(internal, key, false);
+    }
+}
+
+static void poll_button(GpioEncoderInternal* internal) {
+    if (internal->pin_enter == nullptr) {
+        return;
+    }
+
+    bool pressed = false;
+    if (gpio_descriptor_get_level(internal->pin_enter, &pressed) != ERROR_NONE) {
+        return;
+    }
+    // Only commit the new state once its event is actually queued - a full FIFO here
+    // leaves button_pressed unchanged so the same transition is retried next poll instead
+    // of being lost.
+    if (pressed != internal->button_pressed) {
+        if (push_pending(internal, CODEPOINT_ENTER, pressed)) {
+            internal->button_pressed = pressed;
+        }
+    }
+}
+
+static error_t gpio_encoder_read_key(Device* device, KeyboardKeyData* data) {
+    auto* internal = GET_INTERNAL(device);
+
+    poll_wheel(internal);
+    poll_button(internal);
+
+    GpioEncoderPendingEvent event;
+    if (pop_pending(internal, &event)) {
+        data->key = event.key;
+        data->pressed = event.pressed;
+        data->continue_reading = internal->pending_count > 0;
+    } else {
+        data->key = 0;
+        data->pressed = false;
+        data->continue_reading = false;
+    }
+
+    return ERROR_NONE;
+}
+
+// endregion
+
+static constexpr KeyboardApi GPIO_ENCODER_API = {
+    .read_key = gpio_encoder_read_key,
+};
+
+extern Module gpio_encoder_module;
+
+Driver gpio_encoder_driver = {
+    .name = "gpio_encoder",
+    .compatible = (const char*[]) { "tactility,gpio-encoder", nullptr },
+    .start_device = start,
+    .stop_device = stop,
+    .api = &GPIO_ENCODER_API,
+    .device_type = &KEYBOARD_TYPE,
+    .owner = &gpio_encoder_module,
+    .internal = nullptr
+};
+
+}

Drivers/gpio-encoder-module/source/module.cpp

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <tactility/driver.h>
+#include <tactility/module.h>
+
+extern "C" {
+
+extern Driver gpio_encoder_driver;
+
+static Driver* const gpio_encoder_drivers[] = {
+    &gpio_encoder_driver,
+    nullptr
+};
+
+Module gpio_encoder_module = {
+    .name = "gpio-encoder",
+    .drivers = gpio_encoder_drivers
+};
+
+} // extern "C"

Drivers/lilygo-module/bindings/lilygo,tpager-encoder.yaml

@@ -1,22 +0,0 @@
-description: >
-  LilyGO T-Lora Pager encoder wheel next to the display - a 2-phase quadrature encoder
-  (decoded via the ESP32 hardware PCNT peripheral) plus a separate click/enter button.
-  Reports raw, unscaled pulses and button level: the pulses-per-detent scaling and enter-press
-  debounce are UI concerns layered on top by the consumer (see tpager_encoder_input.h), not
-  something this driver knows about.
-
-compatible: "lilygo,tpager-encoder"
-
-properties:
-  pin-a:
-    type: phandles
-    required: true
-    description: Quadrature phase A GPIO pin
-  pin-b:
-    type: phandles
-    required: true
-    description: Quadrature phase B GPIO pin
-  pin-enter:
-    type: phandles
-    required: true
-    description: Click/enter button GPIO pin (active low)

Drivers/lilygo-module/include/lilygo/bindings/tpager_encoder.h

@@ -1,7 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-#pragma once
-
-#include <tactility/bindings/bindings.h>
-#include <lilygo/drivers/tpager_encoder.h>
-
-DEFINE_DEVICETREE(tpager_encoder, struct TpagerEncoderConfig)

Drivers/lilygo-module/include/lilygo/drivers/tpager_encoder.h

@@ -1,59 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-#pragma once
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#include <tactility/drivers/gpio.h>
-#include <tactility/error.h>
-#include <stdbool.h>
-#include <stdint.h>
-
-struct Device;
-struct DeviceType;
-
-struct TpagerEncoderConfig {
-    struct GpioPinSpec pin_a;
-    struct GpioPinSpec pin_b;
-    struct GpioPinSpec pin_enter;
-};
-
-/**
- * @brief API for the T-Lora Pager encoder wheel driver.
- * Reports raw, unscaled pulses: pulses-per-detent scaling and enter-press debounce are UI
- * concerns layered on top by the consumer, not something this driver knows about.
- */
-struct TpagerEncoderApi {
-    /**
-     * @brief Reads the accumulated pulse count since the last read, then resets it to zero.
-     * @param[in] device the encoder device
-     * @param[out] out_pulses accumulated quadrature pulses (positive/negative by direction)
-     * @retval ERROR_NONE when the operation was successful
-     */
-    error_t (*read_delta)(struct Device* device, int32_t* out_pulses);
-
-    /**
-     * @brief Gets whether the enter button is currently pressed.
-     * @param[in] device the encoder device
-     * @param[out] out_pressed true when pressed
-     * @retval ERROR_NONE when the operation was successful
-     */
-    error_t (*get_button_pressed)(struct Device* device, bool* out_pressed);
-};
-
-/**
- * @brief Reads the accumulated pulse count using the specified encoder device.
- */
-error_t tpager_encoder_read_delta(struct Device* device, int32_t* out_pulses);
-
-/**
- * @brief Gets whether the enter button is currently pressed on the specified encoder device.
- */
-error_t tpager_encoder_get_button_pressed(struct Device* device, bool* out_pressed);
-
-extern const struct DeviceType TPAGER_ENCODER_TYPE;
-
-#ifdef __cplusplus
-}
-#endif

Drivers/lilygo-module/include/lilygo/drivers/tpager_encoder_input.h

@@ -1,20 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-#pragma once
-
-#include <lvgl.h>
-
-namespace tpager_encoder {
-
-/**
- * @brief Initialize the encoder wheel as an LVGL input device, backed by the kernel
- * tpager_encoder driver.
- * @return LVGL input device pointer, or nullptr if the kernel device isn't found/started
- */
-lv_indev_t* init();
-
-/**
- * @brief Deinitialize the encoder wheel's LVGL input device.
- */
-void deinit();
-
-}

Drivers/lilygo-module/source/module.cpp

@@ -6,12 +6,10 @@ extern "C" {
 
 extern Driver tdeck_keyboard_driver;
 extern Driver tdeck_keyboard_backlight_driver;
-extern Driver tpager_encoder_driver;
 
 static Driver* const lilygo_drivers[] = {
     &tdeck_keyboard_driver,
     &tdeck_keyboard_backlight_driver,
-    &tpager_encoder_driver,
     nullptr
 };
 

Drivers/lilygo-module/source/tpager_encoder.cpp

@@ -1,198 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-#include <lilygo/drivers/tpager_encoder.h>
-
-#include <tactility/device.h>
-#include <tactility/driver.h>
-#include <tactility/drivers/gpio.h>
-#include <tactility/drivers/gpio_controller.h>
-#include <tactility/drivers/gpio_descriptor.h>
-#include <tactility/log.h>
-
-#include <driver/pulse_cnt.h>
-
-#include <new>
-
-#define TAG "tpager_encoder"
-#define GET_CONFIG(device) (static_cast<const TpagerEncoderConfig*>((device)->config))
-#define GET_INTERNAL(device) (static_cast<TpagerEncoderInternal*>(device_get_driver_data(device)))
-
-struct TpagerEncoderInternal {
-    pcnt_unit_handle_t pcnt_unit = nullptr;
-    GpioDescriptor* pin_enter = nullptr;
-};
-
-extern "C" {
-
-static error_t read_delta(Device* device, int32_t* out_pulses) {
-    auto* internal = GET_INTERNAL(device);
-    int pulses = 0;
-    pcnt_unit_get_count(internal->pcnt_unit, &pulses);
-    pcnt_unit_clear_count(internal->pcnt_unit);
-    *out_pulses = pulses;
-    return ERROR_NONE;
-}
-
-static error_t get_button_pressed(Device* device, bool* out_pressed) {
-    auto* internal = GET_INTERNAL(device);
-    return gpio_descriptor_get_level(internal->pin_enter, out_pressed);
-}
-
-error_t tpager_encoder_read_delta(Device* device, int32_t* out_pulses) {
-    return read_delta(device, out_pulses);
-}
-
-error_t tpager_encoder_get_button_pressed(Device* device, bool* out_pressed) {
-    return get_button_pressed(device, out_pressed);
-}
-
-// region Driver lifecycle
-
-// Accumulating count makes over-/underflow automatically compensated; requires watch points at
-// the low and high limits (see pcnt_unit_add_watch_point() below). Ported from the deprecated
-// HAL's TpagerEncoder::initEncoder().
-static constexpr int PCNT_LOW_LIMIT = -127;
-static constexpr int PCNT_HIGH_LIMIT = 126;
-
-static error_t init_pcnt_unit(const TpagerEncoderConfig* config, pcnt_unit_handle_t* out_unit) {
-    pcnt_unit_config_t unit_config = {
-        .low_limit = PCNT_LOW_LIMIT,
-        .high_limit = PCNT_HIGH_LIMIT,
-        .intr_priority = 0,
-        .flags = { .accum_count = 1 },
-    };
-
-    pcnt_unit_handle_t unit = nullptr;
-    if (pcnt_new_unit(&unit_config, &unit) != ESP_OK) {
-        LOG_E(TAG, "Pulse counter initialization failed");
-        return ERROR_RESOURCE;
-    }
-
-    pcnt_glitch_filter_config_t filter_config = { .max_glitch_ns = 1000 };
-    if (pcnt_unit_set_glitch_filter(unit, &filter_config) != ESP_OK) {
-        LOG_E(TAG, "Pulse counter glitch filter config failed");
-        pcnt_del_unit(unit);
-        return ERROR_RESOURCE;
-    }
-
-    pcnt_chan_config_t chan_a_config = {
-        .edge_gpio_num = static_cast<int>(config->pin_b.pin),
-        .level_gpio_num = static_cast<int>(config->pin_a.pin),
-        .flags = {},
-    };
-    pcnt_chan_config_t chan_b_config = {
-        .edge_gpio_num = static_cast<int>(config->pin_a.pin),
-        .level_gpio_num = static_cast<int>(config->pin_b.pin),
-        .flags = {},
-    };
-
-    pcnt_channel_handle_t chan_a = nullptr;
-    pcnt_channel_handle_t chan_b = nullptr;
-    if (pcnt_new_channel(unit, &chan_a_config, &chan_a) != ESP_OK ||
-        pcnt_new_channel(unit, &chan_b_config, &chan_b) != ESP_OK) {
-        LOG_E(TAG, "Pulse counter channel config failed");
-        pcnt_del_unit(unit);
-        return ERROR_RESOURCE;
-    }
-
-    // Standard quadrature decode: each channel counts on its edge, direction decided by the
-    // other channel's level.
-    if (pcnt_channel_set_edge_action(chan_a, PCNT_CHANNEL_EDGE_ACTION_DECREASE, PCNT_CHANNEL_EDGE_ACTION_INCREASE) != ESP_OK ||
-        pcnt_channel_set_edge_action(chan_b, PCNT_CHANNEL_EDGE_ACTION_INCREASE, PCNT_CHANNEL_EDGE_ACTION_DECREASE) != ESP_OK) {
-        LOG_E(TAG, "Pulse counter edge action config failed");
-        pcnt_del_unit(unit);
-        return ERROR_RESOURCE;
-    }
-    if (pcnt_channel_set_level_action(chan_a, PCNT_CHANNEL_LEVEL_ACTION_KEEP, PCNT_CHANNEL_LEVEL_ACTION_INVERSE) != ESP_OK ||
-        pcnt_channel_set_level_action(chan_b, PCNT_CHANNEL_LEVEL_ACTION_KEEP, PCNT_CHANNEL_LEVEL_ACTION_INVERSE) != ESP_OK) {
-        LOG_E(TAG, "Pulse counter level action config failed");
-        pcnt_del_unit(unit);
-        return ERROR_RESOURCE;
-    }
-
-    if (pcnt_unit_add_watch_point(unit, PCNT_LOW_LIMIT) != ESP_OK ||
-        pcnt_unit_add_watch_point(unit, PCNT_HIGH_LIMIT) != ESP_OK) {
-        LOG_E(TAG, "Pulse counter watch point config failed");
-        pcnt_del_unit(unit);
-        return ERROR_RESOURCE;
-    }
-
-    if (pcnt_unit_enable(unit) != ESP_OK ||
-        pcnt_unit_clear_count(unit) != ESP_OK ||
-        pcnt_unit_start(unit) != ESP_OK) {
-        LOG_E(TAG, "Pulse counter could not be started");
-        pcnt_del_unit(unit);
-        return ERROR_RESOURCE;
-    }
-
-    *out_unit = unit;
-    return ERROR_NONE;
-}
-
-static error_t start(Device* device) {
-    const auto* config = GET_CONFIG(device);
-
-    auto* internal = new (std::nothrow) TpagerEncoderInternal();
-    if (internal == nullptr) {
-        return ERROR_OUT_OF_MEMORY;
-    }
-
-    error_t error = init_pcnt_unit(config, &internal->pcnt_unit);
-    if (error != ERROR_NONE) {
-        delete internal;
-        return error;
-    }
-
-    internal->pin_enter = gpio_descriptor_acquire(config->pin_enter.gpio_controller, config->pin_enter.pin, GPIO_FLAG_DIRECTION_INPUT | GPIO_FLAG_ACTIVE_LOW, GPIO_OWNER_GPIO);
-    if (internal->pin_enter == nullptr) {
-        pcnt_unit_stop(internal->pcnt_unit);
-        pcnt_del_unit(internal->pcnt_unit);
-        delete internal;
-        return ERROR_RESOURCE;
-    }
-
-    device_set_driver_data(device, internal);
-    return ERROR_NONE;
-}
-
-static error_t stop(Device* device) {
-    auto* internal = GET_INTERNAL(device);
-
-    gpio_descriptor_release(internal->pin_enter);
-
-    if (pcnt_unit_stop(internal->pcnt_unit) != ESP_OK) {
-        LOG_W(TAG, "Failed to stop encoder");
-    }
-    if (pcnt_del_unit(internal->pcnt_unit) != ESP_OK) {
-        LOG_W(TAG, "Failed to delete encoder");
-    }
-
-    device_set_driver_data(device, nullptr);
-    delete internal;
-    return ERROR_NONE;
-}
-
-// endregion
-
-static constexpr TpagerEncoderApi TPAGER_ENCODER_API = {
-    .read_delta = read_delta,
-    .get_button_pressed = get_button_pressed,
-};
-
-const struct DeviceType TPAGER_ENCODER_TYPE {
-    .name = "tpager-encoder"
-};
-
-extern Module lilygo_module;
-
-Driver tpager_encoder_driver = {
-    .name = "tpager_encoder",
-    .compatible = (const char*[]) { "lilygo,tpager-encoder", nullptr },
-    .start_device = start,
-    .stop_device = stop,
-    .api = &TPAGER_ENCODER_API,
-    .device_type = &TPAGER_ENCODER_TYPE,
-    .owner = &lilygo_module,
-    .internal = nullptr
-};
-
-}

Drivers/lilygo-module/source/tpager_encoder_input.cpp

@@ -1,95 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-#include <lilygo/drivers/tpager_encoder_input.h>
-#include <lilygo/drivers/tpager_encoder.h>
-
-#include <tactility/device.h>
-#include <tactility/log.h>
-
-constexpr auto* TAG = "tpager_encoder";
-
-namespace tpager_encoder {
-
-static lv_indev_t* g_indev = nullptr;
-static Device* g_device = nullptr;
-
-// Ported from the deprecated HAL's TpagerEncoder::readCallback(). g_raw_total reconstructs the
-// old absolute PCNT counter value (the kernel driver's read_delta() consumes/resets on every
-// call instead of accumulating forever), so the hysteresis below behaves identically: only a
-// run of more than pulses_click raw pulses commits to a detent, and any remainder is discarded
-// rather than carried into the next read (matches the original's pulses_prev = pulses jump).
-static void read_cb(lv_indev_t*, lv_indev_data_t* data) {
-    constexpr int32_t pulses_click = 4;
-    static int32_t raw_total = 0;
-    static int32_t committed_total = 0;
-
-    constexpr int enter_filter_threshold = 2;
-    static int enter_filter = 0;
-
-    data->enc_diff = 0;
-    data->state = LV_INDEV_STATE_RELEASED;
-
-    int32_t delta = 0;
-    tpager_encoder_read_delta(g_device, &delta);
-    raw_total += delta;
-
-    int32_t pulse_diff = raw_total - committed_total;
-    if (pulse_diff > pulses_click || pulse_diff < -pulses_click) {
-        data->enc_diff = static_cast<int16_t>(pulse_diff / pulses_click);
-        committed_total = raw_total;
-    }
-
-    bool pressed = false;
-    tpager_encoder_get_button_pressed(g_device, &pressed);
-    if (pressed && enter_filter < enter_filter_threshold) {
-        enter_filter++;
-    }
-    if (!pressed && enter_filter > 0) {
-        enter_filter--;
-    }
-
-    if (enter_filter == enter_filter_threshold) {
-        data->state = LV_INDEV_STATE_PRESSED;
-    }
-}
-
-lv_indev_t* init() {
-    if (g_indev != nullptr) {
-        LOG_W(TAG, "Already initialized");
-        return g_indev;
-    }
-
-    if (device_get_first_active_by_type(&TPAGER_ENCODER_TYPE, &g_device) != ERROR_NONE) {
-        LOG_E(TAG, "tpager_encoder kernel device not found or not started");
-        return nullptr;
-    }
-
-    g_indev = lv_indev_create();
-    if (g_indev == nullptr) {
-        LOG_E(TAG, "Failed to register LVGL input device");
-        device_put(g_device);
-        g_device = nullptr;
-        return nullptr;
-    }
-
-    lv_indev_set_type(g_indev, LV_INDEV_TYPE_ENCODER);
-    lv_indev_set_read_cb(g_indev, read_cb);
-    LOG_I(TAG, "Initialized");
-
-    return g_indev;
-}
-
-void deinit() {
-    if (g_indev == nullptr) {
-        return;
-    }
-
-    lv_indev_delete(g_indev);
-    g_indev = nullptr;
-
-    device_put(g_device);
-    g_device = nullptr;
-
-    LOG_I(TAG, "Deinitialized");
-}
-
-}

Drivers/m5stack-module/source/cardputer_adv_keyboard.cpp

@@ -14,8 +14,6 @@
 #include <tactility/error.h>
 #include <tactility/log.h>
 
-#include <lvgl.h>
-
 #include <cstdlib>
 
 static constexpr const char* TAG = "CardputerAdvKeyboard";
@@ -46,24 +44,24 @@ static constexpr int CARDPUTER_ADV_COLS = 14;
 // [row][col] on the 4x14 grid, matching the base Cardputer's physical layout. 0 means the cell
 // emits nothing (used for the sym/shift cells themselves, and unwired cells on this board).
 static const uint32_t cardputer_adv_keymap_lc[CARDPUTER_ADV_ROWS][CARDPUTER_ADV_COLS] = {
-    { '`', '1', '2', '3', '4', '5', '6', '7', '8', '9', '0', '-', '=', LV_KEY_BACKSPACE },
+    { '`', '1', '2', '3', '4', '5', '6', '7', '8', '9', '0', '-', '=', CODEPOINT_BACKSPACE },
     { '\t', 'q', 'w', 'e', 'r', 't', 'y', 'u', 'i', 'o', 'p', '[', ']', '\\' },
-    { 0, 0, 'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', ';', '\'', LV_KEY_ENTER },
+    { 0, 0, 'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', ';', '\'', CODEPOINT_ENTER },
     { 0, 0, 0, 'z', 'x', 'c', 'v', 'b', 'n', 'm', ',', '.', '/', ' ' },
 };
 
 static const uint32_t cardputer_adv_keymap_uc[CARDPUTER_ADV_ROWS][CARDPUTER_ADV_COLS] = {
-    { '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', LV_KEY_DEL },
+    { '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', CODEPOINT_DELETE },
     { '\t', 'Q', 'W', 'E', 'R', 'T', 'Y', 'U', 'I', 'O', 'P', '{', '}', '|' },
-    { 0, 0, 'A', 'S', 'D', 'F', 'G', 'H', 'J', 'K', 'L', ':', '"', LV_KEY_ENTER },
+    { 0, 0, 'A', 'S', 'D', 'F', 'G', 'H', 'J', 'K', 'L', ':', '"', CODEPOINT_ENTER },
     { 0, 0, 0, 'Z', 'X', 'C', 'V', 'B', 'N', 'M', '<', '>', '?', ' ' },
 };
 
 static const uint32_t cardputer_adv_keymap_sym[CARDPUTER_ADV_ROWS][CARDPUTER_ADV_COLS] = {
-    { LV_KEY_ESC, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
+    { CODEPOINT_ESCAPE, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
     { '\t', 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
-    { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, LV_KEY_PREV, 0, LV_KEY_ENTER },
-    { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, LV_KEY_LEFT, LV_KEY_NEXT, LV_KEY_RIGHT, 0 },
+    { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, CODEPOINT_ARROW_UP, 0, CODEPOINT_ENTER },
+    { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, CODEPOINT_ARROW_LEFT, CODEPOINT_ARROW_DOWN, CODEPOINT_ARROW_RIGHT, 0 },
 };
 
 struct CardputerAdvActiveKey {

Drivers/m5stack-module/source/cardputer_keyboard.cpp

@@ -14,8 +14,6 @@
 #include <tactility/error.h>
 #include <tactility/log.h>
 
-#include <lvgl.h>
-
 #include <cstdlib>
 
 static constexpr const char* TAG = "CardputerKeyboard";
@@ -31,15 +29,12 @@ static constexpr int CARDPUTER_PENDING_CAPACITY = 2;
 
 enum CardputerKeyRole {
     CARDPUTER_KEY_CHAR,
-    CARDPUTER_KEY_TAB,
     CARDPUTER_KEY_FN,
     CARDPUTER_KEY_SHIFT,
     CARDPUTER_KEY_CTRL,
     CARDPUTER_KEY_OPT,
     CARDPUTER_KEY_ALT,
     CARDPUTER_KEY_DEL,
-    CARDPUTER_KEY_ENTER,
-    CARDPUTER_KEY_SPACE,
 };
 
 struct CardputerKeyDef {
@@ -56,12 +51,12 @@ struct CardputerKeyDef {
 static const CardputerKeyDef cardputer_key_map[CARDPUTER_ROWS][CARDPUTER_COLS] = {
     { K('`', '~'), K('1', '!'), K('2', '@'), K('3', '#'), K('4', '$'), K('5', '%'), K('6', '^'),
       K('7', '&'), K('8', '*'), K('9', '('), K('0', ')'), K('-', '_'), K('=', '+'), { CARDPUTER_KEY_DEL, 0, 0 } },
-    { { CARDPUTER_KEY_TAB, 0, 0 }, K('q', 'Q'), K('w', 'W'), K('e', 'E'), K('r', 'R'), K('t', 'T'), K('y', 'Y'),
+    { K('\t', '\t'), K('q', 'Q'), K('w', 'W'), K('e', 'E'), K('r', 'R'), K('t', 'T'), K('y', 'Y'),
       K('u', 'U'), K('i', 'I'), K('o', 'O'), K('p', 'P'), K('[', '{'), K(']', '}'), K('\\', '|') },
     { { CARDPUTER_KEY_FN, 0, 0 }, { CARDPUTER_KEY_SHIFT, 0, 0 }, K('a', 'A'), K('s', 'S'), K('d', 'D'), K('f', 'F'), K('g', 'G'),
-      K('h', 'H'), K('j', 'J'), K('k', 'K'), K('l', 'L'), K(';', ':'), K('\'', '"'), { CARDPUTER_KEY_ENTER, 0, 0 } },
+      K('h', 'H'), K('j', 'J'), K('k', 'K'), K('l', 'L'), K(';', ':'), K('\'', '"'), K('\r', '\r') },
     { { CARDPUTER_KEY_CTRL, 0, 0 }, { CARDPUTER_KEY_OPT, 0, 0 }, { CARDPUTER_KEY_ALT, 0, 0 }, K('z', 'Z'), K('x', 'X'), K('c', 'C'), K('v', 'V'),
-      K('b', 'B'), K('n', 'N'), K('m', 'M'), K(',', '<'), K('.', '>'), K('/', '?'), { CARDPUTER_KEY_SPACE, 0, 0 } },
+      K('b', 'B'), K('n', 'N'), K('m', 'M'), K(',', '<'), K('.', '>'), K('/', '?'), K(' ', ' ') },
 };
 
 #undef K
@@ -74,8 +69,8 @@ struct CardputerKeyboardPendingEvent {
 struct CardputerKeyboardInternal {
     GpioDescriptor* output_descriptors[CARDPUTER_OUTPUT_COUNT];
     GpioDescriptor* input_descriptors[CARDPUTER_INPUT_COUNT];
-    // 0 when no actionable key is currently held; otherwise the LVGL key code last reported
-    // via read_key(). Only ever one actionable key at a time (matches original hardware driver:
+    // 0 when no actionable key is currently held; otherwise the key (Unicode codepoint) last
+    // reported via read_key(). Only ever one actionable key at a time (matches original hardware driver:
     // modifier keys are consumed internally, and only the first non-modifier key found in a
     // scan is reported).
     uint32_t active_key;
@@ -195,13 +190,10 @@ static uint8_t read_input(CardputerKeyboardInternal* internal) {
     return mask;
 }
 
-// Scans the full matrix and resolves it to a single LVGL key code (0 if none), applying the
-// same priority as the original driver: enter > space > backspace > first regular character
-// found in scan order, with fn changing the interpretation of backspace/enter/punctuation.
-// Modifier keys (fn/shift/ctrl/opt/alt/tab) are never reported themselves.
+// Scans the full matrix and resolves it to a Unicode codepoint
 static uint32_t scan_key(CardputerKeyboardInternal* internal) {
     bool fn = false, shift = false, ctrl = false;
-    bool del_flag = false, enter_flag = false, space_flag = false;
+    bool del_flag = false;
     bool has_regular = false;
     char regular_normal = 0, regular_shifted = 0;
 
@@ -223,7 +215,6 @@ static uint32_t scan_key(CardputerKeyboardInternal* internal) {
             const auto& def = cardputer_key_map[row][col];
 
             switch (def.role) {
-                case CARDPUTER_KEY_TAB:
                 case CARDPUTER_KEY_OPT:
                 case CARDPUTER_KEY_ALT:
                     break; // consumed, never affects output
@@ -239,12 +230,6 @@ static uint32_t scan_key(CardputerKeyboardInternal* internal) {
                 case CARDPUTER_KEY_DEL:
                     del_flag = true;
                     break;
-                case CARDPUTER_KEY_ENTER:
-                    enter_flag = true;
-                    break;
-                case CARDPUTER_KEY_SPACE:
-                    space_flag = true;
-                    break;
                 case CARDPUTER_KEY_CHAR:
                     if (!has_regular) {
                         has_regular = true;
@@ -259,24 +244,22 @@ static uint32_t scan_key(CardputerKeyboardInternal* internal) {
     char resolved_char = has_regular ? ((ctrl || shift) ? regular_shifted : regular_normal) : 0;
 
     if (!fn) {
-        if (enter_flag) return LV_KEY_ENTER;
-        if (space_flag) return (uint32_t)' ';
-        if (del_flag) return LV_KEY_BACKSPACE;
-        if (has_regular) return (uint32_t)(uint8_t)resolved_char;
+        if (del_flag) return CODEPOINT_BACKSPACE;
+        if (has_regular) return (uint32_t)resolved_char;
         return 0;
     }
 
-    // fn combos: forward-delete, enter, and group navigation (using PREV/NEXT rather than
-    // UP/DOWN so widgets like lv_switch that toggle on arrow keys aren't affected).
-    if (del_flag) return LV_KEY_DEL;
-    if (enter_flag) return LV_KEY_ENTER;
+    // fn combos: forward-delete, enter, and group navigation (using the tab-to-bar codepoints
+    // rather than arrow codepoints so widgets like lv_switch that toggle on arrow keys aren't
+    // affected).
+    if (del_flag) return CODEPOINT_DELETE;
     if (has_regular) {
         switch (resolved_char) {
-            case '`': return LV_KEY_ESC;
-            case ',': return LV_KEY_LEFT;
-            case '/': return LV_KEY_RIGHT;
-            case ';': return LV_KEY_PREV;
-            case '.': return LV_KEY_NEXT;
+            case '`': return CODEPOINT_ESCAPE;
+            case ',': return CODEPOINT_ARROW_LEFT;
+            case '/': return CODEPOINT_ARROW_RIGHT;
+            case ';': return CODEPOINT_ARROW_UP;
+            case '.': return CODEPOINT_ARROW_DOWN;
             default: return 0;
         }
     }

Drivers/tca8418-module/bindings/ti,tca8418.yaml

@@ -34,8 +34,8 @@ properties:
       Base (lowercase) layer keymap, rows*columns bytes in row-major order (already in
       silkscreen/keymap column order - see reverse-columns). 0 = no key at this position (e.g.
       a blank matrix position, or a position handled as a modifier via shift-row/shift-col/
-      sym-row/sym-col instead). Non-zero bytes are sent as-is via KeyboardKeyData::key (ASCII
-      or an LVGL LV_KEY_* code).
+      sym-row/sym-col instead). Non-zero bytes are sent as-is via KeyboardKeyData::key (a Unicode
+      codepoint - byte range covers Latin-1 - for character and non-character keys).
   keymap-uc:
     type: array
     element-type: uint8_t