Software keyboard refactored (#594)

Removed software keyboard in Tactility subproject (GuiService, Lvgl.cpp) and re-implemented it in TactilityKernel.

Devices/m5stack-tab5/Source/devices/tab5_headphone_detect.cpp

@@ -1,16 +1,18 @@
 #include "tab5_headphone_detect.h"
 
+#include <tactility/error.h>
 #include <tactility/device.h>
 #include <tactility/drivers/gpio.h>
 #include <tactility/drivers/gpio_controller.h>
 #include <tactility/log.h>
+#include <tactility/concurrent/mutex.h>
 
 #include <freertos/FreeRTOS.h>
 #include <freertos/timers.h>
 
 #include <atomic>
 
-#define TAG "Tab5"
+constexpr auto* TAG = "Tab5";
 
 // PI4IOE5V6408-0 (0x43) bit 1
 constexpr auto GPIO_EXP0_PIN_SPEAKER_ENABLE = 1;
@@ -20,18 +22,88 @@ constexpr auto GPIO_EXP0_PIN_HEADPHONE_DETECT = 7;
 constexpr auto HP_DETECT_POLL_MS = 1000;
 
 static TimerHandle_t hp_detect_timer = nullptr;
-static std::atomic<Device*> io_expander0_cached { nullptr };
 // Flags are written by the timer daemon task
 static std::atomic hp_detect_last { false };
 static std::atomic hp_detect_initialized { false };
 
-static void headphone_detect_callback(TimerHandle_t /*timer*/) {
-    Device* cached = io_expander0_cached.load(std::memory_order_acquire);
-    if (!cached) {
-        cached = device_find_by_name("io_expander0");
-        io_expander0_cached.store(cached, std::memory_order_release);
+// Owns the cached io_expander0 reference.
+// Takes care of refcounting and concurrency.
+struct HeadphoneDetectCache {
+    Mutex mutex {};
+    Device* io_expander0 = nullptr;
+    bool active = false;
+
+    HeadphoneDetectCache() {
+        mutex_construct(&mutex);
+    }
+
+    bool isActive() {
+        mutex_lock(&mutex);
+        bool result = active;
+        mutex_unlock(&mutex);
+        return result;
+    }
+
+    void setActive(bool value) {
+        mutex_lock(&mutex);
+        active = value;
+        mutex_unlock(&mutex);
+    }
+
+    Device* getIoExpander0() {
+        mutex_lock(&mutex);
+        Device* dev = io_expander0;
+        if (dev) {
+            device_get(dev);
+        }
+        mutex_unlock(&mutex);
+        return dev;
+    }
+
+    // Pass nullptr to clear/release the current entry - that always succeeds, regardless of
+    // `active`, since it's what stop() uses to tear the cache down.
+    bool setIoExpander0(Device* dev) {
+        mutex_lock(&mutex);
+        if (dev && !active) {
+            mutex_unlock(&mutex);
+            return false;
+        }
+        Device* old = io_expander0;
+        if (dev) {
+            device_get(dev);
+        }
+        io_expander0 = dev;
+        mutex_unlock(&mutex);
+        if (old) {
+            device_put(old);
+        }
+        return true;
+    }
+};
+
+static HeadphoneDetectCache& headphoneDetectCache() {
+    static HeadphoneDetectCache instance;
+    return instance;
+}
+
+static void headphone_detect_callback(TimerHandle_t /*timer*/) {
+    auto& cache = headphoneDetectCache();
+    if (!cache.isActive()) {
+        return; // Teardown is in progress or done - don't acquire/publish a new reference
+    }
+
+    Device* io_expander0 = cache.getIoExpander0();
+    if (!io_expander0) {
+        Device* dev = nullptr;
+        if (device_get_by_name("io_expander0", &dev) == ERROR_NONE) {
+            if (cache.setIoExpander0(dev)) {
+                device_put(dev); // Cache now holds its own reference
+                io_expander0 = cache.getIoExpander0();
+            } else {
+                io_expander0 = dev; // Deactivated concurrently - use our own reference just this once
+            }
+        }
     }
-    auto* io_expander0 = cached;
     if (!io_expander0) {
         return; // Not ready yet, will retry on next tick
     }
@@ -39,6 +111,7 @@ static void headphone_detect_callback(TimerHandle_t /*timer*/) {
     auto* hp_pin = gpio_descriptor_acquire(io_expander0, GPIO_EXP0_PIN_HEADPHONE_DETECT, GPIO_FLAG_DIRECTION_INPUT, GPIO_OWNER_GPIO);
     if (!hp_pin) {
         LOG_W(TAG, "hp_detect: HP_DET pin busy");
+        device_put(io_expander0);
         return;
     }
 
@@ -48,6 +121,7 @@ static void headphone_detect_callback(TimerHandle_t /*timer*/) {
 
     if (err != ERROR_NONE) {
         LOG_W(TAG, "hp_detect: HP_DET read error: %s", error_to_string(err));
+        device_put(io_expander0);
         return;
     }
 
@@ -57,18 +131,22 @@ static void headphone_detect_callback(TimerHandle_t /*timer*/) {
         auto* spk_pin = gpio_descriptor_acquire(io_expander0, GPIO_EXP0_PIN_SPEAKER_ENABLE, GPIO_FLAG_DIRECTION_OUTPUT, GPIO_OWNER_GPIO);
         if (!spk_pin) {
             LOG_W(TAG, "hp_detect: SPK_EN pin busy, will retry");
+            device_put(io_expander0);
             return;
         }
         error_t spk_err = gpio_descriptor_set_level(spk_pin, !hp);
         gpio_descriptor_release(spk_pin);
         if (spk_err != ERROR_NONE) {
             LOG_W(TAG, "hp_detect: SPK_EN set error: %s, will retry", error_to_string(spk_err));
+            device_put(io_expander0);
             return;
         }
         hp_detect_last = hp;
         hp_detect_initialized = true;
         LOG_I(TAG, "Headphones %s, speaker %s", hp ? "detected" : "removed", hp ? "disabled" : "enabled");
     }
+
+    device_put(io_expander0);
 }
 
 void tab5_headphone_detect_start() {
@@ -80,15 +158,20 @@ void tab5_headphone_detect_start() {
     hp_detect_initialized = false;
     hp_detect_last = false;
 
+    auto& cache = headphoneDetectCache();
+    cache.setActive(true);
+
     hp_detect_timer = xTimerCreate("hp_detect", pdMS_TO_TICKS(HP_DETECT_POLL_MS), pdTRUE, nullptr, headphone_detect_callback);
     if (!hp_detect_timer) {
         LOG_E(TAG, "Failed to create hp_detect timer");
+        cache.setActive(false);
         return;
     }
     if (xTimerStart(hp_detect_timer, pdMS_TO_TICKS(100)) != pdPASS) {
         LOG_E(TAG, "Failed to start hp_detect timer");
         xTimerDelete(hp_detect_timer, pdMS_TO_TICKS(100));
         hp_detect_timer = nullptr;
+        cache.setActive(false);
     }
 }
 
@@ -97,6 +180,10 @@ void tab5_headphone_detect_stop() {
         return;
     }
 
+    auto& cache = headphoneDetectCache();
+    // Block any callback invocation from this point on from installing a new reference.
+    cache.setActive(false);
+
     if (xTimerStop(hp_detect_timer, pdMS_TO_TICKS(100)) != pdPASS) {
         LOG_W(TAG, "Failed to stop hp_detect timer");
     }
@@ -106,5 +193,6 @@ void tab5_headphone_detect_stop() {
     // Always clear the handle — stale non-null handle is worse than a resource leak, as it would
     // cause tab5_headphone_detect_start() to silently skip re-creating the timer.
     hp_detect_timer = nullptr;
-    io_expander0_cached.store(nullptr, std::memory_order_release);
+
+    cache.setIoExpander0(nullptr);
 }

Documentation/ideas.md

@@ -13,6 +13,9 @@
 
 ## Higher Priority
 
+- Bluetooth app: when toggling BT on, it doesn't update the UI with discovered devices. It only works after re-opening the app.
+- display.h API: get_backlight does not change ref counting, but it should
+- bluetooth: various getters for child devices do not change ref counting, but they should
 - Improve kernel_init.cpp (and other modules): create driver_ensure_added() and driver_ensure_destructed()
 - Remove and migrate `Include/Tactility/kernel/Kernel.h` into `tactility/delay.h`
 - Drivers/audio-codec-module is not a module. Move it somewhere else. Or make it an actual module.

Drivers/lilygo-module/source/trackball.cpp

@@ -76,8 +76,7 @@ lv_indev_t* init() {
         return g_indev;
     }
 
-    g_device = device_find_first_active_by_type(&TDECK_TRACKBALL_TYPE);
-    if (g_device == nullptr) {
+    if (device_get_first_active_by_type(&TDECK_TRACKBALL_TYPE, &g_device) != ERROR_NONE) {
         LOG_E(TAG, "tdeck_trackball kernel device not found or not started");
         return nullptr;
     }
@@ -88,6 +87,7 @@ lv_indev_t* init() {
     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;
     }
@@ -129,6 +129,8 @@ void deinit() {
 
     lv_indev_delete(g_indev);
     g_indev = nullptr;
+
+    device_put(g_device);
     g_device = nullptr;
 
     g_mode = Mode::Encoder;

Modules/lvgl-module/CMakeLists.txt

@@ -92,6 +92,7 @@ include("${CMAKE_CURRENT_LIST_DIR}/../../Buildscripts/module.cmake")
 tactility_add_module(lvgl-module
     SRCS ${SOURCE_FILES}
     INCLUDE_DIRS include/
+    PRIV_INCLUDE_DIRS private/
     REQUIRES ${REQUIRES_LIST}
 )
 

Modules/lvgl-module/include/lvgl/devices/keyboard.h

@@ -10,6 +10,10 @@
 extern "C" {
 #endif
 
+struct LvglSoftwareKeyboard {
+    lv_obj_t* object;
+};
+
 /**
  * @brief Creates an lv_indev_t bound to the given KEYBOARD_TYPE device and registers a read callback
  * that polls the device through its KeyboardApi.
@@ -32,6 +36,109 @@ error_t lvgl_keyboard_add(struct Device* device, lv_display_t* display, lv_indev
  */
 void lvgl_keyboard_remove(lv_indev_t* indev);
 
+/**
+ * @brief Assigns the indev to the shared keyboard input group, so it can drive focus
+ * navigation and input for focused widgets.
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_keyboard_enable(lv_indev_t* indev);
+
+/**
+ * @brief Detaches the indev from the shared keyboard input group.
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_keyboard_disable(lv_indev_t* indev);
+
+/**
+ * @brief Wires a textarea up to the on-screen keyboard: shows it on focus, hides it on
+ * defocus/ready, and adds the textarea to the keyboard's navigation group.
+ *
+ * No-op if lvgl_software_keyboard_is_enabled() is false (i.e. a hardware keyboard is present).
+ *
+ * @warning Caller must hold the LVGL lock.
+ * @param[in] keyboard the on-screen keyboard to associate with the textarea
+ * @param[in] textarea the lv_textarea_t object to wire up
+ */
+void lvgl_keyboard_add_textarea(struct LvglSoftwareKeyboard* keyboard, lv_obj_t* textarea);
+
+/**
+ * @brief Checks whether a ready (started) KEYBOARD_TYPE kernel device is present.
+ * @return true if a hardware keyboard device is available
+ */
+bool lvgl_hardware_keyboard_is_available();
+
+/**
+ * @brief Assigns the shared keyboard navigation group to a keypad indev that wasn't created via
+ * lvgl_keyboard_add() (e.g. a USB HID keyboard managed outside the kernel device system).
+ *
+ * @warning Caller must hold the LVGL lock. Requires the keyboard navigation group to already
+ * exist (created during LVGL module start).
+ * @param[in] device the keypad indev to attach to the navigation group
+ */
+void lvgl_hardware_keyboard_add_custom(lv_indev_t* device);
+
+/**
+ * @brief Detaches an indev previously registered with lvgl_hardware_keyboard_add_custom() and
+ * frees its associated context.
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_hardware_keyboard_remove_custom(lv_indev_t* device);
+
+/**
+ * @brief Creates the on-screen keyboard widget as a hidden child of parent, and remembers it as
+ * the last constructed software keyboard (see lvgl_software_keyboard_get_last()).
+ * @warning Caller must hold the LVGL lock.
+ * @param[out] keyboard the software keyboard struct to initialize
+ * @param[in] parent the lv_obj_t that will own the keyboard widget
+ */
+void lvgl_software_keyboard_construct(struct LvglSoftwareKeyboard* keyboard, lv_obj_t* parent);
+
+/**
+ * @brief Deletes the on-screen keyboard widget created by lvgl_software_keyboard_construct().
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_software_keyboard_destruct(struct LvglSoftwareKeyboard* keyboard);
+
+/**
+ * @brief Unhides the on-screen keyboard and binds it to the given textarea for input.
+ * @warning Caller must hold the LVGL lock.
+ * @param[in] keyboard the software keyboard to show
+ * @param[in] textarea the lv_textarea_t that receives the keyboard's input
+ */
+void lvgl_software_keyboard_show(struct LvglSoftwareKeyboard* keyboard, lv_obj_t* textarea);
+
+/**
+ * @brief Hides the on-screen keyboard.
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_software_keyboard_hide(struct LvglSoftwareKeyboard* keyboard);
+
+/**
+ * The on-screen keyboard is only shown when there is no hardware keyboard driver active.
+ * @return if we should show a on-screen keyboard for text input inside our apps
+ */
+bool lvgl_software_keyboard_is_enabled();
+
+/**
+ * @return the most recently constructed software keyboard, or one with a NULL object if none
+ * has been constructed yet (or the last one was destructed)
+ */
+struct LvglSoftwareKeyboard* lvgl_software_keyboard_get_last();
+
+/**
+ * @brief Attaches the shared keyboard navigation group to every currently registered keypad
+ * indev, so they can be used to navigate the on-screen keyboard and focused widgets.
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_software_keyboard_activate(struct LvglSoftwareKeyboard* keyboard);
+
+/**
+ * @brief Detaches the navigation group from every currently registered keypad indev (inverse of
+ * lvgl_software_keyboard_activate()).
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_software_keyboard_deactivate(struct LvglSoftwareKeyboard* keyboard);
+
 #ifdef __cplusplus
 }
 #endif

Modules/lvgl-module/private/lvgl/devices/keyboard_private.h

@@ -0,0 +1,13 @@
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+void lvgl_keyboard_on_start_lvgl();
+void lvgl_keyboard_on_stop_lvgl();
+
+#ifdef __cplusplus
+}
+#endif

Modules/lvgl-module/source/arch/lvgl_esp32.c

@@ -5,6 +5,7 @@
 
 #include <lvgl/lvgl.h>
 #include <lvgl/module.h>
+#include <lvgl/devices/keyboard_private.h>
 #include <tactility/error.h>
 #include <tactility/log.h>
 #include <tactility/time.h>
@@ -51,6 +52,10 @@ error_t lvgl_arch_start() {
     // devices and services. The latter might start adding widgets immediately.
     initialized = true;
 
+    // Must exist before devices/services are attached below, since those can
+    // immediately try to assign an indev to this group (e.g. USB HID input).
+    lvgl_keyboard_on_start_lvgl();
+
     lvgl_devices_attach();
 
     if (lvgl_module_config.on_start) lvgl_module_config.on_start();
@@ -63,8 +68,11 @@ error_t lvgl_arch_stop() {
 
     lvgl_devices_detach();
 
+    lvgl_keyboard_on_stop_lvgl();
+
     if (lvgl_port_deinit() != ESP_OK) {
-        // Call on_start again to recover
+        // Recreate what stop() above tore down, then call on_start again to recover
+        lvgl_keyboard_on_start_lvgl();
         if (lvgl_module_config.on_start) lvgl_module_config.on_start();
         return ERROR_RESOURCE;
     }

Modules/lvgl-module/source/arch/lvgl_posix.c

@@ -12,6 +12,7 @@
 
 #include <lvgl/lvgl.h>
 #include <lvgl/module.h>
+#include <lvgl/devices/keyboard_private.h>
 
 extern struct LvglModuleConfig lvgl_module_config;
 extern void lvgl_devices_attach();
@@ -118,6 +119,10 @@ error_t lvgl_arch_start() {
 
     lv_init();
 
+    // Must exist before devices/services are attached from the lvgl task below,
+    // since those can immediately try to assign an indev to this group.
+    lvgl_keyboard_on_start_lvgl();
+
     // Create the main app loop, like ESP-IDF
     BaseType_t task_result = xTaskCreate(
         lvgl_task,
@@ -147,6 +152,8 @@ error_t lvgl_arch_stop() {
         }
     }
 
+    lvgl_keyboard_on_stop_lvgl();
+
     lv_deinit();
 
     return ERROR_NONE;

Modules/lvgl-module/source/devices/keyboard.c

@@ -1,67 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-#include <lvgl/devices/keyboard.h>
-
-#include <tactility/drivers/keyboard.h>
-
-#include <stdlib.h>
-
-struct LvglKeyboardCtx {
-    struct Device* device;
-};
-
-static void lvgl_keyboard_read_cb(lv_indev_t* indev, lv_indev_data_t* data) {
-    struct LvglKeyboardCtx* ctx = (struct LvglKeyboardCtx*)lv_indev_get_driver_data(indev);
-
-    struct KeyboardKeyData key_data = {0};
-    if (keyboard_read_key(ctx->device, &key_data) != ERROR_NONE) {
-        data->state = LV_INDEV_STATE_RELEASED;
-        data->continue_reading = false;
-        return;
-    }
-
-    // KeyboardKeyData deliberately mirrors lv_indev_data_t's key/continue_reading fields, so no translation is needed.
-    data->key = key_data.key;
-    data->state = key_data.pressed ? LV_INDEV_STATE_PRESSED : LV_INDEV_STATE_RELEASED;
-    data->continue_reading = key_data.continue_reading;
-}
-
-error_t lvgl_keyboard_add(struct Device* device, lv_display_t* display, lv_indev_t** out_indev) {
-    if (device == NULL || out_indev == NULL) {
-        return ERROR_INVALID_ARGUMENT;
-    }
-    if (device_get_type(device) != &KEYBOARD_TYPE) {
-        return ERROR_INVALID_ARGUMENT;
-    }
-
-    struct LvglKeyboardCtx* ctx = (struct LvglKeyboardCtx*)malloc(sizeof(struct LvglKeyboardCtx));
-    if (ctx == NULL) {
-        return ERROR_OUT_OF_MEMORY;
-    }
-    ctx->device = device;
-
-    lv_indev_t* indev = lv_indev_create();
-    if (indev == NULL) {
-        free(ctx);
-        return ERROR_OUT_OF_MEMORY;
-    }
-
-    lv_indev_set_type(indev, LV_INDEV_TYPE_KEYPAD);
-    lv_indev_set_read_cb(indev, lvgl_keyboard_read_cb);
-    lv_indev_set_driver_data(indev, ctx);
-    if (display != NULL) {
-        lv_indev_set_display(indev, display);
-    }
-
-    *out_indev = indev;
-    return ERROR_NONE;
-}
-
-void lvgl_keyboard_remove(lv_indev_t* indev) {
-    if (indev == NULL) {
-        return;
-    }
-
-    struct LvglKeyboardCtx* ctx = (struct LvglKeyboardCtx*)lv_indev_get_driver_data(indev);
-    lv_indev_delete(indev);
-    free(ctx);
-}

Modules/lvgl-module/source/devices/keyboard.cpp

@@ -0,0 +1,218 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <lvgl/devices/keyboard.h>
+#include <lvgl/lvgl.h>
+
+#include <tactility/drivers/keyboard.h>
+
+#include <stdlib.h>
+#include <vector>
+
+struct LvglKeyboardCtx {
+    Device* device;
+};
+
+static LvglSoftwareKeyboard last_software_keyboard = {
+    .object = nullptr
+};
+
+static lv_group_t* keyboard_group;
+
+extern "C" {
+
+void lvgl_keyboard_on_start_lvgl() {
+    lvgl_lock();
+    keyboard_group = lv_group_create();
+    check(keyboard_group);
+    lvgl_unlock();
+}
+
+void lvgl_keyboard_on_stop_lvgl() {
+    last_software_keyboard = {
+        .object = nullptr
+    };
+
+    lvgl_lock();
+    lv_group_delete(keyboard_group);
+    lvgl_unlock();
+
+    keyboard_group = nullptr;
+}
+
+static void lvgl_keyboard_read_cb(lv_indev_t* indev, lv_indev_data_t* data) {
+    LvglKeyboardCtx* ctx = static_cast<struct LvglKeyboardCtx*>(lv_indev_get_driver_data(indev));
+
+    KeyboardKeyData key_data = {};
+    if (keyboard_read_key(ctx->device, &key_data) != ERROR_NONE) {
+        data->state = LV_INDEV_STATE_RELEASED;
+        data->continue_reading = false;
+        return;
+    }
+
+    // KeyboardKeyData deliberately mirrors lv_indev_data_t's key/continue_reading fields, so no translation is needed.
+    data->key = key_data.key;
+    data->state = key_data.pressed ? LV_INDEV_STATE_PRESSED : LV_INDEV_STATE_RELEASED;
+    data->continue_reading = key_data.continue_reading;
+}
+
+error_t lvgl_keyboard_add(struct Device* device, lv_display_t* display, lv_indev_t** out_indev) {
+    if (device == NULL || out_indev == NULL) {
+        return ERROR_INVALID_ARGUMENT;
+    }
+    if (device_get_type(device) != &KEYBOARD_TYPE) {
+        return ERROR_INVALID_ARGUMENT;
+    }
+
+    LvglKeyboardCtx* ctx = static_cast<struct LvglKeyboardCtx*>(malloc(sizeof(struct LvglKeyboardCtx)));
+    if (ctx == NULL) {
+        return ERROR_OUT_OF_MEMORY;
+    }
+    ctx->device = device;
+
+    lv_indev_t* indev = lv_indev_create();
+    if (indev == NULL) {
+        free(ctx);
+        return ERROR_OUT_OF_MEMORY;
+    }
+
+    lv_indev_set_type(indev, LV_INDEV_TYPE_KEYPAD);
+    lv_indev_set_read_cb(indev, lvgl_keyboard_read_cb);
+    lv_indev_set_driver_data(indev, ctx);
+    if (display != NULL) {
+        lv_indev_set_display(indev, display);
+    }
+
+    *out_indev = indev;
+    return ERROR_NONE;
+}
+
+void lvgl_keyboard_remove(lv_indev_t* indev) {
+    if (indev == NULL) {
+        return;
+    }
+
+    LvglKeyboardCtx* ctx = (struct LvglKeyboardCtx*)lv_indev_get_driver_data(indev);
+    lv_indev_delete(indev);
+    free(ctx);
+}
+
+void lvgl_keyboard_enable(lv_indev_t* indev) {
+    check(keyboard_group != nullptr);
+    lv_indev_set_group(indev, keyboard_group);
+}
+
+void lvgl_keyboard_disable(lv_indev_t* indev) {
+    lv_indev_set_group(indev, nullptr);
+}
+
+bool lvgl_hardware_keyboard_is_available() {
+    Device* keyboard_device;
+    if (device_get_first_active_by_type(&KEYBOARD_TYPE, &keyboard_device) != ERROR_NONE) {
+        return false;
+    }
+
+    device_put(keyboard_device);
+    return true;
+}
+
+void lvgl_hardware_keyboard_add_custom(lv_indev_t* indev) {
+    LvglKeyboardCtx* ctx = static_cast<struct LvglKeyboardCtx*>(malloc(sizeof(struct LvglKeyboardCtx)));
+    if (ctx == nullptr) {
+        return;
+    }
+
+    ctx->device = nullptr;
+    lv_indev_set_driver_data(indev, ctx);
+
+    lvgl_keyboard_enable(indev);
+}
+
+void lvgl_hardware_keyboard_remove_custom(lv_indev_t* indev) {
+    lvgl_keyboard_disable(indev);
+    auto* data = lv_indev_get_driver_data(indev);
+    lv_indev_set_driver_data(indev, nullptr);
+    free(data); // LvglKeyboardCtx*
+}
+
+static void textarea_show_keyboard(lv_event_t* event) {
+    lv_obj_t* target = lv_event_get_current_target_obj(event);
+    if (last_software_keyboard.object != nullptr) {
+        lvgl_software_keyboard_show(&last_software_keyboard, target);
+        lv_obj_scroll_to_view(target, LV_ANIM_ON);
+    }
+}
+
+static void textarea_hide_keyboard(lv_event_t* event) {
+    if (last_software_keyboard.object != nullptr) {
+        lvgl_software_keyboard_hide(&last_software_keyboard);
+    }
+}
+
+void lvgl_software_keyboard_construct(LvglSoftwareKeyboard* keyboard, lv_obj_t* parent) {
+    keyboard->object = lv_keyboard_create(parent);
+    lv_obj_add_flag(keyboard->object, LV_OBJ_FLAG_HIDDEN);
+    last_software_keyboard = *keyboard;
+}
+
+void lvgl_software_keyboard_destruct(LvglSoftwareKeyboard* keyboard) {
+    check(keyboard->object);
+
+    lv_obj_delete(keyboard->object);
+    keyboard->object = nullptr;
+
+    last_software_keyboard = *keyboard;
+}
+
+void lvgl_software_keyboard_show(LvglSoftwareKeyboard* keyboard, lv_obj_t* textarea) {
+    assert(keyboard->object != nullptr);
+    lv_obj_clear_flag(keyboard->object, LV_OBJ_FLAG_HIDDEN);
+    lv_keyboard_set_textarea(keyboard->object, textarea);
+}
+
+void lvgl_software_keyboard_hide(LvglSoftwareKeyboard* keyboard) {
+    assert(keyboard->object != nullptr);
+    lv_obj_add_flag(keyboard->object, LV_OBJ_FLAG_HIDDEN);
+}
+
+bool lvgl_software_keyboard_is_enabled() {
+    return !lvgl_hardware_keyboard_is_available();
+}
+
+LvglSoftwareKeyboard* lvgl_software_keyboard_get_last() {
+    return &last_software_keyboard;
+}
+
+void lvgl_keyboard_add_textarea(LvglSoftwareKeyboard* keyboard, lv_obj_t* textarea) {
+    if (lvgl_software_keyboard_is_enabled()) {
+        lv_obj_add_event_cb(textarea, textarea_show_keyboard, LV_EVENT_FOCUSED, nullptr);
+        lv_obj_add_event_cb(textarea, textarea_hide_keyboard, LV_EVENT_DEFOCUSED, nullptr);
+        lv_obj_add_event_cb(textarea, textarea_hide_keyboard, LV_EVENT_READY, nullptr);
+
+        // lv_obj_t auto-remove themselves from the group when they are destroyed (last checked in LVGL 8.3)
+        lv_group_add_obj(keyboard_group, textarea);
+
+        lvgl_software_keyboard_activate(keyboard);
+    }
+}
+
+void lvgl_software_keyboard_activate(LvglSoftwareKeyboard* keyboard) {
+    auto* indev = lv_indev_get_next(nullptr);
+    check(keyboard_group);
+    while (indev) {
+        if (lv_indev_get_type(indev) == LV_INDEV_TYPE_KEYPAD) {
+            lv_indev_set_group(indev, keyboard_group);
+        }
+        indev = lv_indev_get_next(indev);
+    }
+}
+
+void lvgl_software_keyboard_deactivate(LvglSoftwareKeyboard* keyboard) {
+    auto* indev = lv_indev_get_next(nullptr);
+    while (indev) {
+        if (lv_indev_get_type(indev) == LV_INDEV_TYPE_KEYPAD) {
+            lv_indev_set_group(indev, nullptr);
+        }
+        indev = lv_indev_get_next(indev);
+    }
+}
+
+}

Tactility/Include/Tactility/file/File.h

@@ -1,20 +1,24 @@
 /**
  * All functions in this file can be safely called without manually applying file locks.
- * For calls to C stdlib APIs such as fopen(), always call file::getLock(path) first!
+ * For calls to C stdlib APIs such as fopen(), always lock with file::FileMutexGuard(path) first!
  */
 #pragma once
 
 #include <Tactility/TactilityCore.h>
-#include <Tactility/Lock.h>
+
+#include <tactility/filesystem/file_mutex.h>
 
 #include <cstdio>
 #include <dirent.h>
+#include <functional>
+#include <memory>
+#include <string>
 #include <sys/stat.h>
 #include <vector>
 
 /**
  * @warning SD card access requires a locking mechanism:
- * @warning When using this in the Tactility main project, use `file::getLock()` or `file::withLock()`
+ * @warning When using this in the Tactility main project, use `file::FileMutexGuard`
  */
 namespace tt::file {
 
@@ -46,10 +50,25 @@ struct FileCloser {
 };
 
 /**
- * @param[in] path the path to get a lock for
- * @return a lock instance (never null)
+ * RAII lock over TactilityKernel's file_mutex.h for the file system mount that owns `path`.
+ * Locks in the constructor, unlocks in the destructor - no heap allocation, no virtual dispatch.
  */
-std::shared_ptr<Lock> getLock(const std::string& path) __attribute__((deprecated("Use file_mutex.h from TactilityKernel")));
+class FileMutexGuard final {
+    FileMutex mutex {};
+
+public:
+    explicit FileMutexGuard(const std::string& path) {
+        file_mutex_get(&mutex, path.c_str());
+        file_mutex_lock(&mutex);
+    }
+
+    ~FileMutexGuard() {
+        file_mutex_unlock(&mutex);
+    }
+
+    FileMutexGuard(const FileMutexGuard&) = delete;
+    FileMutexGuard& operator=(const FileMutexGuard&) = delete;
+};
 
 long getSize(FILE* file);
 

Tactility/Include/Tactility/file/ObjectFile.h

@@ -2,12 +2,12 @@
 
 #include <Tactility/file/File.h>
 
+#include <tactility/filesystem/file_mutex.h>
+
 #include <string>
 
-#include "FileLock.h"
-
 /**
- * @warning The functionality below does NOT safely acquire file locks. Use file::getLock() or file::withLock() when using the functionality below.
+ * @warning The functionality below does NOT safely acquire file locks. Use file::FileMutexGuard when using the functionality below.
  */
 namespace tt::file {
 
@@ -45,7 +45,7 @@ class ObjectFileWriter {
     const uint32_t recordSize;
     const uint32_t recordVersion;
     const bool append;
-    const std::shared_ptr<Lock> lock;
+    FileMutex mutex {};
 
     std::unique_ptr<FILE, FileCloser> file;
     uint32_t recordsWritten = 0;
@@ -56,9 +56,10 @@ public:
         filePath(std::move(filePath)),
         recordSize(recordSize),
         recordVersion(recordVersion),
-        append(append),
-        lock(getLock(filePath))
-    {}
+        append(append)
+    {
+        file_mutex_get(&mutex, this->filePath.c_str());
+    }
 
 
     ~ObjectFileWriter() {

Tactility/Include/Tactility/lvgl/Keyboard.h

@@ -1,51 +0,0 @@
-#pragma once
-
-#include <lvgl.h>
-
-namespace tt::lvgl {
-
-/**
- * Show the on-screen keyboard.
- * @param[in] textarea the textarea to focus the input for
- */
-void software_keyboard_show(lv_obj_t* textarea);
-
-/**
- * Hide the on-screen keyboard.
- * Has no effect when the keyboard is not visible.
- */
-void software_keyboard_hide();
-
-/**
- * The on-screen keyboard is only shown when both of these conditions are true:
- *  - there is no hardware keyboard
- *  - TT_CONFIG_FORCE_ONSCREEN_KEYBOARD is set to true in tactility_config.h
- * @return if we should show a on-screen keyboard for text input inside our apps
- */
-bool software_keyboard_is_enabled();
-
-/**
- * Activate the keypad for a widget group.
- * @param group
- */
-void software_keyboard_activate(lv_group_t* group);
-
-/**
- * Deactivate the keypad for the current widget group (if any).
- * You don't have to call this after calling _activate() because widget
- * cleanup automatically removes itself from the group it belongs to.
- */
-void software_keyboard_deactivate();
-
-/**
- * @return true if LVGL is configured with a keypad
- */
-bool hardware_keyboard_is_available();
-
-/**
- * Set the keypad.
- * @param device the keypad device
- */
-void hardware_keyboard_set_indev(lv_indev_t* device);
-
-}

Tactility/Private/Tactility/app/btmanage/BtManagePrivate.h

@@ -17,7 +17,7 @@ class BtManage final : public App {
     State state;
     View view = View(&bindings, &state);
     bool isViewEnabled = false;
-    struct Device* btDevice = nullptr;
+    Device* btDevice = nullptr;
 
 public:
 

Tactility/Private/Tactility/app/files/State.h

@@ -7,6 +7,7 @@
 #include <utility>
 #include <vector>
 #include <dirent.h>
+#include <sys/stat.h>
 
 namespace tt::app::files {
 
@@ -31,6 +32,8 @@ private:
     std::string selected_child_entry;
     PendingAction action = ActionNone;
     std::string pending_paste_dst;
+    struct stat pending_paste_dst_stat {};
+    bool pending_paste_dst_stat_valid = false;
     std::string clipboard_path;
     bool clipboard_is_cut = false;
     bool clipboard_active = false;
@@ -81,6 +84,23 @@ public:
     std::string getPendingPasteDst() const { return pending_paste_dst; }
     void setPendingPasteDst(const std::string& dst) { pending_paste_dst = dst; }
 
+    /** Snapshot dst's stat at confirm-dialog time, so it can be revalidated right before the destructive delete. */
+    void setPendingPasteDstStat(const struct stat& st) {
+        pending_paste_dst_stat = st;
+        pending_paste_dst_stat_valid = true;
+    }
+
+    void clearPendingPasteDstStat() { pending_paste_dst_stat_valid = false; }
+
+    /** True if dst had no prior snapshot (nothing to overwrite) or `st` still matches it. */
+    bool pendingPasteDstMatches(const struct stat& st) const {
+        return !pending_paste_dst_stat_valid ||
+            (pending_paste_dst_stat.st_dev == st.st_dev &&
+             pending_paste_dst_stat.st_ino == st.st_ino &&
+             pending_paste_dst_stat.st_size == st.st_size &&
+             pending_paste_dst_stat.st_mtime == st.st_mtime);
+    }
+
     void setClipboard(const std::string& path, bool is_cut) {
         mutex.withLock([&] {
             clipboard_path = path;

Tactility/Private/Tactility/service/gui/GuiService.h

@@ -10,7 +10,7 @@
 
 #include <tactility/concurrent/dispatcher.h>
 
-#include <lvgl.h>
+#include <lvgl/devices/keyboard.h>
 
 namespace tt::service::gui {
 
@@ -47,8 +47,7 @@ class GuiService final : public Service {
     // App-specific
     std::shared_ptr<app::AppInstance> appToRender = nullptr;
 
-    lv_obj_t* keyboard = nullptr;
-    lv_group_t* keyboardGroup = nullptr;
+    LvglSoftwareKeyboard software_keyboard = {};
 
     bool isStarted = false;
 
@@ -92,6 +91,8 @@ public:
      */
     void softwareKeyboardHide();
 
+    void keyboardAddTextArea(lv_obj_t* textarea);
+
     /**
      * The on-screen keyboard is only shown when both of these conditions are true:
      *  - there is no hardware keyboard
@@ -99,15 +100,6 @@ public:
      * @return if we should show a on-screen keyboard for text input inside our apps
      */
     bool softwareKeyboardIsEnabled();
-
-    /**
-     * Glue code for the on-screen keyboard and the hardware keyboard:
-     *  - Attach automatic hide/show parameters for the on-screen keyboard.
-     *  - Registers the textarea to the default lv_group_t for hardware keyboards.
-     * @param[in] textarea
-     */
-    void keyboardAddTextArea(lv_obj_t* textarea);
-
 };
 
 std::shared_ptr<GuiService> findService();

Tactility/Source/Tactility.cpp

@@ -40,6 +40,7 @@
 #include <tactility/drivers/power_supply.h>
 #include <tactility/drivers/rtc.h>
 #include <tactility/drivers/uart_controller.h>
+#include <tactility/filesystem/file_mutex.h>
 #include <tactility/filesystem/file_system.h>
 #include <tactility/kernel_init.h>
 #include <tactility/log.h>
@@ -323,9 +324,9 @@ void createTempDirectory() {
     auto data_path = getUserDataPath();
     auto temp_path = std::format("{}/tmp", data_path);
     if (!file::isDirectory(temp_path)) {
-        auto lockable = file::getLock(data_path);
-        auto lock = lockable->asScopedLock();
-        if (lock.lock(1000 / portTICK_PERIOD_MS)) {
+        FileMutex mutex;
+        file_mutex_get(&mutex, data_path.c_str());
+        if (file_mutex_try_lock(&mutex, 1000 / portTICK_PERIOD_MS)) {
             if (!file::findOrCreateParentDirectory(temp_path, 0777)) {
                 LOG_E(TAG, "Failed to create %s", data_path.c_str());
             } else if (mkdir(temp_path.c_str(), 0777) == 0) {
@@ -333,6 +334,7 @@ void createTempDirectory() {
             } else {
                 LOG_E(TAG, "Failed to create %s", temp_path.c_str());
             }
+            file_mutex_unlock(&mutex);
         } else {
             LOG_E(TAG, LOG_MESSAGE_MUTEX_LOCK_FAILED_FMT, data_path.c_str());
         }

Tactility/Source/app/AppInstall.cpp

@@ -3,7 +3,6 @@
 #include <Tactility/app/AppManifest.h>
 #include <Tactility/app/AppRegistration.h>
 #include <Tactility/file/File.h>
-#include <Tactility/file/FileLock.h>
 #include <Tactility/Paths.h>
 
 #include <cerrno>
@@ -14,6 +13,7 @@
 #include <unistd.h>
 
 #include <minitar.h>
+#include <tactility/filesystem/file_mutex.h>
 #include <tactility/log.h>
 
 namespace tt::app {
@@ -117,19 +117,21 @@ bool install(const std::string& path) {
         return false;
     }
 
-    auto target_path_lockable = file::getLock(app_parent_path);
-    auto source_path_lockable = file::getLock(path);
-    auto target_path_lock = target_path_lockable->asScopedLock();
-    auto source_path_lock = source_path_lockable->asScopedLock();
-    target_path_lock.lock();
-    source_path_lock.lock();
+    FileMutex target_path_mutex;
+    file_mutex_get(&target_path_mutex, app_parent_path.c_str());
+    FileMutex source_path_mutex;
+    file_mutex_get(&source_path_mutex, path.c_str());
+
+    file_mutex_lock(&target_path_mutex);
+    file_mutex_lock(&source_path_mutex);
     LOG_I(TAG, "Extracting app from %s to %s", path.c_str(), app_target_path.c_str());
-    if (!untar(path, app_target_path)) {
+    bool untar_success = untar(path, app_target_path);
+    file_mutex_unlock(&source_path_mutex);
+    file_mutex_unlock(&target_path_mutex);
+    if (!untar_success) {
         LOG_E(TAG, "Failed to extract");
         return false;
     }
-    source_path_lock.unlock();
-    target_path_lock.unlock();
 
     auto manifest_path = app_target_path + "/manifest.properties";
     if (!file::isFile(manifest_path)) {
@@ -159,9 +161,9 @@ bool install(const std::string& path) {
         }
     }
 
-    target_path_lock.lock();
+    file_mutex_lock(&target_path_mutex);
     bool rename_success = rename(app_target_path.c_str(), renamed_target_path.c_str()) == 0;
-    target_path_lock.unlock();
+    file_mutex_unlock(&target_path_mutex);
 
     if (!rename_success) {
         LOG_E(TAG, R"(Failed to rename "%s" to "%s")", app_target_path.c_str(), manifest.appId.c_str());

Tactility/Source/app/ElfApp.cpp

@@ -75,9 +75,10 @@ private:
         assert(elfFileData == nullptr);
 
         size_t size = 0;
-        file::getLock(elf_path)->withLock([this, &elf_path, &size]{
+        {
+            file::FileMutexGuard guard(elf_path);
             elfFileData = file::readBinary(elf_path, size);
-        });
+        }
 
         if (elfFileData == nullptr) {
             return false;

Tactility/Source/app/apphub/AppHubEntry.cpp

@@ -21,9 +21,7 @@ static bool parseEntry(const cJSON* object, AppHubEntry& entry) {
 }
 
 bool parseJson(const std::string& filePath, std::vector<AppHubEntry>& entries) {
-    auto lockable = file::getLock(filePath);
-    auto lock = lockable->asScopedLock();
-    lock.lock();
+    file::FileMutexGuard guard(filePath);
 
     auto data = file::readString(filePath);
     if (data == nullptr) {

Tactility/Source/app/boot/Boot.cpp

@@ -54,13 +54,8 @@ class BootApp : public App {
     );
 
     static void setupDisplay() {
-        auto* display = device_find_first_by_type(&DISPLAY_TYPE);
-        // Boards not yet migrated to the kernel display driver register a placeholder device (so
-        // the devicetree node resolves) with a NULL api - nothing for this function to act on.
-        if (display != nullptr && device_get_driver(display)->api == nullptr) {
-            display = nullptr;
-        }
-        if (display != nullptr) {
+        Device* display = nullptr;
+        if (device_get_first_by_type(&DISPLAY_TYPE, &display) == ERROR_NONE) {
             Device* backlight;
             if (display_get_backlight(display, &backlight) == ERROR_NONE) {
                 if (!device_is_ready(backlight)) {
@@ -83,6 +78,7 @@ class BootApp : public App {
             } else {
                 LOG_I(TAG, "No backlight for %s", display->name);
             }
+            device_put(display);
         } else {
             LOG_I(TAG, "No kernel display");
         }

Tactility/Source/app/btmanage/BtManage.cpp

@@ -18,25 +18,38 @@ extern const AppManifest manifest;
 
 static void onBtToggled(bool requestOn) {
 #if defined(CONFIG_BT_NIMBLE_ENABLED)
-    Device* dev = device_find_first_by_type(&BLUETOOTH_TYPE);
-    if (!dev) return;
-    bool radio_on = bluetooth::isRadioOnOrPending(dev);
-    if (requestOn && !radio_on) {
-        bluetooth::start(dev);
-    } else if (!requestOn && radio_on) {
-        bluetooth::stop(dev);
+    Device* dev;
+    if (device_get_first_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE) {
+        bool radio_on = bluetooth::isRadioOnOrPending(dev);
+        if (requestOn && !radio_on) {
+            LOG_I(TAG, "Turning on");
+            bluetooth::start(dev);
+        } else if (!requestOn && radio_on) {
+            LOG_I(TAG, "Turning off");
+            bluetooth::stop(dev);
+        }
+        device_put(dev);
+    } else {
+        LOG_W(TAG, "Toggle: No bluetooth device found");
     }
+
 #endif
 }
 
 static void onScanToggled(bool enabled) {
-    Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE);
-    if (!dev) return;
+    Device* dev;
+    if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) != ERROR_NONE) {
+        LOG_W(TAG, "Scan: No bluetooth device found");
+        return;
+    }
+
     if (enabled) {
         bluetooth_scan_start(dev);
     } else {
         bluetooth_scan_stop(dev);
     }
+
+    device_put(dev);
 }
 
 static void onConnectPeer(const std::array<uint8_t, 6>& addr, int profileId) {
@@ -86,7 +99,7 @@ void BtManage::requestViewUpdate() {
     unlock();
 }
 
-void BtManage::onBtEvent(const struct BtEvent& event) {
+void BtManage::onBtEvent(const BtEvent& event) {
     auto radio_state = bluetooth::getRadioState();
     LOG_I(TAG, "Update with state %s", bluetooth::radioStateToString(radio_state));
     getState().setRadioState(radio_state);
@@ -112,10 +125,13 @@ void BtManage::onBtEvent(const struct BtEvent& event) {
         case BT_EVENT_RADIO_STATE_CHANGED:
             if (event.radio_state == BT_RADIO_STATE_ON) {
                 getState().updatePairedPeers();
-                Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE);
-                if (dev && !bluetooth_is_scanning(dev)) {
+                Device* dev = nullptr;
+                if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE && !bluetooth_is_scanning(dev)) {
                     bluetooth_scan_start(dev);
                 }
+                if (dev) {
+                    device_put(dev);
+                }
             }
             break;
         default:
@@ -141,7 +157,9 @@ void BtManage::onShow(AppContext& app, lv_obj_t* parent) {
     // Initialise state and view before subscribing to avoid incoming events
     // racing with state initialisation.
     state.setRadioState(bluetooth::getRadioState());
-    Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE);
+    Device* dev = nullptr;
+    device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev);
+
     state.setScanning(dev ? bluetooth_is_scanning(dev) : false);
     state.updateScanResults();
     state.updatePairedPeers();
@@ -152,6 +170,11 @@ void BtManage::onShow(AppContext& app, lv_obj_t* parent) {
     view.update();
     unlock();
 
+    if (btDevice) {
+        // Decrease refcount before re-ssignment
+        device_put(btDevice);
+    }
+
     btDevice = dev;
     if (btDevice) {
         bluetooth_add_event_callback(btDevice, this, onKernelBtEvent);
@@ -172,6 +195,7 @@ void BtManage::onHide(AppContext& app) {
     lock();
     if (btDevice) {
         bluetooth_remove_event_callback(btDevice, onKernelBtEvent);
+        device_put(btDevice);
         btDevice = nullptr;
     }
     isViewEnabled = false;

Tactility/Source/app/btmanage/View.cpp

@@ -46,8 +46,12 @@ static void onEnableOnBootParentClicked(lv_event_t* event) {
 
 static void onScanButtonClicked(lv_event_t* event) {
     auto bt = std::static_pointer_cast<BtManage>(getCurrentApp());
-    Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE);
+    Device* dev = nullptr;
+    device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev);
     bool scanning = dev ? bluetooth_is_scanning(dev) : false;
+    if (dev) {
+        device_put(dev);
+    }
     bt->getBindings().onScanToggled(!scanning);
 }
 

Tactility/Source/app/btpeersettings/BtPeerSettings.cpp

@@ -121,8 +121,12 @@ public:
     }
 
     void onShow(AppContext& app, lv_obj_t* parent) override {
-        if (Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE)) {
-            bluetooth_add_event_callback(dev, this, onKernelBtEvent);
+        {
+            Device* dev;
+            if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE) {
+                bluetooth_add_event_callback(dev, this, onKernelBtEvent);
+                device_put(dev);
+            }
         }
 
         // Load stored settings (name, autoConnect)
@@ -189,8 +193,10 @@ public:
     }
 
     void onHide(AppContext& app) override {
-        if (Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE)) {
+        Device* dev;
+        if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE) {
             bluetooth_remove_event_callback(dev, onKernelBtEvent);
+            device_put(dev);
         }
         viewEnabled = false;
     }

Tactility/Source/app/files/View.cpp

@@ -13,6 +13,7 @@
 #include <tactility/check.h>
 #include <tactility/device.h>
 #include <tactility/drivers/usb_host_msc.h>
+#include <tactility/filesystem/file_mutex.h>
 #include <tactility/log.h>
 
 #include <lvgl/lvgl.h>
@@ -101,17 +102,21 @@ static void onPastePressedCallback(lv_event_t* event) {
 // region File helpers
 
 static bool copyFileContents(const std::string& src, const std::string& dst) {
-    auto src_lock = file::getLock(src);
-    auto dst_lock = file::getLock(dst);
-    const bool same_lock = (src_lock.get() == dst_lock.get());
+    FileMutex src_mutex;
+    file_mutex_get(&src_mutex, src.c_str());
+    FileMutex dst_mutex;
+    file_mutex_get(&dst_mutex, dst.c_str());
+    const bool same_lock = (src_mutex.lock == dst_mutex.lock &&
+        src_mutex.try_lock == dst_mutex.try_lock &&
+        src_mutex.unlock == dst_mutex.unlock);
 
     auto unlock_all = [&] {
-        if (!same_lock) dst_lock->unlock();
-        src_lock->unlock();
+        if (!same_lock) file_mutex_unlock(&dst_mutex);
+        file_mutex_unlock(&src_mutex);
     };
 
-    src_lock->lock();
-    if (!same_lock) dst_lock->lock();
+    file_mutex_lock(&src_mutex);
+    if (!same_lock) file_mutex_lock(&dst_mutex);
 
     FILE* in = fopen(src.c_str(), "rb");
     if (in == nullptr) {
@@ -155,11 +160,12 @@ static bool copyRecursive(const std::string& src, const std::string& dst) {
 
         // Process one entry at a time: release the device lock between iterations
         // so other SPI bus users aren't starved, and stop immediately on failure.
-        auto lock = file::getLock(src);
-        lock->lock();
+        FileMutex mutex;
+        file_mutex_get(&mutex, src.c_str());
+        file_mutex_lock(&mutex);
         DIR* dir = opendir(src.c_str());
         if (!dir) {
-            lock->unlock();
+            file_mutex_unlock(&mutex);
             file::deleteRecursively(dst);
             return false;
         }
@@ -171,14 +177,14 @@ static bool copyRecursive(const std::string& src, const std::string& dst) {
             if (strcmp(entry->d_name, ".") == 0 || strcmp(entry->d_name, "..") == 0) continue;
 
             std::string name = entry->d_name; // copy before releasing lock
-            lock->unlock();
+            file_mutex_unlock(&mutex);
 
             success = copyRecursive(file::getChildPath(src, name), file::getChildPath(dst, name));
 
-            lock->lock();
+            file_mutex_lock(&mutex);
         }
         closedir(dir);
-        lock->unlock();
+        file_mutex_unlock(&mutex);
 
         if (!success) {
             file::deleteRecursively(dst);
@@ -436,12 +442,16 @@ void View::onEjectPressed() {
     std::string mount_path = state->getSelectedChildPath();
     LOG_I(TAG, "Ejecting %s", mount_path.c_str());
 
-    struct Device* msc_dev = device_find_first_active_by_type(&USB_HOST_MSC_TYPE);
-    if (!msc_dev || !usb_msc_eject(msc_dev, mount_path.c_str())) {
+    Device* msc_dev = nullptr;
+    if (device_get_first_active_by_type(&USB_HOST_MSC_TYPE, &msc_dev) != ERROR_NONE || !usb_msc_eject(msc_dev, mount_path.c_str())) {
         LOG_W(TAG, "usb_msc_eject: %s not found", mount_path.c_str());
         alertdialog::start("Eject failed", "Could not eject \"" + file::getLastPathSegment(mount_path) + "\".");
     }
 
+    if (msc_dev) {
+        device_put(msc_dev);
+    }
+
     onNavigate();
     state->setEntriesForPath(state->getCurrentPath());
     update();
@@ -589,12 +599,10 @@ void View::onResult(LaunchId launchId, Result result, std::unique_ptr<Bundle> bu
                         LOG_W(TAG, "Failed to delete %s", filepath.c_str());
                     }
                 } else if (file::isFile(filepath)) {
-                    auto lock = file::getLock(filepath);
-                    lock->lock();
+                    file::FileMutexGuard guard(filepath);
                     if (remove(filepath.c_str()) != 0) {
                         LOG_W(TAG, "Failed to delete %s", filepath.c_str());
                     }
-                    lock->unlock();
                 }
 
                 state->setEntriesForPath(state->getCurrentPath());
@@ -605,23 +613,22 @@ void View::onResult(LaunchId launchId, Result result, std::unique_ptr<Bundle> bu
         case State::ActionRename: {
             auto new_name = inputdialog::getResult(*bundle);
             if (!new_name.empty() && new_name != state->getSelectedChildEntry()) {
-                auto lock = file::getLock(filepath);
-                lock->lock();
                 std::string rename_to = file::getChildPath(state->getCurrentPath(), new_name);
-                struct stat st;
-                if (stat(rename_to.c_str(), &st) == 0) {
-                    LOG_W(TAG, "Rename: destination already exists: \"%s\"", rename_to.c_str());
-                    lock->unlock();
-                    state->setPendingAction(State::ActionNone);
-                    alertdialog::start("Rename failed", "\"" + new_name + "\" already exists.");
-                    break;
+                {
+                    file::FileMutexGuard guard(filepath);
+                    struct stat st;
+                    if (stat(rename_to.c_str(), &st) == 0) {
+                        LOG_W(TAG, "Rename: destination already exists: \"%s\"", rename_to.c_str());
+                        state->setPendingAction(State::ActionNone);
+                        alertdialog::start("Rename failed", "\"" + new_name + "\" already exists.");
+                        break;
+                    }
+                    if (rename(filepath.c_str(), rename_to.c_str()) == 0) {
+                        LOG_I(TAG, "Renamed \"%s\" to \"%s\"", filepath.c_str(), rename_to.c_str());
+                    } else {
+                        LOG_E(TAG, "Failed to rename \"%s\" to \"%s\"", filepath.c_str(), rename_to.c_str());
+                    }
                 }
-                if (rename(filepath.c_str(), rename_to.c_str()) == 0) {
-                    LOG_I(TAG, "Renamed \"%s\" to \"%s\"", filepath.c_str(), rename_to.c_str());
-                } else {
-                    LOG_E(TAG, "Failed to rename \"%s\" to \"%s\"", filepath.c_str(), rename_to.c_str());
-                }
-                lock->unlock();
 
                 state->setEntriesForPath(state->getCurrentPath());
                 update();
@@ -633,24 +640,23 @@ void View::onResult(LaunchId launchId, Result result, std::unique_ptr<Bundle> bu
             if (!filename.empty()) {
                 std::string new_file_path = file::getChildPath(state->getCurrentPath(), filename);
 
-                auto lock = file::getLock(new_file_path);
-                lock->lock();
+                {
+                    file::FileMutexGuard guard(new_file_path);
 
-                struct stat st;
-                if (stat(new_file_path.c_str(), &st) == 0) {
-                    LOG_W(TAG, "File already exists: \"%s\"", new_file_path.c_str());
-                    lock->unlock();
-                    break;
-                }
+                    struct stat st;
+                    if (stat(new_file_path.c_str(), &st) == 0) {
+                        LOG_W(TAG, "File already exists: \"%s\"", new_file_path.c_str());
+                        break;
+                    }
 
-                FILE* new_file = fopen(new_file_path.c_str(), "w");
-                if (new_file) {
-                    fclose(new_file);
-                    LOG_I(TAG, "Created file \"%s\"", new_file_path.c_str());
-                } else {
-                    LOG_E(TAG, "Failed to create file \"%s\"", new_file_path.c_str());
+                    FILE* new_file = fopen(new_file_path.c_str(), "w");
+                    if (new_file) {
+                        fclose(new_file);
+                        LOG_I(TAG, "Created file \"%s\"", new_file_path.c_str());
+                    } else {
+                        LOG_E(TAG, "Failed to create file \"%s\"", new_file_path.c_str());
+                    }
                 }
-                lock->unlock();
 
                 state->setEntriesForPath(state->getCurrentPath());
                 update();
@@ -662,22 +668,21 @@ void View::onResult(LaunchId launchId, Result result, std::unique_ptr<Bundle> bu
             if (!foldername.empty()) {
                 std::string new_folder_path = file::getChildPath(state->getCurrentPath(), foldername);
 
-                auto lock = file::getLock(new_folder_path);
-                lock->lock();
+                {
+                    file::FileMutexGuard guard(new_folder_path);
 
-                struct stat st;
-                if (stat(new_folder_path.c_str(), &st) == 0) {
-                    LOG_W(TAG, "Folder already exists: \"%s\"", new_folder_path.c_str());
-                    lock->unlock();
-                    break;
-                }
+                    struct stat st;
+                    if (stat(new_folder_path.c_str(), &st) == 0) {
+                        LOG_W(TAG, "Folder already exists: \"%s\"", new_folder_path.c_str());
+                        break;
+                    }
 
-                if (mkdir(new_folder_path.c_str(), 0755) == 0) {
-                    LOG_I(TAG, "Created folder \"%s\"", new_folder_path.c_str());
-                } else {
-                    LOG_E(TAG, "Failed to create folder \"%s\"", new_folder_path.c_str());
+                    if (mkdir(new_folder_path.c_str(), 0755) == 0) {
+                        LOG_I(TAG, "Created folder \"%s\"", new_folder_path.c_str());
+                    } else {
+                        LOG_E(TAG, "Failed to create folder \"%s\"", new_folder_path.c_str());
+                    }
                 }
-                lock->unlock();
 
                 state->setEntriesForPath(state->getCurrentPath());
                 update();
@@ -689,6 +694,30 @@ void View::onResult(LaunchId launchId, Result result, std::unique_ptr<Bundle> bu
                 auto clipboard = state->getClipboard();
                 if (clipboard.has_value()) {
                     std::string dst = state->getPendingPasteDst();
+
+                    // dst was last checked before the dialog was shown; a writer could
+                    // have replaced it while the user was looking at the confirmation.
+                    // Revalidate right before the destructive delete so we only ever
+                    // remove the exact file the user agreed to overwrite.
+                    bool dst_unchanged;
+                    {
+                        file::FileMutexGuard guard(dst);
+                        struct stat current_stat {};
+                        dst_unchanged = (stat(dst.c_str(), &current_stat) == 0) &&
+                            state->pendingPasteDstMatches(current_stat);
+                    }
+                    state->clearPendingPasteDstStat();
+
+                    if (!dst_unchanged) {
+                        LOG_W(TAG, "Overwrite: destination \"%s\" changed since confirmation, aborting", dst.c_str());
+                        state->setPendingAction(State::ActionNone);
+                        alertdialog::start(
+                            "Overwrite aborted",
+                            "\"" + file::getLastPathSegment(dst) + "\" changed while the dialog was open. Please try again."
+                        );
+                        break;
+                    }
+
                     // Trade-off: dst is removed before the copy attempt. If doPaste
                     // subsequently fails (e.g. source read error, out of space), the
                     // original dst data is unrecoverable. Acceptable for an embedded
@@ -705,6 +734,8 @@ void View::onResult(LaunchId launchId, Result result, std::unique_ptr<Bundle> bu
                         );
                     }
                 }
+            } else {
+                state->clearPendingPasteDstStat();
             }
             break;
         }
@@ -738,23 +769,28 @@ void View::onPastePressed() {
     std::string entry_name = file::getLastPathSegment(src);
     std::string dst = file::getChildPath(state->getCurrentPath(), entry_name);
 
-    // Note: getLock(src) guards the source path; the existence check below is
-    // against dst, so there is a TOCTOU gap — another writer could create dst
-    // between this check and the write inside doPaste.  Acceptable on a
-    // single-user embedded device; locking dst instead would be more correct.
+    // Note: FileMutexGuard(src) guards the source path; the existence check below is
+    // against dst, so there is a TOCTOU gap between this check and the write inside
+    // doPaste. When dst exists, the overwrite-confirm path below re-validates dst's
+    // stat immediately before the destructive delete (see ActionPaste in onResult),
+    // closing the window that matters (the dialog being open). When dst does not
+    // exist here, doPaste's write can still race a concurrent creator; acceptable on
+    // a single-user embedded device.
     if (src == dst) {
         LOG_I(TAG, "Paste: source and destination are the same path, skipping");
         return;
     }
-    auto lock = file::getLock(src);
-    lock->lock();
 
-    struct stat st;
-    bool dst_exists = (stat(dst.c_str(), &st) == 0);
-    lock->unlock();
+    bool dst_exists;
+    struct stat dst_stat {};
+    {
+        file::FileMutexGuard guard(src);
+        dst_exists = (stat(dst.c_str(), &dst_stat) == 0);
+    }
 
     if (dst_exists) {
         state->setPendingPasteDst(dst);
+        state->setPendingPasteDstStat(dst_stat);
         state->setPendingAction(State::ActionPaste);
         const std::vector<std::string> choices = {"Overwrite", "Cancel"};
         alertdialog::start("File exists", "Overwrite \"" + entry_name + "\"?", choices);
@@ -768,10 +804,10 @@ void View::doPaste(const std::string& src, bool is_cut, const std::string& dst)
     bool success = false;
     bool src_delete_failed = false;
     if (is_cut) {
-        auto lock = file::getLock(src);
-        lock->lock();
-        success = (rename(src.c_str(), dst.c_str()) == 0);
-        lock->unlock();
+        {
+            file::FileMutexGuard guard(src);
+            success = (rename(src.c_str(), dst.c_str()) == 0);
+        }
         if (!success) {
             // Fallback for cross-filesystem moves: copy then delete.
             // Only mark success if both halves succeed — if the source removal

Tactility/Source/app/kerneldisplay/KernelDisplay.cpp

@@ -25,15 +25,18 @@ namespace tt::app::kerneldisplay {
 constexpr auto* TAG = "KernelDisplay";
 
 static Device* getBacklightDevice() {
-    Device* display = device_find_first_by_type(&DISPLAY_TYPE);
-    check(display);
+    Device* display;
+    check(device_get_first_by_type(&DISPLAY_TYPE, &display) == ERROR_NONE);
     // Boards not yet migrated to the kernel display driver register a placeholder device (so the
     // devicetree node resolves) with a NULL api - nothing for display_get_backlight() to act on.
     if (device_get_driver(display)->api == nullptr) {
+        device_put(display);
         return nullptr;
     }
     Device* backlight = nullptr;
-    return display_get_backlight(display, &backlight) == ERROR_NONE ? backlight : nullptr;
+    display_get_backlight(display, &backlight);
+    device_put(display);
+    return backlight;
 }
 
 class KernelDisplayApp final : public App {

Tactility/Source/app/keyboard/KeyboardSettings.cpp

@@ -28,9 +28,10 @@ static uint32_t timeoutMsToIndex(uint32_t ms) {
 
 static void applyKeyboardBacklight(bool enabled, uint8_t brightness) {
     // TODO: Get keyboard backlight from (optional) keyboard child device
-    Device* backlight = device_find_by_name("keyboard_backlight");
-    if (backlight != nullptr) {
+    Device* backlight;
+    if (device_get_by_name("keyboard_backlight", &backlight) == ERROR_NONE) {
         backlight_set_brightness(backlight, enabled ? brightness : 0);
+        device_put(backlight);
     }
 }
 

Tactility/Source/app/notes/Notes.cpp

@@ -2,7 +2,6 @@
 
 #include <Tactility/app/AppManifest.h>
 #include <Tactility/app/fileselection/FileSelection.h>
-#include <Tactility/file/FileLock.h>
 #include <Tactility/lvgl/Toolbar.h>
 #include <Tactility/file/File.h>
 
@@ -83,29 +82,29 @@ class NotesApp final : public App {
 
     void openFile(const std::string& path) {
         // We might be reading from the SD card, which could share a SPI bus with other devices (display)
-        file::getLock(path)->withLock([this, path] {
-            auto data = file::readString(path);
-            if (data != nullptr) {
-                lvgl_lock();
-                lv_textarea_set_text(uiNoteText, reinterpret_cast<const char*>(data.get()));
-                lv_label_set_text(uiCurrentFileName, path.c_str());
-                lvgl_unlock();
-                filePath = path;
-                LOG_I(TAG, "Loaded from %s", path.c_str());
-            }
-        });
+        file::FileMutexGuard guard(path);
+        auto data = file::readString(path);
+        if (data != nullptr) {
+            lvgl_lock();
+            lv_textarea_set_text(uiNoteText, reinterpret_cast<const char*>(data.get()));
+            lv_label_set_text(uiCurrentFileName, path.c_str());
+            lvgl_unlock();
+            filePath = path;
+            LOG_I(TAG, "Loaded from %s", path.c_str());
+        }
     }
 
     bool saveFile(const std::string& path) {
         // We might be writing to SD card, which could share a SPI bus with other devices (display)
         bool result = false;
-        file::getLock(path)->withLock([&result, this, path] {
-           if (file::writeString(path, saveBuffer.c_str())) {
-               LOG_I(TAG, "Saved to %s", path.c_str());
-               filePath = path;
-               result = true;
-           }
-        });
+        {
+            file::FileMutexGuard guard(path);
+            if (file::writeString(path, saveBuffer.c_str())) {
+                LOG_I(TAG, "Saved to %s", path.c_str());
+                filePath = path;
+                result = true;
+            }
+        }
         return result;
     }
 

Tactility/Source/bluetooth/Bluetooth.cpp

@@ -124,8 +124,10 @@ static void bt_event_bridge(Device*, void* /*context*/, BtEvent event) {
                         }
                         if (has_hid_host_auto) {
                             LOG_I(TAG, "HID host auto-connect peer found — starting scan");
-                            if (Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE)) {
+                            Device* dev;
+                            if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE) {
                                 bluetooth_scan_start(dev);
+                                device_put(dev);
                             }
                         } else if (has_hid_device_auto) {
                             LOG_I(TAG, "HID device auto-start (bonded peer found)");
@@ -231,10 +233,12 @@ static void bt_event_bridge(Device*, void* /*context*/, BtEvent event) {
                         }
                     }
                     if (has_auto) {
-                        if (Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE)) {
+                        Device* dev;
+                        if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE) {
                             if (!bluetooth_is_scanning(dev)) {
                                 bluetooth_scan_start(dev);
                             }
+                            device_put(dev);
                         }
                     }
                 });
@@ -337,10 +341,19 @@ const char* radioStateToString(RadioState state) {
 }
 
 RadioState getRadioState() {
-    Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE);
-    if (dev == nullptr) return RadioState::Off;
     BtRadioState state = BT_RADIO_STATE_OFF;
-    bluetooth_get_radio_state(dev, &state);
+
+    // Scoped to safeguard dev usage
+    {
+        Device* dev = nullptr;
+        device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev);
+        if (dev == nullptr) {
+            return RadioState::Off;
+        }
+        bluetooth_get_radio_state(dev, &state);
+        device_put(dev);
+    }
+
     switch (state) {
         case BT_RADIO_STATE_OFF:         return RadioState::Off;
         case BT_RADIO_STATE_ON_PENDING:  return RadioState::OnPending;
@@ -405,9 +418,10 @@ void pair(const std::array<uint8_t, 6>& /*addr*/) {
 }
 
 void unpair(const std::array<uint8_t, 6>& addr) {
-    Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE);
-    if (dev != nullptr) {
+    Device* dev;
+    if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE) {
         bluetooth_unpair(dev, addr.data());
+        device_put(dev);
     }
     settings::remove(settings::addrToHex(addr));
 }
@@ -442,9 +456,11 @@ void disconnect(const std::array<uint8_t, 6>& addr, int profileId) {
             bluetooth_hid_device_stop(dev);
         }
     } else {
-        Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE);
-        if (dev == nullptr) return;
-        bluetooth_disconnect(dev, addr.data(), (BtProfileId)profileId);
+        Device* dev;
+        if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE) {
+            bluetooth_disconnect(dev, addr.data(), (BtProfileId)profileId);
+            device_put(dev);
+        }
     }
 }
 

Tactility/Source/bluetooth/BluetoothHidHost.cpp

@@ -10,7 +10,6 @@
 
 #include <Tactility/Assets.h>
 #include <Tactility/Tactility.h>
-#include <Tactility/lvgl/Keyboard.h>
 
 #include <tactility/log.h>
 
@@ -22,6 +21,7 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/queue.h>
 
+#include <lvgl/devices/keyboard.h>
 #include <lvgl/lvgl.h>
 
 #include <algorithm>
@@ -470,11 +470,12 @@ static void hidHostSubscribeNext(HidHostCtx& ctx) {
         getMainDispatcher().dispatch([] {
             if (!hid_host_ctx || hid_host_ctx->kbIndev != nullptr) return;
             if (!lvgl_try_lock(1000)) { LOG_W(TAG, "LVGL lock failed for kb indev"); return; }
+
             auto* kb = lv_indev_create();
             lv_indev_set_type(kb, LV_INDEV_TYPE_KEYPAD);
             lv_indev_set_read_cb(kb, hidHostKeyboardReadCb);
             hid_host_ctx->kbIndev = kb;
-            lvgl::hardware_keyboard_set_indev(kb);
+            lvgl_hardware_keyboard_add_custom(kb);
             lvgl_unlock();
             LOG_I(TAG, "Keyboard indev registered");
         });
@@ -500,12 +501,14 @@ static void hidHostSubscribeNext(HidHostCtx& ctx) {
             }
             device.name = name;
             settings::save(device);
-            if (Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE)) {
+            Device* dev;
+            if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE) {
                 BtEvent e = {};
                 e.type = BT_EVENT_PROFILE_STATE_CHANGED;
                 e.profile_state.state = BT_PROFILE_STATE_CONNECTED;
                 e.profile_state.profile = BT_PROFILE_HID_HOST;
                 bluetooth_fire_event(dev, e);
+                device_put(dev);
             }
         });
         return;
@@ -660,13 +663,15 @@ static int hidHostGapCb(struct ble_gap_event* event, void* /*arg*/) {
             } else {
                 LOG_W(TAG, "Connect failed status=%d", event->connect.status);
                 hid_host_ctx.reset();
-                if (Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE)) {
+                Device* dev;
+                if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE) {
                     bluetooth_set_hid_host_active(dev, false);
-                    struct BtEvent e = {};
+                    BtEvent e = {};
                     e.type = BT_EVENT_PROFILE_STATE_CHANGED;
                     e.profile_state.state = BT_PROFILE_STATE_IDLE;
                     e.profile_state.profile = BT_PROFILE_HID_HOST;
                     bluetooth_fire_event(dev, e);
+                    device_put(dev);
                 }
             }
             break;
@@ -685,13 +690,15 @@ static int hidHostGapCb(struct ble_gap_event* event, void* /*arg*/) {
             hid_host_mouse_btn.store(false);
             hid_host_mouse_active.store(false);
 
-            if (Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE)) {
+            Device* dev;
+            if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE) {
                 bluetooth_set_hid_host_active(dev, false);
                 struct BtEvent e = {};
                 e.type = BT_EVENT_PROFILE_STATE_CHANGED;
                 e.profile_state.state = BT_PROFILE_STATE_IDLE;
                 e.profile_state.profile = BT_PROFILE_HID_HOST;
                 bluetooth_fire_event(dev, e);
+                device_put(dev);
             }
 
             getMainDispatcher().dispatch([saved_kb, saved_mouse, saved_cursor, saved_queue] {
@@ -701,7 +708,7 @@ static int hidHostGapCb(struct ble_gap_event* event, void* /*arg*/) {
                     return;
                 }
                 if (saved_kb) {
-                    lvgl::hardware_keyboard_set_indev(nullptr);
+                    lvgl_hardware_keyboard_remove_custom(saved_kb);
                     lv_indev_delete(saved_kb);
                 }
                 if (saved_mouse)  lv_indev_delete(saved_mouse);
@@ -793,7 +800,13 @@ void hidHostConnect(const std::array<uint8_t, 6>& addr) {
     }
 
     // Notify driver that a HID host central connection is starting.
-    if (Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE)) bluetooth_set_hid_host_active(dev, true);
+    {
+        Device* dev;
+        if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE) {
+            bluetooth_set_hid_host_active(dev, true);
+            device_put(dev);
+        }
+    }
 
     // Look up the addr_type from the cached scan results.
     ble_addr_t ble_addr = {};
@@ -813,7 +826,8 @@ void hidHostConnect(const std::array<uint8_t, 6>& addr) {
     if (rc != 0) {
         LOG_W(TAG, "ble_gap_connect failed rc=%d", rc);
         hid_host_ctx.reset();
-        if (Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE)) {
+        Device* dev;
+        if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE) {
             bluetooth_set_hid_host_active(dev, false);
             // Fire IDLE so bt_event_bridge can start a new scan and retry.
             BtEvent e = {};
@@ -821,6 +835,7 @@ void hidHostConnect(const std::array<uint8_t, 6>& addr) {
             e.profile_state.state   = BT_PROFILE_STATE_IDLE;
             e.profile_state.profile = BT_PROFILE_HID_HOST;
             bluetooth_fire_event(dev, e);
+            device_put(dev);
         }
     } else {
         LOG_I(TAG, "Connecting...");
@@ -867,11 +882,13 @@ void autoConnectHidHost() {
     auto peers = settings::loadAll();
     for (const auto& peer : peers) {
         if (peer.autoConnect && peer.profileId == BT_PROFILE_HID_HOST) {
-            if (Device* dev = device_find_first_active_by_type(&BLUETOOTH_TYPE)) {
+            Device* dev;
+            if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &dev) == ERROR_NONE) {
                 if (!bluetooth_is_scanning(dev)) {
                     LOG_I(TAG, "Auto-connect HID host: device not in scan, retrying scan");
                     bluetooth_scan_start(dev);
                 }
+                device_put(dev);
             }
             break;
         }

Tactility/Source/file/File.cpp

@@ -4,9 +4,7 @@
 #include <fstream>
 #include <unistd.h>
 
-#include <tactility/filesystem/file_mutex.h>
 #include <tactility/log.h>
-#include <Tactility/Mutex.h>
 #include <Tactility/StringUtils.h>
 
 namespace tt::hal::sdcard {
@@ -17,27 +15,6 @@ namespace tt::file {
 
 constexpr auto* TAG = "file";
 
-class FileMutexLock final : public Lock {
-    FileMutex mutex;
-
-public:
-    explicit FileMutexLock(const std::string& path) {
-        file_mutex_get(&mutex, path.c_str());
-    }
-
-    bool lock(TickType_t timeout) const override {
-        return file_mutex_try_lock(&mutex, timeout);
-    }
-
-    void unlock() const override {
-        file_mutex_unlock(&mutex);
-    }
-};
-
-std::shared_ptr<Lock> getLock(const std::string& path) {
-    return std::make_shared<FileMutexLock>(path);
-}
-
 std::string getChildPath(const std::string& basePath, const std::string& childPath) {
     // Postfix with "/" when the current path isn't "/"
     if (basePath.length() != 1) {
@@ -65,9 +42,7 @@ bool listDirectory(
     const std::string& path,
     std::function<void(const dirent&)> onEntry
 ) {
-    auto lockable = getLock(path);
-    auto lock = lockable->asScopedLock();
-    lock.lock();
+    FileMutexGuard guard(path);
 
     LOG_I(TAG, "listDir start %s", path.c_str());
     DIR* dir = opendir(path.c_str());
@@ -93,9 +68,7 @@ int scandir(
     ScandirFilter filterMethod,
     ScandirSort sortMethod
 ) {
-    auto lockable = getLock(path);
-    auto lock = lockable->asScopedLock();
-    lock.lock();
+    FileMutexGuard guard(path);
 
     LOG_I(TAG, "scandir start");
     DIR* dir = opendir(path.c_str());
@@ -220,9 +193,7 @@ bool writeString(const std::string& filepath, const std::string& content) {
 }
 
 static bool findOrCreateDirectoryInternal(std::string path, mode_t mode) {
-    auto lockable = getLock(path);
-    auto lock = lockable->asScopedLock();
-    lock.lock();
+    FileMutexGuard guard(path);
 
     struct stat dir_stat;
     if (mkdir(path.c_str(), mode) == 0) {
@@ -336,38 +307,28 @@ bool deleteRecursively(const std::string& path) {
 }
 
 bool deleteFile(const std::string& path) {
-    auto lockable = getLock(path);
-    auto lock = lockable->asScopedLock();
-    lock.lock();
+    FileMutexGuard guard(path);
     return remove(path.c_str()) == 0;
 }
 
 bool deleteDirectory(const std::string& path) {
-    auto lockable = getLock(path);
-    auto lock = lockable->asScopedLock();
-    lock.lock();
+    FileMutexGuard guard(path);
     return rmdir(path.c_str()) == 0;
 }
 
 bool isFile(const std::string& path) {
-    auto lockable = getLock(path);
-    auto lock = lockable->asScopedLock();
-    lock.lock();
+    FileMutexGuard guard(path);
     return access(path.c_str(), F_OK) == 0;
 }
 
 bool isDirectory(const std::string& path) {
-    auto lockable = getLock(path);
-    auto lock = lockable->asScopedLock();
-    lock.lock();
+    FileMutexGuard guard(path);
     struct stat stat_result;
     return stat(path.c_str(), &stat_result) == 0 && S_ISDIR(stat_result.st_mode);
 }
 
 bool readLines(const std::string& filePath, bool stripNewLine, std::function<void(const char* line)> callback) {
-    auto lockable = getLock(filePath);
-    auto lock = lockable->asScopedLock();
-    lock.lock();
+    FileMutexGuard guard(filePath);
 
     auto* file = fopen(filePath.c_str(), "r");
     if (file == nullptr) {

Tactility/Source/file/PropertiesFile.cpp

@@ -2,7 +2,6 @@
 
 #include <Tactility/StringUtils.h>
 #include <Tactility/file/File.h>
-#include <Tactility/file/FileLock.h>
 #include <tactility/log.h>
 
 namespace tt::file {
@@ -55,22 +54,20 @@ bool loadPropertiesFile(const std::string& filePath, std::map<std::string, std::
 }
 
 bool savePropertiesFile(const std::string& filePath, const std::map<std::string, std::string>& properties) {
-    bool result = false;
-    getLock(filePath)->withLock([&result, filePath, &properties] {
-        LOG_I(TAG, "Saving properties file %s", filePath.c_str());
+    FileMutexGuard guard(filePath);
 
-        FILE* file = fopen(filePath.c_str(), "w");
-        if (file == nullptr) {
-            LOG_E(TAG, "Failed to open %s", filePath.c_str());
-            return;
-        }
+    LOG_I(TAG, "Saving properties file %s", filePath.c_str());
 
-        for (const auto& [key, value]: properties) { fprintf(file, "%s=%s\n", key.c_str(), value.c_str()); }
+    FILE* file = fopen(filePath.c_str(), "w");
+    if (file == nullptr) {
+        LOG_E(TAG, "Failed to open %s", filePath.c_str());
+        return false;
+    }
 
-        fclose(file);
-        result = true;
-    });
-    return result;
+    for (const auto& [key, value]: properties) { fprintf(file, "%s=%s\n", key.c_str(), value.c_str()); }
+
+    fclose(file);
+    return true;
 }
 
 }

Tactility/Source/lvgl/Keyboard.cpp

@@ -1,73 +0,0 @@
-#include "Tactility/lvgl/Keyboard.h"
-#include "Tactility/service/gui/GuiService.h"
-
-#include <tactility/device.h>
-#include <tactility/drivers/keyboard.h>
-
-namespace tt::lvgl {
-
-static lv_indev_t* keyboard_device = nullptr;
-static lv_group_t* pending_keyboard_group = nullptr;
-
-void software_keyboard_show(lv_obj_t* textarea) {
-    auto gui_service = service::gui::findService();
-    if (gui_service != nullptr) {
-        gui_service->softwareKeyboardShow(textarea);
-    }
-}
-
-void software_keyboard_hide() {
-    auto gui_service = service::gui::findService();
-    if (gui_service != nullptr) {
-        gui_service->softwareKeyboardHide();
-    }
-}
-
-bool software_keyboard_is_enabled() {
-    auto gui_service = service::gui::findService();
-    if (gui_service != nullptr) {
-        return gui_service->softwareKeyboardIsEnabled();
-    } else {
-        return false;
-    }
-}
-
-void software_keyboard_activate(lv_group_t* group) {
-    pending_keyboard_group = group;
-    if (keyboard_device != nullptr) {
-        lv_indev_set_group(keyboard_device, group);
-    }
-}
-
-void software_keyboard_deactivate() {
-    pending_keyboard_group = nullptr;
-    if (keyboard_device != nullptr) {
-        lv_indev_set_group(keyboard_device, nullptr);
-    }
-}
-
-bool hardware_keyboard_is_available() {
-    if (keyboard_device != nullptr) {
-        return true;
-    }
-    bool has_kernel_keyboard = false;
-    device_for_each_of_type(&KEYBOARD_TYPE, &has_kernel_keyboard, [](Device* device, void* context) {
-        if (device_is_ready(device)) {
-            *static_cast<bool*>(context) = true;
-            return false;
-        }
-        return true;
-    });
-    return has_kernel_keyboard;
-}
-
-void hardware_keyboard_set_indev(lv_indev_t* device) {
-    keyboard_device = device;
-    // If an app already activated a keyboard group while no hardware keyboard was
-    // connected, apply the pending group now that the device is available.
-    if (device != nullptr && pending_keyboard_group != nullptr) {
-        lv_indev_set_group(device, pending_keyboard_group);
-    }
-}
-
-}

Tactility/Source/lvgl/LabelUtils.cpp

@@ -1,14 +1,14 @@
 #include <Tactility/lvgl/LabelUtils.h>
 #include <Tactility/file/File.h>
-#include <Tactility/file/FileLock.h>
 
 namespace tt::lvgl {
 
 bool label_set_text_file(lv_obj_t* label, const char* filepath) {
     std::unique_ptr<uint8_t[]> text;
-    file::getLock(filepath)->withLock([&text, filepath] {
+    {
+        file::FileMutexGuard guard(filepath);
         text = file::readString(filepath);
-    });
+    }
 
     if (text != nullptr) {
         lv_label_set_text(label, reinterpret_cast<const char*>(text.get()));

Tactility/Source/lvgl/UsbHidInput.cpp

@@ -3,7 +3,6 @@
 #ifdef ESP_PLATFORM
 
 #include <Tactility/Assets.h>
-#include <Tactility/lvgl/Keyboard.h>
 
 #include <tactility/device.h>
 #include <tactility/drivers/usb_host_hid.h>
@@ -15,6 +14,7 @@
 #include <freertos/semphr.h>
 
 #include <lvgl/lvgl.h>
+#include <lvgl/devices/keyboard.h>
 
 #include <atomic>
 
@@ -171,6 +171,7 @@ static void usbHidInputTask(void* arg) {
     lv_indev_set_read_cb(ctx->kb_indev, keyboard_read_cb);
     lv_indev_set_user_data(ctx->kb_indev, ctx);
     lv_indev_set_group(ctx->kb_indev, lv_group_get_default());
+    lvgl_hardware_keyboard_add_custom(ctx->kb_indev);
 
     lvgl_unlock();
 
@@ -179,8 +180,11 @@ static void usbHidInputTask(void* arg) {
         UsbHidEvent hid_evt;
         if (xQueueReceive(ctx->hid_queue, &hid_evt, pdMS_TO_TICKS(100)) != pdTRUE) {
             if (!ctx->subscribed) {
-                struct Device* hid_dev = device_find_first_active_by_type(&USB_HOST_HID_TYPE);
-                if (hid_dev) ctx->subscribed = usb_host_hid_subscribe(hid_dev, ctx->hid_queue);
+                Device* hid_dev;
+                if (device_get_first_active_by_type(&USB_HOST_HID_TYPE, &hid_dev) == ERROR_NONE) {
+                    ctx->subscribed = usb_host_hid_subscribe(hid_dev, ctx->hid_queue);
+                    device_put(hid_dev);
+                }
             }
             continue;
         }
@@ -227,13 +231,15 @@ static void usbHidInputTask(void* arg) {
         }
         case USB_HID_EVENT_KEYBOARD_CONNECTED:
             if (ctx->kb_indev && lvgl_try_lock(pdMS_TO_TICKS(200))) {
-                hardware_keyboard_set_indev(ctx->kb_indev);
+                lvgl_keyboard_enable(ctx->kb_indev);
                 lvgl_unlock();
             }
             break;
         case USB_HID_EVENT_KEYBOARD_DISCONNECTED:
             if (lvgl_try_lock(pdMS_TO_TICKS(200))) {
-                hardware_keyboard_set_indev(nullptr);
+                if (ctx->kb_indev) {
+                    lvgl_keyboard_disable(ctx->kb_indev);
+                }
                 lvgl_unlock();
             }
             break;
@@ -260,7 +266,7 @@ static void usbHidInputTask(void* arg) {
     if (ctx->mouse_indev)  { lv_indev_delete(ctx->mouse_indev);  ctx->mouse_indev  = nullptr; }
     if (ctx->mouse_cursor) { lv_obj_delete(ctx->mouse_cursor);   ctx->mouse_cursor = nullptr; }
     if (ctx->kb_indev) {
-        hardware_keyboard_set_indev(nullptr);
+        lvgl_hardware_keyboard_remove_custom(ctx->kb_indev);
         lv_indev_delete(ctx->kb_indev);
         ctx->kb_indev = nullptr;
     }
@@ -300,14 +306,23 @@ void startUsbHidInput() {
         return;
     }
 
-    struct Device* hid_dev = device_find_first_active_by_type(&USB_HOST_HID_TYPE);
-    if (hid_dev) ctx->subscribed = usb_host_hid_subscribe(hid_dev, ctx->hid_queue);
+    Device* hid_dev = nullptr;
+    if (device_get_first_active_by_type(&USB_HOST_HID_TYPE, &hid_dev) == ERROR_NONE) {
+        ctx->subscribed = usb_host_hid_subscribe(hid_dev, ctx->hid_queue);
+        device_put(hid_dev);
+    }
 
     ctx->running = true;
     if (xTaskCreate(usbHidInputTask, "usb_hid_inp", TASK_STACK, ctx, TASK_PRIORITY, &ctx->task) != pdPASS) {
         LOG_E(TAG, "failed to create task");
         ctx->running = false;
-        if (hid_dev) usb_host_hid_unsubscribe(hid_dev, ctx->hid_queue);
+        if (ctx->subscribed) {
+            Device* cleanup_dev = nullptr;
+            if (device_get_first_active_by_type(&USB_HOST_HID_TYPE, &cleanup_dev) == ERROR_NONE) {
+                usb_host_hid_unsubscribe(cleanup_dev, ctx->hid_queue);
+                device_put(cleanup_dev);
+            }
+        }
         vQueueDelete(ctx->hid_queue);
         vQueueDelete(ctx->key_queue);
         vSemaphoreDelete(ctx->task_done);
@@ -335,7 +350,7 @@ void stopUsbHidInput() {
             if (ctx->mouse_indev)  { lv_indev_delete(ctx->mouse_indev);  ctx->mouse_indev  = nullptr; }
             if (ctx->mouse_cursor) { lv_obj_delete(ctx->mouse_cursor);   ctx->mouse_cursor = nullptr; }
             if (ctx->kb_indev) {
-                hardware_keyboard_set_indev(nullptr);
+                lvgl_hardware_keyboard_remove_custom(ctx->kb_indev);
                 lv_indev_delete(ctx->kb_indev);
                 ctx->kb_indev = nullptr;
             }
@@ -345,8 +360,11 @@ void stopUsbHidInput() {
     ctx->task = nullptr;
 
     if (ctx->subscribed) {
-        struct Device* hid_dev = device_find_first_active_by_type(&USB_HOST_HID_TYPE);
-        if (hid_dev) usb_host_hid_unsubscribe(hid_dev, ctx->hid_queue);
+        Device* hid_dev;
+        if (device_get_first_active_by_type(&USB_HOST_HID_TYPE, &hid_dev) == ERROR_NONE) {
+            usb_host_hid_unsubscribe(hid_dev, ctx->hid_queue);
+            device_put(hid_dev);
+        }
     }
     vQueueDelete(ctx->hid_queue);
     vQueueDelete(ctx->key_queue);

Tactility/Source/lvgl/wrappers/textarea.cpp

@@ -1,10 +1,7 @@
 #ifdef ESP_PLATFORM
 
-#include <lvgl.h>
-
 #include <lvgl/lvgl.h>
-
-#include <Tactility/service/gui/GuiService.h>
+#include <lvgl/devices/keyboard.h>
 
 extern "C" {
 
@@ -17,9 +14,9 @@ lv_obj_t* __wrap_lv_textarea_create(lv_obj_t* parent) {
         lv_obj_set_style_pad_all(textarea, 2, LV_STATE_DEFAULT);
     }
 
-    auto gui_service = tt::service::gui::findService();
-    if (gui_service != nullptr) {
-        gui_service->keyboardAddTextArea(textarea);
+    auto* software_keyboard = lvgl_software_keyboard_get_last();
+    if (software_keyboard != nullptr) {
+        lvgl_keyboard_add_textarea(software_keyboard, textarea);
     }
 
     if (lv_display_get_color_format(lv_obj_get_display(parent)) == LV_COLOR_FORMAT_L8) {

Tactility/Source/network/Http.cpp

@@ -70,9 +70,7 @@ void download(
 
         auto bytes_left = client->getContentLength();
 
-        auto lockable = file::getLock(downloadFilePath);
-        auto lock = lockable->asScopedLock();
-        lock.lock();
+        file::FileMutexGuard guard(downloadFilePath);
         LOG_I(TAG, "opening %s", downloadFilePath.c_str());
         auto* file = fopen(downloadFilePath.c_str(), "wb");
         if (file == nullptr) {

Tactility/Source/network/HttpdReq.cpp

@@ -186,9 +186,7 @@ size_t receiveFile(httpd_req_t* request, size_t length, const std::string& fileP
     char buffer[BUFFER_SIZE];
     size_t bytes_received = 0;
 
-    auto lockable = file::getLock(filePath);
-    auto lock = lockable->asScopedLock();
-    lock.lock();
+    file::FileMutexGuard guard(filePath);
 
     auto* file = fopen(filePath.c_str(), "wb");
     if (file == nullptr) {

Tactility/Source/service/gui/GuiService.cpp

@@ -1,4 +1,7 @@
 #include <Tactility/service/gui/GuiService.h>
+
+#include "lvgl/devices/keyboard.h"
+
 #include <Tactility/LogMessages.h>
 #include <Tactility/Tactility.h>
 #include <Tactility/app/AppInstance.h>
@@ -113,7 +116,6 @@ int32_t GuiService::guiMain() {
         return 0;
     }
 
-    service->keyboardGroup = lv_group_create();
     lv_obj_set_style_border_width(screen_root, 0, LV_STATE_DEFAULT);
     lv_obj_set_style_pad_all(screen_root, 0, LV_STATE_DEFAULT);
 
@@ -157,11 +159,12 @@ lv_obj_t* GuiService::createAppViews(lv_obj_t* parent) {
     lv_obj_set_style_border_width(child_container, 0, LV_STATE_DEFAULT);
     lv_obj_set_flex_grow(child_container, 1);
 
-    if (softwareKeyboardIsEnabled()) {
-        keyboard = lv_keyboard_create(parent);
-        lv_obj_add_flag(keyboard, LV_OBJ_FLAG_HIDDEN);
+    if (lvgl_software_keyboard_is_enabled()) {
+        lvgl_software_keyboard_construct(&software_keyboard, parent);
     } else {
-        keyboard = nullptr;
+        software_keyboard = {
+            nullptr
+        };
     }
 
     return child_container;
@@ -281,9 +284,8 @@ void GuiService::onStop(ServiceContext& service) {
     thread->join();
 
     lvgl_lock();
-    if (keyboardGroup != nullptr) {
-        lv_group_delete(keyboardGroup);
-        keyboardGroup = nullptr;
+    if (software_keyboard.object != nullptr) {
+        lvgl_software_keyboard_destruct(&software_keyboard);
     }
 
     auto* default_group = lv_group_get_default();

Tactility/Source/service/gui/Keyboard.cpp

@@ -1,76 +0,0 @@
-#include <Tactility/lvgl/Keyboard.h>
-#include <Tactility/service/gui/GuiService.h>
-#include <Tactility/TactilityConfig.h>
-#include <Tactility/service/espnow/EspNowService.h>
-
-#include <tactility/check.h>
-
-#include <lvgl/lvgl.h>
-
-namespace tt::service::gui {
-
-static void show_keyboard(lv_event_t* event) {
-    auto service = findService();
-    if (service != nullptr) {
-        lv_obj_t* target = lv_event_get_current_target_obj(event);
-        service->softwareKeyboardShow(target);
-        lv_obj_scroll_to_view(target, LV_ANIM_ON);
-    }
-}
-
-static void hide_keyboard(lv_event_t* event) {
-    auto service = findService();
-    if (service != nullptr) {
-        service->softwareKeyboardHide();
-    }
-}
-
-bool GuiService::softwareKeyboardIsEnabled() {
-    return !lvgl::hardware_keyboard_is_available() || TT_CONFIG_FORCE_ONSCREEN_KEYBOARD;
-}
-
-void GuiService::softwareKeyboardShow(lv_obj_t* textarea) {
-    lock();
-
-    if (isStarted && keyboard != nullptr) {
-        lv_obj_clear_flag(keyboard, LV_OBJ_FLAG_HIDDEN);
-        lv_keyboard_set_textarea(keyboard, textarea);
-    }
-
-    unlock();
-}
-
-void GuiService::softwareKeyboardHide() {
-    lock();
-
-    if (isStarted && keyboard != nullptr) {
-        lv_obj_add_flag(keyboard, LV_OBJ_FLAG_HIDDEN);
-    }
-
-    unlock();
-}
-
-void GuiService::keyboardAddTextArea(lv_obj_t* textarea) {
-    lock();
-
-    if (isStarted) {
-        check(lvgl_try_lock(0), "lvgl should already be locked before calling this method");
-
-        if (softwareKeyboardIsEnabled()) {
-            lv_obj_add_event_cb(textarea, show_keyboard, LV_EVENT_FOCUSED, nullptr);
-            lv_obj_add_event_cb(textarea, hide_keyboard, LV_EVENT_DEFOCUSED, nullptr);
-            lv_obj_add_event_cb(textarea, hide_keyboard, LV_EVENT_READY, nullptr);
-
-            // lv_obj_t auto-remove themselves from the group when they are destroyed (last checked in LVGL 8.3)
-            lv_group_add_obj(keyboardGroup, textarea);
-
-            lvgl::software_keyboard_activate(keyboardGroup);
-        }
-
-        lvgl_unlock();
-    }
-
-    unlock();
-}
-
-} // namespace

Tactility/Source/service/keyboardidle/KeyboardIdle.cpp

@@ -9,10 +9,10 @@
 #include <Tactility/service/ServiceRegistration.h>
 #include <Tactility/settings/KeyboardSettings.h>
 
+#include <lvgl/lvgl.h>
 #include <tactility/device.h>
 #include <tactility/drivers/backlight.h>
 #include <tactility/drivers/keyboard.h>
-#include <lvgl/lvgl.h>
 
 namespace tt::service::keyboardidle {
 

Tactility/Source/service/rtctime/RtcTimeService.cpp

@@ -19,7 +19,7 @@ constexpr auto* TAG = "RtcTime";
 
 Device* RtcTimeService::findRtcDevice() {
     if (!rtcDevice) {
-        rtcDevice = device_find_first_active_by_type(&RTC_TYPE);
+        device_get_first_active_by_type(&RTC_TYPE, &rtcDevice);
     }
     return rtcDevice;
 }
@@ -130,6 +130,11 @@ void RtcTimeService::onStop(ServiceContext& serviceContext) {
         kernel::unsubscribeSystemEvent(timeEventSubscription);
         timeEventSubscription = 0;
     }
+
+    if (rtcDevice) {
+        device_put(rtcDevice);
+        rtcDevice = nullptr;
+    }
 }
 
 extern const ServiceManifest manifest = {

Tactility/Source/service/statusbar/Statusbar.cpp

@@ -166,8 +166,18 @@ class StatusbarService final : public Service {
 
     void updateBluetoothIcon() {
         auto radio_state = bluetooth::getRadioState();
-        Device* btdev = device_find_first_active_by_type(&BLUETOOTH_TYPE);
-        bool scanning = btdev ? bluetooth_is_scanning(btdev) : false;
+        bool scanning;
+
+        {
+            Device* btdev;
+            if (device_get_first_active_by_type(&BLUETOOTH_TYPE, &btdev) == ERROR_NONE) {
+                scanning = bluetooth_is_scanning(btdev);
+                device_put(btdev);
+            } else {
+                scanning = false;
+            }
+        }
+
         Device* serial_dev = bluetooth_serial_get_device();
         Device* midi_dev = bluetooth_midi_get_device();
         bool connected = (serial_dev && bluetooth_serial_is_connected(serial_dev)) ||
@@ -211,11 +221,27 @@ class StatusbarService final : public Service {
         }
     }
 
-    void updateUsbIcon() {
-        Device* hid_dev  = device_find_first_active_by_type(&USB_HOST_HID_TYPE);
-        Device* midi_dev = device_find_first_active_by_type(&USB_HOST_MIDI_TYPE);
+    static bool isHidOrMidiConnected() {
+        Device* hid_dev = nullptr;
+        device_get_first_active_by_type(&USB_HOST_HID_TYPE, &hid_dev);
+        Device* midi_dev = nullptr;
+        device_get_first_active_by_type(&USB_HOST_MIDI_TYPE, &midi_dev);
+
         bool connected = (hid_dev && usb_host_hid_is_connected(hid_dev)) ||
                          (midi_dev && usb_midi_is_connected(midi_dev));
+
+        if (hid_dev) {
+            device_put(hid_dev);
+        }
+        if (midi_dev) {
+            device_put(midi_dev);
+        }
+
+        return connected;
+    }
+
+    void updateUsbIcon() {
+        bool connected = isHidOrMidiConnected();
         if (!connected) {
             // MSC: scan filesystems for any mounted /usb* path
             file_system_for_each(&connected, [](struct FileSystem* fs, void* ctx) -> bool {

Tactility/Source/service/webserver/AssetVersion.cpp

@@ -30,13 +30,11 @@ static bool loadVersionFromFile(const char* path, AssetVersion& version) {
     // Read file content
     std::string content;
     {
-        auto lock = file::getLock(path);
-        lock->lock(portMAX_DELAY);
+        file::FileMutexGuard guard(path);
 
         FILE* fp = fopen(path, "r");
         if (!fp) {
             LOG_E(TAG, "Failed to open version file: %s", path);
-            lock->unlock();
             return false;
         }
 
@@ -44,7 +42,6 @@ static bool loadVersionFromFile(const char* path, AssetVersion& version) {
         size_t bytesRead = fread(buffer, 1, sizeof(buffer) - 1, fp);
         bool readError = ferror(fp) != 0;
         fclose(fp);
-        lock->unlock();
 
         if (readError) {
             LOG_E(TAG, "Error reading version file: %s", path);
@@ -117,9 +114,8 @@ static bool saveVersionToFile(const char* path, const AssetVersion& version) {
     // Write to file
     bool success = false;
     {
-        auto lock = file::getLock(path);
-        lock->lock(portMAX_DELAY);
-        
+        file::FileMutexGuard guard(path);
+
         FILE* fp = fopen(path, "w");
         if (fp) {
             size_t len = strlen(jsonString);
@@ -139,7 +135,6 @@ static bool saveVersionToFile(const char* path, const AssetVersion& version) {
             }
             fclose(fp);
         }
-        lock->unlock();
     }
     
     cJSON_free(jsonString);

Tactility/Source/service/webserver/WebServerService.cpp

@@ -1703,8 +1703,7 @@ esp_err_t WebServerService::handleAssets(httpd_req_t* request) {
             httpd_resp_set_type(request, "image/png");
             httpd_resp_set_hdr(request, "Cache-Control", "public, max-age=86400");
 
-            auto lock = file::getLock(faviconPath);
-            lock->lock(portMAX_DELAY);
+            file::FileMutexGuard guard(faviconPath);
 
             FILE* fp = fopen(faviconPath, "rb");
             if (fp) {
@@ -1713,17 +1712,14 @@ esp_err_t WebServerService::handleAssets(httpd_req_t* request) {
                 while ((bytesRead = fread(buffer, 1, sizeof(buffer), fp)) > 0) {
                     if (httpd_resp_send_chunk(request, buffer, bytesRead) != ESP_OK) {
                         fclose(fp);
-                        lock->unlock();
                         return ESP_FAIL;
                     }
                 }
                 fclose(fp);
-                lock->unlock();
                 httpd_resp_send_chunk(request, nullptr, 0);
                 LOG_I(TAG, "[200] %s (favicon)", uri);
                 return ESP_OK;
             }
-            lock->unlock();
         }
         // If favicon not found, return 404 silently (browsers handle this gracefully)
         httpd_resp_send_err(request, HTTPD_404_NOT_FOUND, "Not found");
@@ -1752,9 +1748,8 @@ esp_err_t WebServerService::handleAssets(httpd_req_t* request) {
         httpd_resp_set_type(request, getContentType(dataPath));
         
         // Read and send file using standard C FILE* operations
-        auto lock = file::getLock(dataPath);
-        lock->lock(portMAX_DELAY);
-        
+        file::FileMutexGuard guard(dataPath);
+
         FILE* fp = fopen(dataPath.c_str(), "rb");
         if (fp) {
             char buffer[512];
@@ -1762,18 +1757,15 @@ esp_err_t WebServerService::handleAssets(httpd_req_t* request) {
             while ((bytesRead = fread(buffer, 1, sizeof(buffer), fp)) > 0) {
                 if (httpd_resp_send_chunk(request, buffer, bytesRead) != ESP_OK) {
                     fclose(fp);
-                    lock->unlock();
                     return ESP_FAIL;
                 }
             }
             fclose(fp);
-            lock->unlock();
 
             httpd_resp_send_chunk(request, nullptr, 0);  // End of chunks
             LOG_I(TAG, "[200] %s (from Data)", uri);
             return ESP_OK;
         }
-        lock->unlock();
     }
 
     // Fallback to SD card
@@ -1781,9 +1773,8 @@ esp_err_t WebServerService::handleAssets(httpd_req_t* request) {
     if (file::isFile(sdPath.c_str())) {
         httpd_resp_set_type(request, getContentType(sdPath));
         
-        auto lock = file::getLock(sdPath);
-        lock->lock(portMAX_DELAY);
-        
+        file::FileMutexGuard guard(sdPath);
+
         FILE* fp = fopen(sdPath.c_str(), "rb");
         if (fp) {
             char buffer[512];
@@ -1791,18 +1782,15 @@ esp_err_t WebServerService::handleAssets(httpd_req_t* request) {
             while ((bytesRead = fread(buffer, 1, sizeof(buffer), fp)) > 0) {
                 if (httpd_resp_send_chunk(request, buffer, bytesRead) != ESP_OK) {
                     fclose(fp);
-                    lock->unlock();
                     return ESP_FAIL;
                 }
             }
             fclose(fp);
-            lock->unlock();
-            
+
             httpd_resp_send_chunk(request, nullptr, 0);  // End of chunks
             LOG_I(TAG, "[200] %s (from SD)", uri);
             return ESP_OK;
         }
-        lock->unlock();
     }
     
     // File not found

TactilityKernel/include/tactility/device.h

@@ -334,45 +334,11 @@ void device_for_each_of_type(const struct DeviceType* type, void* callback_conte
 bool device_exists_of_type(const struct DeviceType* type) ;
 
 /**
- * Find a device by its name.
- *
- * @param[in] name non-null device name to look up
- * @return the device pointer if found, or NULL if not found
- */
-struct Device* device_find_by_name(const char* name) __attribute__((deprecated("Use device_get_by_name() and device_put()")));
-
-/**
- * Find the first started device of the given type.
- *
- * @param[in] type non-null device type pointer
- * @return the first started device of the given type, or NULL if none found
- */
-struct Device* device_find_first_active_by_type(const struct DeviceType* type) __attribute__((deprecated("Use device_get_first_active_by_type() and device_put()")));
-
-/**
- * Find the first device of the given type.
- *
- * @param[in] type non-null device type pointer
- * @return the first device of the given type, or NULL if none found
- */
-struct Device* device_find_first_by_type(const struct DeviceType* type) __attribute__((deprecated("Use device_get_first_by_type() and device_put()")));
-
-/**
- * Find the first device whose driver matches the given compatible string.
- *
- * @param[in] compatible non-null compatible string to match
- * @return the first matching device, or NULL if none found
- */
-struct Device* device_find_first_by_compatible(const char* compatible) __attribute__((deprecated("Use device_get_first_by_compatible() and device_put()")));
-
-/**
- * Find a device by name and atomically take a reference on it (equivalent to a device_find_by_name()
+ * Find a device by name and atomically take a reference on it.
  * immediately followed by a successful device_get(), but race-free: the lookup and the reference
  * are taken under the same lock, so a device that gets torn down concurrently either isn't found
  * or is safely referenced - there is no gap where a caller could be handed a pointer that's about
- * to become invalid). Prefer this over device_find_by_name() + device_get() for any device that
- * might be dynamically constructed/destructed at runtime (e.g. a hot-pluggable child device),
- * rather than a static devicetree-defined one.
+ * to become invalid).
  *
  * @param[in] name non-null device name to look up
  * @param[out] out_device receives the found device on success; untouched on failure
@@ -383,9 +349,7 @@ struct Device* device_find_first_by_compatible(const char* compatible) __attribu
 error_t device_get_by_name(const char* name, struct Device** out_device);
 
 /**
- * Find the first device of the given type and atomically take a reference on it. See
- * device_get_by_name() for why this is preferred over device_find_first_by_type() + device_get()
- * for dynamically constructed/destructed devices.
+ * Find the first device of the given type and atomically take a reference on it.
  *
  * @param[in] type non-null device type pointer
  * @param[out] out_device receives the found device on success; untouched on failure
@@ -396,9 +360,7 @@ error_t device_get_by_name(const char* name, struct Device** out_device);
 error_t device_get_first_by_type(const struct DeviceType* type, struct Device** out_device);
 
 /**
- * Find the first started device of the given type and atomically take a reference on it. See
- * device_get_by_name() for why this is preferred over device_find_first_active_by_type() +
- * device_get() for dynamically constructed/destructed devices.
+ * Find the first started device of the given type and atomically take a reference on it.
  *
  * @param[in] type non-null device type pointer
  * @param[out] out_device receives the found device on success; untouched on failure
@@ -417,9 +379,7 @@ error_t device_get_first_active_by_type(const struct DeviceType* type, struct De
 bool device_has_active_by_type(const struct DeviceType* type);
 
 /**
- * Find the first device whose driver matches the given compatible string and atomically take a
- * reference on it. See device_get_by_name() for why this is preferred over
- * device_find_first_by_compatible() + device_get() for dynamically constructed/destructed devices.
+ * Find the first device whose driver matches the given compatible string and atomically take a reference on it.
  *
  * @param[in] compatible non-null compatible string to match
  * @param[out] out_device receives the found device on success; untouched on failure

TactilityKernel/source/device.cpp

@@ -43,11 +43,9 @@ struct DeviceInternal {
     } state;
     /** Attached child devices */
     std::vector<Device*> children {};
-    // Outstanding device_get() holders. Guarded by `mutex`. device_get() refuses new refs once
-    // state.stopping is set, and device_stop() refuses to set state.stopping while this is > 0 -
-    // together that guarantees ref_count > 0 implies state.started == true, so by the time
-    // device_remove()/device_destruct() run (both already require !started), this is always
-    // already 0.
+    // Outstanding device_get() holders. Guarded by `mutex`. Independent of state.started -
+    // device_get()/device_put() bracket construct/destruct, not start/stop, so a ref can be held
+    // across a device_stop(). device_destruct() refuses to run while this is > 0.
     int32_t ref_count = 0;
 };
 
@@ -94,6 +92,10 @@ error_t device_destruct(Device* device) {
 
     auto* internal = device->internal;
 
+    if (internal->ref_count > 0) {
+        unlock_internal(device->internal);
+        return ERROR_RESOURCE_BUSY;
+    }
     if (internal->state.started || internal->state.added) {
         unlock_internal(device->internal);
         return ERROR_INVALID_STATE;
@@ -102,13 +104,6 @@ error_t device_destruct(Device* device) {
         unlock_internal(device->internal);
         return ERROR_INVALID_STATE;
     }
-    // Callers are expected to sequence teardown correctly (device_stop() already refuses to
-    // clear `started` while ref_count > 0, so by the time !started holds above, ref_count is
-    // already 0) - this is a cheap defense-in-depth check, not a substitute for that discipline.
-    if (internal->ref_count > 0) {
-        unlock_internal(device->internal);
-        return ERROR_RESOURCE_BUSY;
-    }
     LOG_D(TAG, "destruct %s", device->name);
 
     device->internal = nullptr;
@@ -253,11 +248,6 @@ error_t device_stop(Device* device) {
         return ERROR_NONE;
     }
 
-    if (internal->ref_count > 0) {
-        unlock_internal(internal);
-        return ERROR_RESOURCE_BUSY;
-    }
-
     // Already stopping on another thread
     if (internal->state.stopping) {
         unlock_internal(internal);
@@ -266,10 +256,6 @@ error_t device_stop(Device* device) {
     internal->state.stopping = true;
     unlock_internal(internal);
 
-    // driver_unbind() runs the driver's stop_device callback, which may remove/destruct child
-    // devices (device_remove() takes ledger_lock) - `mutex` must stay released across this call,
-    // same reasoning as device_start(). state.stopping keeps device_get() from handing out a new
-    // ref while ref_count is meant to stay at 0 during the unbind.
     error_t unbind_error = driver_unbind(internal->driver, device);
 
     lock_internal(internal);
@@ -393,11 +379,10 @@ bool device_is_constructed(const Device* device) {
 
 error_t device_get(Device* device) {
     auto* internal = device->internal;
-    lock_internal(internal);
-    if (!internal->state.started || internal->state.stopping) {
-        unlock_internal(internal);
+    if (!internal) {
         return ERROR_INVALID_STATE;
     }
+    lock_internal(internal);
     internal->ref_count++;
     unlock_internal(internal);
     return ERROR_NONE;
@@ -466,54 +451,6 @@ bool device_exists_of_type(const DeviceType* type) {
     return found;
 }
 
-Device* device_find_by_name(const char* name) {
-    Device* found = nullptr;
-    ledger_lock();
-    for (auto* device : ledger.devices) {
-        if (device->name != nullptr && std::strcmp(device->name, name) == 0) {
-            found = device;
-            break;
-        }
-    }
-    ledger_unlock();
-    return found;
-}
-
-Device* device_find_first_active_by_type(const DeviceType* type) {
-    Device* found = nullptr;
-    device_for_each_of_type(type, &found, [](Device* dev, void* ctx) -> bool {
-        if (device_is_ready(dev)) {
-            *static_cast<Device**>(ctx) = dev;
-            return false;
-        }
-        return true;
-    });
-    return found;
-}
-
-Device* device_find_first_by_type(const DeviceType* type) {
-    Device* found = nullptr;
-    device_for_each_of_type(type, &found, [](Device* dev, void* ctx) -> bool {
-        *static_cast<Device**>(ctx) = dev;
-        return false;
-    });
-    return found;
-}
-
-Device* device_find_first_by_compatible(const char* compatible) {
-    struct Ctx { Device* found; const char* compatible; };
-    Ctx ctx = { nullptr, compatible };
-    device_for_each(&ctx, [](Device* dev, void* raw_ctx) -> bool {
-        auto* c = static_cast<Ctx*>(raw_ctx);
-        if (device_is_compatible(dev, c->compatible)) {
-            c->found = dev;
-            return false;
-        }
-        return true;
-    });
-    return ctx.found;
-}
-
 error_t device_get_by_name(const char* name, Device** out_device) {
     ledger_lock();
     Device* found = nullptr;

TactilityKernel/source/drivers/keyboard.cpp

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
+#include <tactility/device.h>
 #include <tactility/drivers/keyboard.h>
 #include <tactility/error.h>
-#include <tactility/device.h>
 
 #define KEYBOARD_DRIVER_API(driver) ((struct KeyboardApi*)driver->api)
 

TactilityKernel/source/symbols.c

@@ -9,9 +9,9 @@
 #include <tactility/drivers/audio_stream.h>
 #include <tactility/drivers/backlight.h>
 #include <tactility/drivers/bluetooth.h>
-#include <tactility/drivers/bluetooth_serial.h>
-#include <tactility/drivers/bluetooth_midi.h>
 #include <tactility/drivers/bluetooth_hid_device.h>
+#include <tactility/drivers/bluetooth_midi.h>
+#include <tactility/drivers/bluetooth_serial.h>
 #include <tactility/drivers/camera.h>
 #include <tactility/drivers/display.h>
 #include <tactility/drivers/gpio_controller.h>
@@ -35,14 +35,14 @@
 #include <tactility/drivers/usb_host_msc.h>
 #include <tactility/drivers/wifi.h>
 #include <tactility/error.h>
-#include <tactility/filesystem/file_system.h>
 #include <tactility/filesystem/file_mutex.h>
+#include <tactility/filesystem/file_system.h>
 #include <tactility/memory.h>
 #include <tactility/module.h>
-#include <tactility/wifi_auto_scan.h>
 #include <tactility/service/service_instance.h>
 #include <tactility/service/service_manager.h>
 #include <tactility/service/service_paths.h>
+#include <tactility/wifi_auto_scan.h>
 
 #ifndef ESP_PLATFORM
 #include <tactility/log.h>
@@ -81,10 +81,6 @@ const struct ModuleSymbol KERNEL_SYMBOLS[] = {
     DEFINE_MODULE_SYMBOL(device_for_each_child),
     DEFINE_MODULE_SYMBOL(device_for_each_of_type),
     DEFINE_MODULE_SYMBOL(device_exists_of_type),
-    DEFINE_MODULE_SYMBOL(device_find_by_name),
-    DEFINE_MODULE_SYMBOL(device_find_first_active_by_type),
-    DEFINE_MODULE_SYMBOL(device_find_first_by_type),
-    DEFINE_MODULE_SYMBOL(device_find_first_by_compatible),
     DEFINE_MODULE_SYMBOL(device_get),
     DEFINE_MODULE_SYMBOL(device_put),
     DEFINE_MODULE_SYMBOL(device_get_by_name),

Tests/TactilityKernel/Source/DeviceGetPutTest.cpp

@@ -32,7 +32,7 @@ Driver test_driver = {
 
 } // namespace
 
-TEST_CASE("device_get should fail with ERROR_INVALID_STATE when the device is not started") {
+TEST_CASE("device_get should succeed even when the device is not started") {
     Device device = { .name = "get_not_started", .config = nullptr, .parent = nullptr };
 
     CHECK_EQ(driver_construct_add(&test_driver), ERROR_NONE);
@@ -40,13 +40,30 @@ TEST_CASE("device_get should fail with ERROR_INVALID_STATE when the device is no
     device_set_driver(&device, &test_driver);
     CHECK_EQ(device_add(&device), ERROR_NONE);
 
-    CHECK_EQ(device_get(&device), ERROR_INVALID_STATE);
+    // Ref-counting brackets construct/destruct, not start/stop.
+    CHECK_EQ(device_get(&device), ERROR_NONE);
+    device_put(&device);
 
     CHECK_EQ(device_remove(&device), ERROR_NONE);
     CHECK_EQ(device_destruct(&device), ERROR_NONE);
     CHECK_EQ(driver_remove_destruct(&test_driver), ERROR_NONE);
 }
 
+TEST_CASE("device_get should fail with ERROR_INVALID_STATE once the device has been destructed") {
+    Device device = { .name = "get_after_destruct", .config = nullptr, .parent = nullptr };
+
+    CHECK_EQ(driver_construct_add(&test_driver), ERROR_NONE);
+    CHECK_EQ(device_construct(&device), ERROR_NONE);
+    device_set_driver(&device, &test_driver);
+    CHECK_EQ(device_add(&device), ERROR_NONE);
+    CHECK_EQ(device_remove(&device), ERROR_NONE);
+    CHECK_EQ(device_destruct(&device), ERROR_NONE);
+
+    CHECK_EQ(device_get(&device), ERROR_INVALID_STATE);
+
+    CHECK_EQ(driver_remove_destruct(&test_driver), ERROR_NONE);
+}
+
 TEST_CASE("device_get should succeed once started, and device_put should release it") {
     Device device = { .name = "get_started", .config = nullptr, .parent = nullptr };
 
@@ -65,7 +82,7 @@ TEST_CASE("device_get should succeed once started, and device_put should release
     CHECK_EQ(driver_remove_destruct(&test_driver), ERROR_NONE);
 }
 
-TEST_CASE("device_stop should fail with ERROR_RESOURCE_BUSY while a reference is held, from a concurrent thread") {
+TEST_CASE("device_stop should succeed while a reference is held, but device_destruct should fail with ERROR_RESOURCE_BUSY until it is released") {
     static Device device = { .name = "get_put_concurrent", .config = nullptr, .parent = nullptr };
     static std::atomic<bool> acquired { false };
     static std::atomic<bool> release { false };
@@ -103,21 +120,22 @@ TEST_CASE("device_stop should fail with ERROR_RESOURCE_BUSY while a reference is
         delay_millis(1);
     }
 
-    // Held by the worker thread right now - device_stop() must fail fast, not block.
-    CHECK_EQ(device_stop(&device), ERROR_RESOURCE_BUSY);
+    // Held by the worker thread right now - device_stop() is independent of ref-counting, so it
+    // still succeeds; only device_destruct() gates on outstanding refs.
+    CHECK_EQ(device_stop(&device), ERROR_NONE);
+    CHECK_EQ(device_remove(&device), ERROR_NONE);
+    CHECK_EQ(device_destruct(&device), ERROR_RESOURCE_BUSY);
 
     release = true;
     CHECK_EQ(thread_join(thread, 200, 1), ERROR_NONE);
     thread_free(thread);
 
-    // Reference released - device_stop() now succeeds.
-    CHECK_EQ(device_stop(&device), ERROR_NONE);
-    CHECK_EQ(device_remove(&device), ERROR_NONE);
+    // Reference released - device_destruct() now succeeds.
     CHECK_EQ(device_destruct(&device), ERROR_NONE);
     CHECK_EQ(driver_remove_destruct(&test_driver), ERROR_NONE);
 }
 
-TEST_CASE("device_get_by_name should find and reference a started device, or fail if not found/not started") {
+TEST_CASE("device_get_by_name should find and reference an added device regardless of started state, or fail if not found") {
     Device device = { .name = "get_by_name_device", .config = nullptr, .parent = nullptr };
 
     CHECK_EQ(driver_construct_add(&test_driver), ERROR_NONE);
@@ -127,7 +145,11 @@ TEST_CASE("device_get_by_name should find and reference a started device, or fai
 
     Device* out = nullptr;
     CHECK_EQ(device_get_by_name("does_not_exist", &out), ERROR_NOT_FOUND);
-    CHECK_EQ(device_get_by_name("get_by_name_device", &out), ERROR_INVALID_STATE);
+
+    // Not started yet - lookup still succeeds, since it only requires the device to be added.
+    CHECK_EQ(device_get_by_name("get_by_name_device", &out), ERROR_NONE);
+    CHECK_EQ(out, &device);
+    device_put(out);
 
     CHECK_EQ(device_start(&device), ERROR_NONE);
     CHECK_EQ(device_get_by_name("get_by_name_device", &out), ERROR_NONE);