#include "usb_badge/usb_hid.h"
#include "usb_descriptors.h"
#include "cdc_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_mac.h"
#include "tusb.h"
#include "class/cdc/cdc.h"
#include "class/hid/hid_device.h"
#include <string.h>
#include <stdio.h>

Functions
static void	build_config_descriptor (void)
	Rebuilds the composite USB configuration descriptor from registered interfaces.
static void	init_serial_number ()
	Initializes the serial-number string once from efuse MAC.
uint8_t const *	tud_descriptor_device_cb (void)
	TinyUSB descriptor and HID report callbacks.
uint8_t const *	tud_descriptor_configuration_cb (uint8_t index)
	Returns the active configuration descriptor.
uint16_t const *	tud_descriptor_string_cb (uint8_t index, uint16_t langid)
	Returns UTF-16 string descriptors for fixed and dynamic strings.
uint8_t const *	tud_hid_descriptor_report_cb (uint8_t instance)
	Returns the HID report descriptor for a HID instance.
uint16_t	tud_hid_get_report_cb (uint8_t instance, uint8_t report_id, hid_report_type_t report_type, uint8_t *buffer, uint16_t reqlen)
	Handles HID GET_REPORT requests by delegating to interface callbacks.
void	tud_hid_set_report_cb (uint8_t instance, uint8_t report_id, hid_report_type_t report_type, uint8_t const *buffer, uint16_t bufsize)
	Handles HID SET_REPORT requests by delegating to interface callbacks.
void	tud_hid_report_complete_cb (uint8_t instance, uint8_t const *report, uint16_t len)
	Notifies interface callbacks that a HID report transfer completed.
bool	usb_hid_init (void)
	Public USB HID/composite configuration API implementation.
bool	usb_hid_apply_config (const UsbInterfaceDef defs, size_t count, bool needs_replug)
	Applies the runtime interface configuration and optionally triggers re-enumeration.
bool	usb_hid_ready (void)
	Returns whether TinyUSB stack is ready.
bool	usb_hid_instance_ready (uint8_t instance)
	Returns whether a specific HID instance endpoint is ready.
bool	usb_hid_send_report (uint8_t instance, uint8_t report_id, const uint8_t *data, uint16_t len)
	Sends one HID report on the selected interface instance.

Variables
static const char *	TAG = "USB_HID"
	USB composite descriptor/runtime builder for CDC plus optional HID/CCID interfaces.
static bool	s_hid_initialized = false
	Global descriptor and interface registration state.
static constexpr size_t	MAX_INTERFACES = 3
static UsbInterfaceDef	s_defs [MAX_INTERFACES] = {}
static size_t	s_def_count = 0
static int8_t	s_hid_map [MAX_INTERFACES] = {-1, -1, -1}
static size_t	s_hid_count = 0
static uint8_t	s_config_descriptor [256]
static uint16_t	s_config_descriptor_len = 0
static const char *	s_dynamic_strings [MAX_INTERFACES] = {}
	Dynamic module interface names generated during configuration apply.
static size_t	s_dynamic_string_count = 0
static tusb_desc_device_t	device_descriptor
	Descriptor storage used for runtime-generated TinyUSB configuration descriptors.
static char	s_serial_number [13] = "000000000000"
	USB serial number derived from ESP32 MAC address.
static const char *	s_fixed_strings []
	Fixed USB string descriptors; dynamic interface strings are appended at runtime.
static constexpr size_t	FIXED_STRING_COUNT = sizeof(s_fixed_strings) / sizeof(s_fixed_strings[0])

Function Documentation

◆ build_config_descriptor()

void build_config_descriptor ( void )

static

Rebuilds the composite USB configuration descriptor from registered interfaces.

Definition at line 70 of file usb_hid.cpp.

References device_descriptor, EP_CCID_SIZE, EP_CDC_IN, EP_CDC_NOTIF, EP_CDC_NOTIF_SIZE, EP_CDC_OUT, EP_CDC_SIZE, LOG_W, MAX_INTERFACES, s_config_descriptor, s_config_descriptor_len, s_def_count, s_defs, s_dynamic_string_count, s_dynamic_strings, s_hid_count, s_hid_map, STR_CDC, STR_DYNAMIC_BASE, TAG, TUD_CCID_DESCRIPTOR, TUD_CCID_TOTAL_LEN, USB_PID_BADGE, USB_PID_GEMALTO, USB_VID_ESPRESSIF, and USB_VID_GEMALTO.

Referenced by usb_hid_apply_config(), and usb_hid_init().

◆ init_serial_number()

void init_serial_number ( )

static

Initializes the serial-number string once from efuse MAC.

Definition at line 187 of file usb_hid.cpp.

References s_serial_number.

Referenced by usb_hid_init().

◆ tud_descriptor_configuration_cb()

uint8_t const * tud_descriptor_configuration_cb ( uint8_t index )

Returns the active configuration descriptor.

Parameters

index Configuration index (unused; single configuration only).

Returns: Pointer to descriptor buffer, or nullptr if not built.

Definition at line 231 of file usb_hid.cpp.

References s_config_descriptor, and s_config_descriptor_len.

◆ tud_descriptor_device_cb()

uint8_t const * tud_descriptor_device_cb ( void )

TinyUSB descriptor and HID report callbacks.

Returns the device descriptor used by TinyUSB.

Returns: Pointer to static device descriptor.

Definition at line 222 of file usb_hid.cpp.

References device_descriptor.

◆ tud_descriptor_string_cb()

uint16_t const * tud_descriptor_string_cb	(	uint8_t	index,
		uint16_t	langid )

Returns UTF-16 string descriptors for fixed and dynamic strings.

Parameters

index	String descriptor index.
langid	Requested language ID (unused).

Returns: Pointer to UTF-16 descriptor buffer, or nullptr if index is invalid.

Definition at line 242 of file usb_hid.cpp.

References FIXED_STRING_COUNT, s_dynamic_string_count, s_dynamic_strings, s_fixed_strings, and STR_DYNAMIC_BASE.

◆ tud_hid_descriptor_report_cb()

uint8_t const * tud_hid_descriptor_report_cb ( uint8_t instance )

Returns the HID report descriptor for a HID instance.

Parameters

instance HID instance index.

Returns: Pointer to report descriptor, or nullptr if instance is invalid.

Definition at line 280 of file usb_hid.cpp.

References s_defs, s_hid_count, and s_hid_map.

◆ tud_hid_get_report_cb()

uint16_t tud_hid_get_report_cb	(	uint8_t	instance,
		uint8_t	report_id,
		hid_report_type_t	report_type,
		uint8_t *	buffer,
		uint16_t	reqlen )

Handles HID GET_REPORT requests by delegating to interface callbacks.

Parameters

instance	HID instance index.
report_id	Requested report ID.
report_type	Requested report type.
buffer	Destination buffer.
reqlen	Requested report length.

Returns: Number of bytes written to buffer.

Definition at line 297 of file usb_hid.cpp.

References s_defs, s_hid_count, and s_hid_map.

◆ tud_hid_report_complete_cb()

void tud_hid_report_complete_cb	(	uint8_t	instance,
		uint8_t const *	report,
		uint16_t	len )

Notifies interface callbacks that a HID report transfer completed.

Parameters

instance	HID instance index.
report	Transmitted report payload.
len	Report length in bytes.

Definition at line 333 of file usb_hid.cpp.

References s_defs, s_hid_count, and s_hid_map.

◆ tud_hid_set_report_cb()

void tud_hid_set_report_cb	(	uint8_t	instance,
		uint8_t	report_id,
		hid_report_type_t	report_type,
		uint8_t const *	buffer,
		uint16_t	bufsize )

Handles HID SET_REPORT requests by delegating to interface callbacks.

Parameters

instance	HID instance index.
report_id	Report ID.
report_type	Report type.
buffer	Report payload.
bufsize	Payload length in bytes.

Definition at line 316 of file usb_hid.cpp.

References s_defs, s_hid_count, and s_hid_map.

◆ usb_hid_apply_config()

bool usb_hid_apply_config	(	const UsbInterfaceDef *	defs,
		size_t	count,
		bool *	needs_replug )

Applies the runtime interface configuration and optionally triggers re-enumeration.

Parameters

defs	Interface definition array.
count	Number of interface definitions.
needs_replug	Optional out-flag indicating host re-enumeration request.

Returns: true on successful configuration apply.

Definition at line 367 of file usb_hid.cpp.

References build_config_descriptor(), MAX_INTERFACES, s_def_count, and s_defs.

Referenced by cdc::core::UsbManager::applyConfiguration().

◆ usb_hid_init()

bool usb_hid_init ( void )

Public USB HID/composite configuration API implementation.

Initializes HID descriptor state and builds default descriptors.

Returns: true if initialization is complete.

Definition at line 352 of file usb_hid.cpp.

References build_config_descriptor(), init_serial_number(), and s_hid_initialized.

Referenced by usb_cdc_init().

◆ usb_hid_instance_ready()

bool usb_hid_instance_ready ( uint8_t instance )

Returns whether a specific HID instance endpoint is ready.

Parameters

instance HID instance index.

Returns: true if that instance is ready for reports.

Definition at line 402 of file usb_hid.cpp.

Referenced by cdc::mod_fido2::fido2_usb_ready().

◆ usb_hid_ready()

bool usb_hid_ready ( void )

Returns whether TinyUSB stack is ready.

Returns: true when USB device stack is ready.

Definition at line 393 of file usb_hid.cpp.

◆ usb_hid_send_report()

bool usb_hid_send_report	(	uint8_t	instance,
		uint8_t	report_id,
		const uint8_t *	data,
		uint16_t	len )

Sends one HID report on the selected interface instance.

Parameters

instance	HID instance index.
report_id	Report ID.
data	Report payload.
len	Payload length in bytes.

Returns: true if TinyUSB accepted the report for transmission.

Definition at line 414 of file usb_hid.cpp.

Referenced by cdc::mod_fido2::fido2_usb_write().

Variable Documentation

◆ device_descriptor

tusb_desc_device_t device_descriptor

static

Initial value:

                                            = {
    .bLength            = sizeof(tusb_desc_device_t),
    .bDescriptorType    = TUSB_DESC_DEVICE,
    .bcdUSB             = 0x0200 ,
    .bDeviceClass       = TUSB_CLASS_MISC,
    .bDeviceSubClass    = MISC_SUBCLASS_COMMON,
    .bDeviceProtocol    = MISC_PROTOCOL_IAD,
    .bMaxPacketSize0    = CFG_TUD_ENDPOINT0_SIZE,
    .idVendor           = 0x303A ,
    .idProduct          = 0xBADE ,
    .bcdDevice          = 0x0100,
    .iManufacturer      = STR_MANUFACTURER,
    .iProduct           = STR_PRODUCT,
    .iSerialNumber      = STR_SERIAL,
    .bNumConfigurations = 1
}

Descriptor storage used for runtime-generated TinyUSB configuration descriptors.

Definition at line 50 of file usb_hid.cpp.

Referenced by build_config_descriptor(), and tud_descriptor_device_cb().

◆ FIXED_STRING_COUNT

size_t FIXED_STRING_COUNT = sizeof(s_fixed_strings) / sizeof(s_fixed_strings[0])

staticconstexpr

Definition at line 210 of file usb_hid.cpp.

Referenced by tud_descriptor_string_cb().

◆ MAX_INTERFACES

size_t MAX_INTERFACES = 3

staticconstexpr

Definition at line 30 of file usb_hid.cpp.

Referenced by build_config_descriptor(), and usb_hid_apply_config().

◆ s_config_descriptor

uint8_t s_config_descriptor[256]

static

Definition at line 37 of file usb_hid.cpp.

Referenced by build_config_descriptor(), and tud_descriptor_configuration_cb().

◆ s_config_descriptor_len

uint16_t s_config_descriptor_len = 0

static

Definition at line 38 of file usb_hid.cpp.

Referenced by build_config_descriptor(), and tud_descriptor_configuration_cb().

◆ s_def_count

size_t s_def_count = 0

static

Definition at line 32 of file usb_hid.cpp.

Referenced by build_config_descriptor(), and usb_hid_apply_config().

◆ s_defs

UsbInterfaceDef s_defs[MAX_INTERFACES] = {}

static

Definition at line 31 of file usb_hid.cpp.

Referenced by build_config_descriptor(), tud_hid_descriptor_report_cb(), tud_hid_get_report_cb(), tud_hid_report_complete_cb(), tud_hid_set_report_cb(), and usb_hid_apply_config().

◆ s_dynamic_string_count

size_t s_dynamic_string_count = 0

static

Definition at line 44 of file usb_hid.cpp.

Referenced by build_config_descriptor(), and tud_descriptor_string_cb().

◆ s_dynamic_strings

const char* s_dynamic_strings[MAX_INTERFACES] = {}

static

Dynamic module interface names generated during configuration apply.

Definition at line 43 of file usb_hid.cpp.

Referenced by build_config_descriptor(), and tud_descriptor_string_cb().

◆ s_fixed_strings

const char* s_fixed_strings[]

static

Initial value:

                                  = {
    (const char[]){0x09, 0x04},  
    "CDC",                        
    "BadgeV1",                    
    s_serial_number,              
    "CDC Serial",                 
}

Fixed USB string descriptors; dynamic interface strings are appended at runtime.

Definition at line 203 of file usb_hid.cpp.

Referenced by tud_descriptor_string_cb().

◆ s_hid_count

size_t s_hid_count = 0

static

Definition at line 35 of file usb_hid.cpp.

Referenced by build_config_descriptor(), tud_hid_descriptor_report_cb(), tud_hid_get_report_cb(), tud_hid_report_complete_cb(), and tud_hid_set_report_cb().

◆ s_hid_initialized

bool s_hid_initialized = false

static

Global descriptor and interface registration state.

Definition at line 28 of file usb_hid.cpp.

Referenced by usb_hid_init().

◆ s_hid_map

int8_t s_hid_map[MAX_INTERFACES] = {-1, -1, -1}

static

Definition at line 34 of file usb_hid.cpp.

Referenced by build_config_descriptor(), tud_hid_descriptor_report_cb(), tud_hid_get_report_cb(), tud_hid_report_complete_cb(), and tud_hid_set_report_cb().

◆ s_serial_number

char s_serial_number[13] = "000000000000"

static

USB serial number derived from ESP32 MAC address.

Definition at line 182 of file usb_hid.cpp.

Referenced by init_serial_number().

◆ TAG

const char* TAG = "USB_HID"

static

USB composite descriptor/runtime builder for CDC plus optional HID/CCID interfaces.

Definition at line 22 of file usb_hid.cpp.

Functions

Variables

Function Documentation

◆ build_config_descriptor()

◆ init_serial_number()

◆ tud_descriptor_configuration_cb()

◆ tud_descriptor_device_cb()

◆ tud_descriptor_string_cb()

◆ tud_hid_descriptor_report_cb()

◆ tud_hid_get_report_cb()

◆ tud_hid_report_complete_cb()

◆ tud_hid_set_report_cb()

◆ usb_hid_apply_config()

◆ usb_hid_init()

◆ usb_hid_instance_ready()

◆ usb_hid_ready()

◆ usb_hid_send_report()

Variable Documentation

◆ device_descriptor

◆ FIXED_STRING_COUNT

◆ MAX_INTERFACES

◆ s_config_descriptor

◆ s_config_descriptor_len

◆ s_def_count

◆ s_defs

◆ s_dynamic_string_count

◆ s_dynamic_strings

◆ s_fixed_strings

◆ s_hid_count

◆ s_hid_initialized

◆ s_hid_map

◆ s_serial_number

◆ TAG