Memos From the Cube

I’ve come to realise that the current design of the LUFA API was a bad idea in many respects. Most people were confused by the simple “Scheduler” included in the demos, which was just a nice way (IMHO, of course) of thinking about the multitude of functions normally called in a loop within a project’s main function. Many people took a look at all the class boilerplate code required to implement each USB class in the demos and spat the dummy – I’m looking at you, Arduino programmers – and were turned off using the library.

As such, now that I’ve realised the library’s shortcomings, I’m moving towards correcting them. That means removing the psuedo-scheduler from the library, as well as making generic class drivers for both host and device mode inside the library that can be referenced by the user code if desired. Of course, this will not change the underlying API, and those wanting to implement their own classes (like in the case of the DFU bootloader) or use the low level library API will not be affected. However, this will mean that the focus in the demos will be on the demo’s functionality, and not all the USB code around it to get it to work.
Contrast the existing Keyboard device demo from LUFA 090510, with the current in-work version using the HID class driver I’m developing:

#include "Keyboard.h"

USB_ClassInfo_HID_t Keyboard_HID_Interface =
    {
        .InterfaceNumber         = 0,

        .ReportINEndpointNumber  = KEYBOARD_EPNUM,
        .ReportINEndpointSize    = KEYBOARD_EPSIZE,

        .ReportOUTEndpointNumber = KEYBOARD_LEDS_EPNUM,
        .ReportOUTEndpointSize   = KEYBOARD_EPSIZE,

        .IdleCount               = 500,
    };

int main(void)
{
    SetupHardware();

    LEDs_SetAllLEDs(LEDMASK_USB_NOTREADY);

    for (;;)
    {
        USB_HID_USBTask(&Keyboard_HID_Interface);
        USB_USBTask();
    }
}

void SetupHardware()
{
    /* Disable watchdog if enabled by bootloader/fuses */
    MCUSR &= ~(1 << WDRF);
    wdt_disable();

    /* Disable clock division */
    clock_prescale_set(clock_div_1);

    /* Hardware Initialization */
    Joystick_Init();
    LEDs_Init();
    Buttons_Init();
    USB_Init();
}

void EVENT_USB_Connect(void)
{
    LEDs_SetAllLEDs(LEDMASK_USB_ENUMERATING);
}

void EVENT_USB_Disconnect(void)
{
    LEDs_SetAllLEDs(LEDMASK_USB_NOTREADY);
}

void EVENT_USB_ConfigurationChanged(void)
{
    LEDs_SetAllLEDs(LEDMASK_USB_READY);

    if (!(USB_HID_ConfigureEndpoints(&Keyboard_HID_Interface)))
      LEDs_SetAllLEDs(LEDMASK_USB_ERROR);
}

void EVENT_USB_UnhandledControlPacket(void)
{
    USB_HID_ProcessControlPacket(&Keyboard_HID_Interface);
}

void EVENT_USB_StartOfFrame(void)
{
    USB_HID_RegisterStartOfFrame(&Keyboard_HID_Interface);
}

uint16_t CALLBACK_USB_HID_CreateNextHIDReport(USB_ClassInfo_HID_t* HIDInterfaceInfo, void* ReportData)
{
    USB_KeyboardReport_Data_t* KeyboardReport = (USB_KeyboardReport_Data_t*)ReportData;

    uint8_t JoyStatus_LCL    = Joystick_GetStatus();
    uint8_t ButtonStatus_LCL = Buttons_GetStatus();

    if (JoyStatus_LCL & JOY_UP)
      KeyboardReport->KeyCode[0] = 0x04; // A
    else if (JoyStatus_LCL & JOY_DOWN)
      KeyboardReport->KeyCode[0] = 0x05; // B

    if (JoyStatus_LCL & JOY_LEFT)
      KeyboardReport->KeyCode[0] = 0x06; // C
    else if (JoyStatus_LCL & JOY_RIGHT)
      KeyboardReport->KeyCode[0] = 0x07; // D

    if (JoyStatus_LCL & JOY_PRESS)
      KeyboardReport->KeyCode[0] = 0x08; // E

    if (ButtonStatus_LCL & BUTTONS_BUTTON1)
      KeyboardReport->KeyCode[0] = 0x09; // F

    return sizeof(USB_KeyboardReport_Data_t);
}

void CALLBACK_USB_HID_ProcessReceivedHIDReport(USB_ClassInfo_HID_t* HIDInterfaceInfo, void* ReportData, uint16_t ReportSize)
{
    uint8_t  LEDMask   = LEDS_NO_LEDS;
    uint8_t* LEDReport = (uint8_t*)ReportData;

    if (*LEDReport & 0x01) // NUM Lock
      LEDMask |= LEDS_LED1;

    if (*LEDReport & 0x02) // CAPS Lock
      LEDMask |= LEDS_LED3;

    if (*LEDReport & 0x04) // SCROLL Lock
      LEDMask |= LEDS_LED4;

    LEDs_SetAllLEDs(LEDMask);
}

Yep, that’s the whole code, other than the supporting header files and descriptors. As you can see, it all revolves around the new HID class driver, which implements all the backend needed (between the user application and the LUFA library) for the HID USB class. You create a new global of each class driver’s type (for multiple instances of the same class, you make multiple instances of the class driver’s state structure), fill in the required values to match your device’s descriptors, and then link the LUFA events to the class driver functions. Each class driver can also define its own custom events and callbacks for the user application, which is the case here; the HID driver calls the CreateNextHIDReport() and ProcessReceivedHIDReport() functions when reports are sent and received.

This new system means more robust applications, as all the work is in the library itself; as the library is updated, so are all the class drivers. The best part is that it makes it trivial to create compound devices of several interfaces, both of the same class and of multiple different classes.

These changes will be visible in the next release of LUFA, scheduled in the next week or two.