Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# Example application

This section contains a fully worked example of implementing a USB mouse device compliant to the Human Interface Device (HID) Class mouse device.

The application operates as a simple mouse which when running moves the mouse pointer on the host machine. This demonstrates the simple way in which PC peripheral devices can easily be deployed using an xcore device.

Note

This application note provides a standard USB HID class device and as a result does not require drivers to run on Windows, macOS or Linux.

The full source for this application is provided along side the `lib_xud` software download in the examples/app_hid_house directory.

Note

The example code provides implementations in C and XC. This section concentrates on the XC version.

## Required hardware

This application note is designed to run on XMOS xcore-200 or xcore.ai series devices.

The example code provided has been implemented and tested on the XK-EVK-XU316 board but there is no dependency on this board and it can be modified to run on any development board which uses an xcore-200 or xcore.ai series device.

## Declarations

    #include "xud_device.h"
    #include "hid.h"
    #include "hid_descs.h"

    /* Number of Endpoints used by this app */
    #define EP_COUNT_OUT   1
    #define EP_COUNT_IN    2

    /* Endpoint type tables - informs XUD what the transfer types for each Endpoint in use and also
     * if the endpoint wishes to be informed of USB bus resets
     */
    XUD_EpType epTypeTableOut[EP_COUNT_OUT] = {XUD_EPTYPE_CTL | XUD_STATUS_ENABLE};
    XUD_EpType epTypeTableIn[EP_COUNT_IN] =   {XUD_EPTYPE_CTL | XUD_STATUS_ENABLE, XUD_EPTYPE_BUL};

## `main()`

The `main()` function creates three tasks: the XUD Io task, endpoint 0, and a task for handling the HID endpoint. An array of channels is used for both IN and OUT endpoints, endpoint 0 requires both, the HID task simply implements an IN endpoint sending mouse data to the host.

    int main()
    {
        chan c_ep_out[EP_COUNT_OUT];
        chan c_ep_in[EP_COUNT_IN];

        par
        {
            on tile[0]: XUD_Main(c_ep_out, EP_COUNT_OUT, c_ep_in, EP_COUNT_IN, null,
                                 epTypeTableOut, epTypeTableIn, XUD_SPEED_HS, XUD_PWR_BUS);

            on tile[0]: Endpoint0(c_ep_out[0], c_ep_in[0]);

            on tile[0]: hid_mouse(c_ep_in[1]);
        }

        return 0;
    } //

Since this example does not require SOF notifications `null` is passed into the `c_sof` parameter. `XUD_SPEED_HS` is passed for the `desiredSpeed` parameter such that the device attempts to run as a high-speed device.

## HID endpoint task

This function responds to the HID requests - it moves the mouse cursor in square by moving 40 pixels in each direction in sequence every 100 requests using a basic state-machine. This function could be easily changed to feed other data back (for example based on user input).

    void hid_mouse(chanend chan_ep_hid)
    {
        int counter = 0;
        enum {RIGHT, DOWN, LEFT, UP} state = RIGHT;

        XUD_ep ep_hid = XUD_InitEp(chan_ep_hid);

        for(;;)
        {
            /* Move the pointer around in a square (relative) */
            if(counter++ >= 500)
            {
                int x;
                int y;

                switch(state)
                {
                    case RIGHT:
                        x = 40;
                        y = 0;
                        state = DOWN;
                        break;

                    case DOWN:
                        x = 0;
                        y = 40;
                        state = LEFT;
                        break;

                    case LEFT:
                        x = -40;
                        y = 0;
                        state = UP;
                        break;

                    case UP:
                    default:
                        x = 0;
                        y = -40;
                        state = RIGHT;
                        break;
                }

                /* Unsafe region so we can use shared memory. */
                unsafe
                {
                    char * unsafe p_reportBuffer = g_reportBuffer;

                    p_reportBuffer[1] = x;
                    p_reportBuffer[2] = y;

                    /* Send the buffer to the host.  Note this will return when complete */
                    XUD_SetBuffer(ep_hid, (char *) p_reportBuffer, sizeof(g_reportBuffer));
                    counter = 0;
                }
            }
        }
    } //

Note, this endpoint does not receive or check for status data. It always performs IN transactions. Since it’s behaviour is not modified based on bus speed the mouse cursor will move more slowly when connected via a full-speed port. Ideally the device would either modify its required polling rate in its descriptors (bInterval in the endpoint descriptor) or the counter value it is using in the `hid_mouse()` function.

Should processing take longer that the host IN polls, the `XUD_Main()` task will simply NAK the host. The `XUD_SetBuffer()` function will return when the packet transmission is complete.

## Device descriptors

The `USB_StandardRequests()` function expects descriptors to be declared as arrays of characters. Descriptors are looked at in depth in this section.

Note

`null` values and length 0 are passed for the full-speed descriptors, this means that the same descriptors will be used whether the device is running in full or high-speed.

### Device descriptor

The device descriptor contains basic information about the device. This descriptor is the first descriptor the host reads during its enumeration process and it includes information that enables the host to further interrogate the device. The descriptor includes information on the descriptor itself, the device (USB version, vendor ID etc.), its configurations and any classes the device implements. For the HID Mouse example this descriptor looks like the following:

    static unsigned char devDesc[] =
    {
        0x12,                  /* 0  bLength */
        USB_DESCTYPE_DEVICE,   /* 1  bdescriptorType */
        0x00,                  /* 2  bcdUSB */
        0x02,                  /* 3  bcdUSB */
        0x00,                  /* 4  bDeviceClass */
        0x00,                  /* 5  bDeviceSubClass */
        0x00,                  /* 6  bDeviceProtocol */
        0x40,                  /* 7  bMaxPacketSize */
        (VENDOR_ID & 0xFF),    /* 8  idVendor */
        (VENDOR_ID >> 8),      /* 9  idVendor */
        (PRODUCT_ID & 0xFF),   /* 10 idProduct */
        (PRODUCT_ID >> 8),     /* 11 idProduct */
        (BCD_DEVICE & 0xFF),   /* 12 bcdDevice */
        (BCD_DEVICE >> 8),     /* 13 bcdDevice */
        0x01,                  /* 14 iManufacturer */
        0x02,                  /* 15 iProduct */
        0x00,                  /* 16 iSerialNumber */
        0x01                   /* 17 bNumConfigurations */
    };

### Device qualifier descriptor

Devices which support both full and high-speeds must implement a device qualifier descriptor. The device qualifier descriptor defines how fields of a high speed device’s descriptor would look if that device is run at a different speed. If a high-speed device is running currently at full/high speed, fields of this descriptor reflect how device descriptor fields would look if speed was changed to high/full. Please refer to section 9.6.2 of the USB 2.0 specification for further details.

For a full-speed only device this is not required.

Typically a device qualifier descriptor is derived mechanically from the device descriptor. The `USB_StandardRequest()` function will build a device qualifier from the device descriptors passed to it based on the speed the device is currently running at.

### Configuration descriptor

The configuration descriptor contains the devices features and abilities. This descriptor includes Interface and Endpoint Descriptors. Every device must have at least one configuration, in this example there is only one configuration. The configuration descriptor is presented below:

    static unsigned char cfgDesc[] = {
        0x09,                 /* 0  bLength */
        0x02,                 /* 1  bDescriptortype */
        0x22, 0x00,           /* 2  wTotalLength */
        0x01,                 /* 4  bNumInterfaces */
        0x01,                 /* 5  bConfigurationValue */
        0x03,                 /* 6  iConfiguration */
        0x80,                 /* 7  bmAttributes */
        0xC8,                 /* 8  bMaxPower */

        0x09,                 /* 0  bLength */
        0x04,                 /* 1  bDescriptorType */
        0x00,                 /* 2  bInterfacecNumber */
        0x00,                 /* 3  bAlternateSetting */
        0x01,                 /* 4: bNumEndpoints */
        0x03,                 /* 5: bInterfaceClass */
        0x00,                 /* 6: bInterfaceSubClass */
        0x02,                 /* 7: bInterfaceProtocol*/
        0x00,                 /* 8  iInterface */

        0x09,                 /* 0  bLength. Note this is replicated in hidDescriptor[] */
        0x21,                 /* 1  bDescriptorType (HID) */
        0x11,                 /* 2  bcdHID */
        0x01,                 /* 3  bcdHID */
        0x00,                 /* 4  bCountryCode */
        0x01,                 /* 5  bNumDescriptors */
        0x22,                 /* 6  bDescriptorType[0] (Report) */
        0x32,                 /* 7  wDescriptorLength */
        0x00,                 /* 8  wDescriptorLength */

        0x07,                 /* 0  bLength */
        0x05,                 /* 1  bDescriptorType */
        0x81,                 /* 2  bEndpointAddress */
        0x03,                 /* 3  bmAttributes */
        0x40,                 /* 4  wMaxPacketSize */
        0x00,                 /* 5  wMaxPacketSize */
        0x0a                  /* 6  bInterval */
    };

### Other Speed Configuration descriptor

An Other Speed Configuration descriptor is used for similar reasons as the Device Qualifier descriptor. The `USB_StandardRequests()` function generates this descriptor from the Configuration descriptors passed to it based on the bus speed it is currently running at. For the HID mouse example the same Configuration descriptors are uses regardless of bus-speed (i.e. full-speed or high-speed).

### String descriptors

An array of strings supplies all the strings that are referenced from the descriptors (using fields such as ‘iInterface’, ‘iProduct’ etc.). The string at index 0 must always contain the Language ID Descriptor. This descriptor indicates the languages that the device supports for string descriptors.

The `USB_StandardRequests()` function deals with requests for strings using the table of strings passed to it. It handles the conversion of the raw strings to valid USB string descriptors.

The string table for the HID mouse example is shown below:

        static char * unsafe stringDescriptors[]=
        {
            "\x09\x04",             // Language ID string (US English)
            "XMOS",                 // iManufacturer
            "Example HID Mouse",    // iProduct
            "Config",               // iConfiguration
        };

## Application and class specific requests

Although the `USB_StandardRequests()` function deals with many of the requests the device is required to handle in order to be properly enumerated by a host, typically a USB device will have Class (or Application) specific requests that must be handled.

In the case of the HID mouse there are three mandatory requests that must be handled:

- `GET_DESCRIPTOR`

  - `HID`: Return the HID descriptor

  - `REPORT`: Return the HID report descriptor

  - `GET_REPORT`: Return the HID report data

See the HID Class Specification and related documentation for full details of all HID requests.

The HID report descriptor informs the host of the contents of the HID reports that the device sending to the host periodically. For a mouse this could include X/Y axis values, button presses etc. A tool for building these descriptors is available for download on the usb.org website.

The HID report descriptor for the HID mouse example is shown below:

    static unsigned char hidReportDescriptor[] =
    {
        0x05, 0x01,   /* Usage Page (Generic Desktop) */
        0x09, 0x02,   /* Usage (Mouse) */
        0xA1, 0x01,   /* Collection (Application) */
        0x09, 0x01,   /* Usage (Pointer) */
        0xA1, 0x00,   /* Collection (Physical) */
        0x05, 0x09,   /* Usage Page (Buttons) */
        0x19, 0x01,   /* Usage Minimum (01) */
        0x29, 0x03,   /* Usage Maximum (03) */
        0x15, 0x00,   /* Logical Minimum (0) */
        0x25, 0x01,   /* Logical Maximum (1) */
        0x95, 0x03,   /* Report Count (3) */
        0x75, 0x01,   /* Report Size (1) */
        0x81, 0x02,   /* Input (Data,Variable,Absolute); 3 button bits */
        0x95, 0x01,   /* Report Count (1) */
        0x75, 0x05,   /* Report Size (5) */
        0x81, 0x01,   /* Input(Constant); 5 bit padding */
        0x05, 0x01,   /* Usage Page (Generic Desktop) */
        0x09, 0x30,   /* Usage (X) */
        0x09, 0x31,   /* Usage (Y) */
        0x15, 0x81,   /* Logical Minimum (-127) */
        0x25, 0x7F,   /* Logical Maximum (127) */
        0x75, 0x08,   /* Report Size (8) */
        0x95, 0x02,   /* Report Count (2) */
        0x81, 0x06,   /* Input (Data,Variable,Relative); 2 position bytes (X & Y) */
        0xC0,         /* End Collection */
        0xC0          /* End Collection */
    };

The request for this descriptor (and the other required requests) should be implemented before making the call to `USB_StandardRequests()`. The programmer may decide not to make a call to `USB_StandardRequests` if the request is fully handled. It is possible the programmer may choose to implement some functionality for a request, then allow `USB_StandardRequests()` to finalise.

The complete code listing for the main endpoint 0 task is shown below:

    void Endpoint0(chanend chan_ep0_out, chanend chan_ep0_in)
    {
        USB_SetupPacket_t sp;

        unsigned bmRequestType;
        XUD_BusSpeed_t usbBusSpeed;

        XUD_ep ep0_out = XUD_InitEp(chan_ep0_out);
        XUD_ep ep0_in  = XUD_InitEp(chan_ep0_in);

        while(1)
        {
            /* Returns XUD_RES_OKAY on success */
            XUD_Result_t result = USB_GetSetupPacket(ep0_out, ep0_in, sp);

            if(result == XUD_RES_OKAY)
            {
                /* Set result to ERR, we expect it to get set to OKAY if a request is handled */
                result = XUD_RES_ERR;

                /* Stick bmRequest type back together for an easier parse... */
                bmRequestType = (sp.bmRequestType.Direction<<7) |
                                (sp.bmRequestType.Type<<5) |
                                (sp.bmRequestType.Recipient);

                if ((bmRequestType == USB_BMREQ_H2D_STANDARD_DEV) &&
                    (sp.bRequest == USB_SET_ADDRESS))
                {
                  // Host has set device address, value contained in sp.wValue
                }

                switch(bmRequestType)
                {
                    /* Direction: Device-to-host
                     * Type: Standard
                     * Recipient: Interface
                     */
                    case USB_BMREQ_D2H_STANDARD_INT:

                        if(sp.bRequest == USB_GET_DESCRIPTOR)
                        {
                            /* HID Interface is Interface 0 */
                            if(sp.wIndex == 0)
                            {
                                /* Look at Descriptor Type (high-byte of wValue) */
                                unsigned short descriptorType = sp.wValue & 0xff00;

                                switch(descriptorType)
                                {
                                    case HID_HID:
                                        result = XUD_DoGetRequest(ep0_out, ep0_in, hidDescriptor, sizeof(hidDescriptor), sp.wLength);
                                        break;

                                    case HID_REPORT:
                                        result = XUD_DoGetRequest(ep0_out, ep0_in, hidReportDescriptor, sizeof(hidReportDescriptor), sp.wLength);
                                        break;
                                }
                            }
                        }
                        break;

                    /* Direction: Device-to-host and Host-to-device
                     * Type: Class
                     * Recipient: Interface
                     */
                    case USB_BMREQ_H2D_CLASS_INT:
                    case USB_BMREQ_D2H_CLASS_INT:

                        /* Inspect for HID interface num */
                        if(sp.wIndex == 0)
                        {
                            /* Returns  XUD_RES_OKAY if handled,
                             *          XUD_RES_ERR if not handled,
                             *          XUD_RES_RST for bus reset */
                            result = HidInterfaceClassRequests(ep0_out, ep0_in, sp);
                        }
                        break;
                }
            }

            /* If we haven't handled the request about then do standard enumeration requests */
            if(result == XUD_RES_ERR )
            {
                /* Returns  XUD_RES_OKAY if handled okay,
                 *          XUD_RES_ERR if request was not handled (STALLed),
                 *          XUD_RES_RST for USB Reset */
                unsafe
                {
                    result = USB_StandardRequests(ep0_out, ep0_in, devDesc,
                            sizeof(devDesc), cfgDesc, sizeof(cfgDesc),
                            null, 0, null, 0, stringDescriptors, sizeof(stringDescriptors)/sizeof(stringDescriptors[0]),
                            sp, usbBusSpeed);
                }
            }

            /* USB bus change detected, */
            if(result == XUD_RES_UPDATE)
            {
                XUD_BusState_t busState = XUD_GetBusState(ep0_out, ep0_in);

                if(busState == XUD_BUS_RESET)
                {
                    /* Reset EP and get new bus speed */
                     usbBusSpeed = XUD_ResetEndpoint(ep0_out, ep0_in);
                }
                else if(busState == XUD_BUS_SUSPEND)
                {
                    /* Perform suspend actions */

                    /* Acknowledge back to XUD letting it know we've handled suspend */
                    XUD_AckBusState(ep0_out, ep0_in);
                }
                else if(busState == XUD_BUS_RESUME)
                {
                    /* Perform resume actions */

                    /* Acknowledge back to XUD letting it know we've handled resume */
                    XUD_AckBusState(ep0_out, ep0_in);
                }
            }
        }
    } /* Endpoint0 */

The skeleton `HidInterfaceClassRequests()` function deals with any outstanding HID requests. See the USB HID Specification for full request details:

    XUD_Result_t HidInterfaceClassRequests(XUD_ep c_ep0_out, XUD_ep c_ep0_in, USB_SetupPacket_t sp)
    {
        unsigned char buffer[64];

        switch(sp.bRequest)
        {
            case HID_GET_REPORT:

                /* Mandatory. Allows sending of report over control pipe */
                /* Send a hid report - note the use of unsafe due to shared mem */
                unsafe {
                  char * unsafe p_reportBuffer = g_reportBuffer;
                  for (int i = 0; i < sizeof(g_reportBuffer); i++)
                    buffer[i] = g_reportBuffer[i];
                }

                return XUD_DoGetRequest(c_ep0_out, c_ep0_in, buffer, sizeof(g_reportBuffer), sp.wLength);
                break;

            case HID_GET_IDLE:
                /* Return the current Idle rate - optional for a HID mouse */

                /* Do nothing - i.e. STALL */
                break;

            case HID_GET_PROTOCOL:
                /* Required only devices supporting boot protocol devices,
                 * which this example does not */

                /* Do nothing - i.e. STALL */
                break;

             case HID_SET_REPORT:
                /* The host sends an Output or Feature report to a HID
                 * using a cntrol transfer - optional */

                /* Do nothing - i.e. STALL */
                break;

            case HID_SET_IDLE:
                /* Set the current Idle rate - this is optional for a HID mouse
                 * (Bandwidth can be saved by limiting the frequency that an
                 * interrupt IN EP when the data hasn't changed since the last
                 * report */

                /* Do nothing - i.e. STALL */
                break;

            case HID_SET_PROTOCOL:
                /* Required only devices supporting boot protocol devices,
                 * which this example does not */

                /* Do nothing - i.e. STALL */
                break;
        }

        return XUD_RES_ERR;
    } /* HidInterfaceClassRequests */

If the HID request is not handled, the function returns `XUD_RES_ERR`. This results in `USB_StandardRequests()` being called, and eventually the endpoint responding to the host with a STALL to indicate an unsupported request.