如何修改共享同一USBComposite实例的两个摇杆的各自名称？

问题根源 #

你做了个单设备集成双摇杆的HID外设，基于USBComposite_stm32f1库开发，但系统里两个摇杆名称完全一致，导致关联程序每次启动都丢失设置。改设备的VendorID、ProductString，或者手动改注册表都没效果——这是因为两个摇杆共享同一个HID设备的顶层描述符信息，系统把它们识别为同一设备下的不同报告ID，而非独立设备，所以顶层的产品字符串会被两个摇杆复用。

具体解决方案 #

要让系统识别成两个独立命名的摇杆，得给每个HID子设备单独指定字符串描述符，不能只依赖全局的ProductString。以下是修改步骤：

1. 自定义字符串与报告描述符 #

替换原代码中的描述符部分，为每个摇杆添加独立名称：

#include <Arduino.h>
#include <USBComposite.h>

// 自定义字符串描述符：索引1=厂商名，2=设备总名称，3=左摇杆，4=右摇杆
const USBStringDescriptor stringDescriptors[] = {
    USBStringDescriptor(L"你的厂商名称"),
    USBStringDescriptor(L"双摇杆复合设备"),
    USBStringDescriptor(L"左侧摇杆"),
    USBStringDescriptor(L"右侧摇杆")
};

// 手动构建双摇杆的HID报告描述符，为每个摇杆绑定独立标识
const uint8_t reportDescription[] = {
    HID_MOUSE_REPORT_DESCRIPTOR(),
    HID_KEYBOARD_REPORT_DESCRIPTOR(),
    // 左摇杆HID集合
    0x06, 0x00, 0xFF,        // 自定义Usage Page
    0x09, 0x01,              // 自定义Usage
    0xA1, 0x01,              // 开始应用集合
    0x85, HID_JOYSTICK_REPORT_ID, // 报告ID
    HID_JOYSTICK_REPORT_DESCRIPTOR_CONTENTS(), // 复用原摇杆的报告内容
    0xC0,                    // 结束集合
    // 右摇杆HID集合
    0x06, 0x00, 0xFF,        // 自定义Usage Page
    0x09, 0x02,              // 自定义Usage
    0xA1, 0x01,              // 开始应用集合
    0x85, HID_JOYSTICK_REPORT_ID+1, // 报告ID
    HID_JOYSTICK_REPORT_DESCRIPTOR_CONTENTS(), // 复用原摇杆的报告内容
    0xC0,                    // 结束集合
};

USBCompositeSerial CompositeSerial;
USBHID HID;
HIDJoystick Joystick(HID, HID_JOYSTICK_REPORT_ID);
HIDJoystick Joystick2(HID, HID_JOYSTICK_REPORT_ID+1);

void setup(){
    // 加载自定义字符串描述符
    USBComposite.setStrings(stringDescriptors, sizeof(stringDescriptors)/sizeof(USBStringDescriptor));
    // 初始化HID设备
    HID.begin(CompositeSerial, reportDescription, sizeof(reportDescription));
    while (!USBComposite);
    Joystick.setManualReportMode(true);
    Joystick2.setManualReportMode(true);
}

void loop(){  
    Joystick.send();
    Joystick2.send();
}

2. 核心修改说明 #

• 扩展字符串描述符：新增两个字符串分别对应左右摇杆，让系统能区分两者的名称。
• 拆分报告描述符：不再直接复用库的HID_JOYSTICK_REPORT_DESCRIPTOR()宏，手动构建每个摇杆的HID集合，确保每个集合有唯一的Usage值，方便系统识别为独立子设备。
• 绑定字符串到子设备：如果上述代码中字符串未生效，需要检查库的USB配置描述符，为每个HID接口添加独立的字符串索引字段（部分库需要在接口描述符里指定iInterface参数对应字符串索引）。

3. 备选方案（库不支持子设备字符串时） #

如果当前用的USBComposite_stm32f1库不支持为单个HID报告指定字符串，可以试试：

• 把两个摇杆拆成两个独立的HID接口，而非同一接口下的多个报告ID，每个接口用独立的字符串描述符，系统会识别成两个独立设备。
• 修改库的核心代码，在USB配置描述符中给每个HID接口添加独立的字符串索引。

验证 #

烧录修改后的固件，打开系统设备管理器查看“人机接口设备”，两个摇杆应该显示你自定义的不同名称，此时程序的设置就能分别保存，不会再丢失了。

内容的提问来源于stack exchange，提问作者Łukasz Piórecki