Implemented XBOX Controller Host Support

[phatchman]

Hi All,

I've implemented support for the XBOX controller in host mode, but would like some ideas on the best way to cleanly integrate this into the tinyusb source.

XBOX Controllers are HID Devices, with 2 exceptions:

1. The descriptor passed into hidh_open does not contain the HID descriptor (tusb_hid_descriptor_hid_t). It only sends the interface descriptor and endpoint descriptors.
2. The controller does not provide a HID Report Descriptor i.e. will not respond to tuh_descriptor_get_hid_report.

Otherwise it behaves exactly like a HID device and can be handled by hid_host.c

The way I've implemented support is to provide 3 callbacks so that user-code can provide the missing descriptors.

// Return true if this is a supported vendor specific HID device
// Called if TUSB_CLASS_VENDOR_SPECIFIC == desc_itf->bInterfaceClass in hidh_open.
TU_ATTR_WEAK bool tuh_hid_is_hid_device_cb(uint16_t vid, uint16_t pid, uint8_t itf_num);

// Get the HID descriptor in descriptor for this device
// Called in hidh_open if tuh_hid_is_hid_device returns true 
TU_ATTR_WEAK bool tuh_hid_get_hid_descriptor_cb(uint16_t vid, uint16_t pid, tusb_hid_descriptor_hid_t *descriptor);

// Get the vendor specific HID report
// Called in process_set_config in case CONFIG_GET_REPORT_DESC. If returns true, the provided descriptor is used,
// otherwise the normal tuh_descriptor_get_hid_report is called.
TU_ATTR_WEAK bool tuh_descriptor_get_hid_report_cb(uint16_t vid, uint16_t pid, uint8_t **desc_report, uint16_t *desc_len);

This seems to work quite well for my purposes, with minimal changes to hid_host.c.

Does this seem like a valid approach? My concern that this is going to be quite specific to the XBOX controller and not generally applicable. But I can't see a better way as making an xbox-specific class is basically going to duplicate all of the hid_host code.

The user-code looks something like below (Note the HID report descriptor is not correct, it's a very minimal one that suits my purpose)

/* Callbacks for XBOX Controller support */
bool tuh_hid_is_hid_device_cb(uint16_t vid, uint16_t pid, uint8_t itf_num)
{
    /* Support interface 0 on xbox contollers */
    return itf_num == 0 && is_xbox_controller(pid);
}

// Get the HID descriptor in descriptor for this device
bool tuh_hid_get_hid_descriptor_cb(uint16_t vid, uint16_t pid, tusb_hid_descriptor_hid_t *descriptor)
{
    static uint8_t xbox_descriptor[] = { 0x09, 0x21, 0x10, 0x01, 0x21, 0x01, 0x22, 0xff, 0x00 };

    if (!is_xbox_controller(pid))
        return false;
    
    memcpy(descriptor, xbox_descriptor, sizeof(tusb_hid_descriptor_hid_t));

    return true;
}

/* Get the vendor specific HID report */
bool tuh_descriptor_get_hid_report_cb(uint16_t vid, uint16_t pid, uint8_t **desc_report, uint16_t *desc_len)
{
    /* This is a minimal HID report descriptor just to get the buttons and X/Y inputs */
    static uint8_t xbox_hid[] = { 
        0x05, 0x01, 0x09, 0x04, 0xA1, 0x01, 0xA1, 0x02, 0x85, 0x20, 0x75, 0x08, 0x95, 0x03, 
        0x06, 0x00, 0xFF, 0x81, 0x03, 0x75, 0x01, 0x95, 0x04, 0x06, 0x00, 0xFF, 0x81, 0x02, 
        0x95, 0x0C, 0x15, 0x00, 0x25, 0x01, 0x05, 0x09, 0x81, 0x02, 0x75, 0x08, 0x95, 0x04, 
        0x06, 0x00, 0xFF, 0x81, 0x03, 0xC0, 0xA1, 0x00, 0x75, 0x10, 0x95, 0x02, 0x15, 0x00, 
        0x27, 0xFF, 0xFF, 0x00, 0x00, 0x09, 0x30, 0x09, 0x31, 0x81, 0x03, 0xC0, 0xC0
    };
    
    if (!is_xbox_controller(pid))
        return false;
    
    *desc_report = xbox_hid;
    *desc_len = sizeof(xbox_hid);
    return true;
}

If the approach makes sense, I'll send through a pull request with the changes and an example.

[hathach]

late response, but the approach can be much simpler. There is an example that handle PS4 dual shock controller using vid/pid matching https://github.com/hathach/tinyusb/blob/master/examples/host/hid_controller/src/hid_app.c . I don't have an xbox controller and therefore couldn't test/add its support yet. It is strange that xbox does not contain hid descriptor and report descriptor, would you mind pasting/attaching its configuration descriptor here.

[Norto04]

DescriptorDump_Rock_Candy_Gamepad_for_Xbox_360.txt

Heres a Descriptor Dump of a 3rd party 360 Controller, should work the same as an official one

[KunYi]

implement the host driver to support Xbox Controller with RT-Thread
you can visit https://github.com/RT-Thread-Studio/sdk-bsp-ra8d1-vision-board/tree/master/projects/usb/vision_board_tinyusb_xpad/board/tinyusb
to check

and integration with DOOM, video on https://streamable.com/4xs72c