refactor: extract HID functionality into transport_hid and ble_hid modules

Implemented clean architectural separation following the established transport pattern:

## New modules created:
- **transport_hid.c/h**: Pure transport bridge for BLE HID ↔ USB HID data flow
- **ble_hid.c/h**: BLE HID client implementation with protocol handling and callbacks

## Architecture improvements:
- **Separation of concerns**: Transport logic separated from protocol implementation
- **Consistent patterns**: Matches transport_uart/ble_nus architecture
- **Callback-based design**: Clean event flow between layers
- **Modular initialization**: Each module handles its own setup

## Code changes:
- Created transport_hid with bridge state management and USB forwarding
- Created ble_hid with ESP HID event handling and device lifecycle
- Refactored main.c to use callback-based architecture
- Removed duplicate helper functions (log_report, log_addr, appearance_to_string)
- Updated hidh_callback to forward events to ble_hid module
- Added proper module initialization in app_main

## Benefits:
- Cleaner code organization and maintainability
- Easier to extend with future HID features
- Consistent with existing transport_uart pattern
- Better error handling and state management
- Alphabetical file ordering (transport_hid, transport_uart)

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: RobertDaleSmith

esp32/CMakeLists.txt

@@ -1,4 +1,4 @@
 cmake_minimum_required(VERSION 3.16)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
-project(mouthpad_esp32_ble_hid_central)
+project(mouthpad_usb)

esp32/main/CMakeLists.txt

@@ -1,3 +1,3 @@
-idf_component_register(SRCS "transport_uart.c" "ble_central.c" "dev_dfu.c" "ble_dis.c" "ble_nus.c" "button.c" "ble_bas.c" "leds.c" "main.c" "usb_hid.c" "usb_cdc.c"
+idf_component_register(SRCS "usb_dfu.c" "ble_hid.c" "transport_hid.c" "transport_uart.c" "ble_central.c" "ble_dis.c" "ble_nus.c" "button.c" "ble_bas.c" "leds.c" "main.c" "usb_hid.c" "usb_cdc.c"
                        INCLUDE_DIRS "."
                        REQUIRES bt esp_hid nvs_flash esp_driver_uart)

esp32/main/ble_dis.c

@@ -9,7 +9,7 @@
 #include "freertos/queue.h"
 #include "string.h"
 
-static const char *TAG = "BLE_DEVICE_INFO";
+static const char *TAG = "BLE_DIS";
 
 // Device info client state
 static esp_gatt_if_t dis_gattc_if = ESP_GATT_IF_NONE;

esp32/main/ble_hid.c

@@ -0,0 +1,159 @@
+#include "ble_hid.h"
+#include "esp_log.h"
+#include "esp_hidh.h"
+#include "esp_hid_common.h"
+#include "string.h"
+
+static const char *TAG = "BLE_HID";
+
+// Client state and callbacks
+static ble_hid_client_config_t s_config = {0};
+static esp_hidh_dev_t *s_active_dev = NULL;
+static bool s_connected = false;
+
+// Helper function to log HID reports
+static void log_report(const uint8_t *data, size_t length)
+{
+    if (!data || !length) {
+        ESP_LOGI(TAG, "Empty report");
+        return;
+    }
+
+    char buffer[3 * 32 + 1];
+    size_t to_print = length < 32 ? length : 32;
+    for (size_t i = 0; i < to_print; ++i) {
+        snprintf(buffer + i * 3, sizeof(buffer) - i * 3, "%02X ", data[i]);
+    }
+    buffer[to_print * 3] = '\0';
+    ESP_LOGI(TAG, "Report (%d bytes): %s%s", (int)length, buffer,
+             length > to_print ? "..." : "");
+}
+
+// Helper function to log device address
+static void log_addr(const uint8_t *addr)
+{
+    if (!addr) {
+        ESP_LOGI(TAG, "(unknown addr)");
+        return;
+    }
+    ESP_LOGI(TAG, "Address: %02X:%02X:%02X:%02X:%02X:%02X",
+             addr[0], addr[1], addr[2], addr[3], addr[4], addr[5]);
+}
+
+esp_err_t ble_hid_client_init(const ble_hid_client_config_t *config)
+{
+    if (!config) {
+        ESP_LOGE(TAG, "Invalid config");
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    ESP_LOGI(TAG, "Initializing BLE HID client");
+
+    // Store configuration
+    memcpy(&s_config, config, sizeof(ble_hid_client_config_t));
+
+    // Initialize state
+    s_active_dev = NULL;
+    s_connected = false;
+
+    ESP_LOGI(TAG, "BLE HID client initialized successfully");
+    return ESP_OK;
+}
+
+void ble_hid_client_handle_event(void *handler_args, esp_event_base_t base, int32_t id, void *event_data)
+{
+    (void)handler_args;
+    (void)base;
+    esp_hidh_event_t event = (esp_hidh_event_t)id;
+    esp_hidh_event_data_t *param = (esp_hidh_event_data_t *)event_data;
+
+    switch (event) {
+    case ESP_HIDH_OPEN_EVENT:
+        if (param->open.dev) {
+            const uint8_t *bda = esp_hidh_dev_bda_get(param->open.dev);
+            ESP_LOGI(TAG, "=== HID DEVICE CONNECTED ===");
+            ESP_LOGI(TAG, "Name: %s", esp_hidh_dev_name_get(param->open.dev));
+            if (bda) {
+                log_addr(bda);
+            }
+
+            // Update state
+            s_active_dev = param->open.dev;
+            s_connected = true;
+
+            // Notify transport layer via callback
+            if (s_config.connected_cb && bda) {
+                s_config.connected_cb(param->open.dev, bda);
+            }
+        }
+        break;
+
+    case ESP_HIDH_BATTERY_EVENT:
+        ESP_LOGI(TAG, "Battery event");
+        if (s_config.battery_cb) {
+            s_config.battery_cb(param->battery.level, param->battery.status);
+        }
+        if (param->battery.status != ESP_OK) {
+            ESP_LOGW(TAG, "Battery event error: %d", param->battery.status);
+        }
+        break;
+
+    case ESP_HIDH_INPUT_EVENT:
+        if (param->input.dev) {
+            // Forward to transport layer via callback (fast path)
+            if (s_config.input_cb) {
+                s_config.input_cb(param->input.report_id, param->input.data, param->input.length);
+            }
+            // Optional verbose logging can be enabled here if needed
+        }
+        break;
+
+    case ESP_HIDH_FEATURE_EVENT:
+        if (param->feature.dev) {
+            ESP_LOGI(TAG, "Feature report (usage=%s, id=%u)",
+                     esp_hid_usage_str(param->feature.usage), param->feature.report_id);
+            log_report(param->feature.data, param->feature.length);
+
+            // Notify callback if set
+            if (s_config.feature_cb) {
+                s_config.feature_cb(param->feature.dev, param->feature.report_id,
+                                  param->feature.data, param->feature.length, param->feature.usage);
+            }
+        }
+        break;
+
+    case ESP_HIDH_CLOSE_EVENT:
+        ESP_LOGI(TAG, "HID device disconnected");
+
+        // Update state
+        if (param->close.dev == s_active_dev) {
+            s_active_dev = NULL;
+            s_connected = false;
+        }
+
+        // Notify transport layer via callback
+        if (s_config.disconnected_cb) {
+            s_config.disconnected_cb(param->close.dev);
+        }
+
+        // Clean up device handle
+        if (param->close.dev) {
+            esp_hidh_dev_free(param->close.dev);
+        }
+        break;
+
+    default:
+        ESP_LOGD(TAG, "Unhandled HID event %d", event);
+        break;
+    }
+}
+
+esp_hidh_dev_t *ble_hid_client_get_active_device(void)
+{
+    return s_active_dev;
+}
+
+bool ble_hid_client_is_connected(void)
+{
+    return s_connected && s_active_dev != NULL;
+}

esp32/main/ble_hid.h

@@ -0,0 +1,55 @@
+#pragma once
+
+#include "esp_err.h"
+#include "esp_hidh.h"
+#include "esp_event.h"
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// BLE HID client configuration structure
+typedef struct {
+    void (*connected_cb)(esp_hidh_dev_t *dev, const uint8_t *bda);
+    void (*disconnected_cb)(esp_hidh_dev_t *dev);
+    void (*input_cb)(uint8_t report_id, const uint8_t *data, uint16_t length);
+    void (*feature_cb)(esp_hidh_dev_t *dev, uint8_t report_id, const uint8_t *data, uint16_t length, esp_hid_usage_t usage);
+    void (*battery_cb)(uint8_t level, esp_err_t status);
+} ble_hid_client_config_t;
+
+/**
+ * @brief Initialize the BLE HID client
+ *
+ * @param config Configuration structure with callbacks
+ * @return esp_err_t ESP_OK on success
+ */
+esp_err_t ble_hid_client_init(const ble_hid_client_config_t *config);
+
+/**
+ * @brief Handle ESP HID host events (called from main HID callback)
+ *
+ * @param handler_args Handler arguments (unused)
+ * @param base Event base
+ * @param id Event ID
+ * @param event_data Event data
+ */
+void ble_hid_client_handle_event(void *handler_args, esp_event_base_t base, int32_t id, void *event_data);
+
+/**
+ * @brief Get the currently active HID device
+ *
+ * @return esp_hidh_dev_t* Active device or NULL if none
+ */
+esp_hidh_dev_t *ble_hid_client_get_active_device(void);
+
+/**
+ * @brief Check if a HID device is currently connected
+ *
+ * @return true if connected, false otherwise
+ */
+bool ble_hid_client_is_connected(void);
+
+#ifdef __cplusplus
+}
+#endif

esp32/main/ble_nus.c

@@ -9,7 +9,7 @@
 #include "freertos/queue.h"
 #include "string.h"
 
-static const char *TAG = "BLE_NUS_CLIENT";
+static const char *TAG = "BLE_NUS";
 
 // NUS client state
 static esp_gatt_if_t nus_gattc_if = ESP_GATT_IF_NONE;