LUFA is a high-level USB library for AVRs generously released under MIT. It has considerable documentation, but no real guide stating what the bare-minimum functions are for any new / custom gadget.
LUFA is a high-level USB library for AVRs generously released under MIT. It has considerable documentation, but no real guide stating what the bare-minimum functions are for any new / custom gadget.
LUFA is a high-level USB library for AVRs generously released under MIT. It has considerable documentation, but no real guide stating what the bare-minimum functions are for any new / custom gadget.
2 December 8, 2009 Lately Ive been killing off course requirements by taking project based courses. Happily, Bart Massey offered a Linux device driver course that gave me an opportunity to get my hands dirty in the embedded world again. The project was to make an AVR based USB gadget do something anything. Most prior experience with Cs was with Rabbits a fitting name seeing as the useful and higher level libraries seemed to multiply like rabbits. Unfortunately, the AVRs didnt have any apparent high level library for USB; many of the examples used commented byte arrays as USB descriptors. While understandable, this feels harder to debug, ugly, and just generally wrong. Enter LUFA. LUFA LUFA is a high-level USB library for AVRs generously released under MIT. It has considerable documentation, but no real guide stating what the bare-minimum functions are for any new/custom gadget this is my attempt at providing such a guide. After you verify your AVR is supported by LUFA go ahead and download LUFA to an includes directory for your project. All code here is made possible by LUFA and its included examples Ill only claim to being the original author of any and all bugs. My Device Before going any further you should have an understanding of what your device will do, how many and what type of USB endpoints it will use (BULK, INTERRUPT, CONTROL, ISOCRONOUS), and what driver will support it. If you are making something that will use a generic driver, such as a HID, then you probably can stop here as there is plenty of code for you to use this post is aimed at people making custom devices. Im using a Teensy 2.0 with three bulk interfaces (two OUT one IN). One OUT provides commands to the gadget, which will change its state. Another OUT will send jobs to the gadget and the final IN will read the results of those jobs. This requires a custom driver which I and several other folks developed for course work. The Makefile Its probably safe for you to rip-off one of the makefiles from an example in LUFA/Demo/Devices/LowLevel/. Noitice several of the defines change the API, defines I used for this post/project include: -DUSB_DEVICE_ONLY # Saves space if you only need gadget-side code -DNO_STREAM_CALLBACKS # Changes the API to exclude any callbacks on streams -DINTERRUPT_CONTROL_ENDPOINT # So you don't have to call USB_USBTask() manually on a regular basis -DUSE_FLASH_DESCRIPTORS # Save RAM, leave these in the Flash -DUSE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_AUTO_PLL)" EDIT: All the makefiles Ive seen are broken, they dont properly track dependencies, so either fix that or be sure to make clean prior to each build. Enumeration When your gadget is plugged in its going to have to enumerate its interfaces by sending descriptors to the host. Start by declaring a global USB_Descriptor_Device_t along with Language, Manufacturer and Product structures: typedef struct { USB_Descriptor_Configuration_Header_t Config; USB_Descriptor_Interface_t Interface; USB_Descriptor_Endpoint_t DataInEndpoint; USB_Descriptor_Endpoint_t DataOutEndpoint; USB_Descriptor_Endpoint_t CommandEndpoint; } USB_Descriptor_Configuration_t;
So now you see I have a device with a single interface and three bulk endpoints (two OUT and one IN). Remember, in USB terminology OUT means from the HOST to the GADGET while IN means from the GADGET to the HOST. While there is a direction to these channels, USB 1.0 and 2.0 BULK communications start with the host sending a message to the device (i.e. IN endpoints are polled) and the device should always respond. Now that we have descriptors lets be sure to send them when the host tries to enumerate the device. uint16_t CALLBACK_USB_GetDescriptor (const uint16_t wValue, const uint8_t wIndex, void **const DescriptorAddress) { const uint8_t DescriptorType = (wValue >> 8); const uint8_t DescriptorNumber = (wValue & 0xFF);
switch (DescriptorType) { case DTYPE_Device: Address = (void*)&DeviceDescriptor; Size = sizeof(USB_Descriptor_Device_t); break; case DTYPE_Configuration: Address = (void*)&ConfigurationDescriptor; Size = sizeof(USB_Descriptor_Configuration_t); break; case DTYPE_String: switch (DescriptorNumber) { case 0x00: Address = (void*)&LanguageString; Size = pgm_read_byte(&LanguageString.Header.Size); break; case 0x01: Address = (void*)&ManufacturerString; Size = pgm_read_byte(&ManufacturerString.Header.Size); break; case 0x02: Address = (void*)&ProductString; Size = pgm_read_byte(&ProductString.Header.Size); break; } break; }
*DescriptorAddress = Address; return Size; }
With this, and calling USB_Init() when your device starts up, you should have a gadget that is properly enumerated by the matching driver. Once a configuration is selected we need to configure the endpoints, but after that we can finally send and receive data! void EVENT_USB_Device_ConfigurationChanged(void) { int i,succ=1;
succ &= Endpoint_ConfigureEndpoint(COMMAND_EPNUM,EP_TYPE_BULK,ENDPOINT_DIR_OUT, COMMAND_EPSIZE,ENDPOINT_BANK_SINGLE); LED_CONFIG; while(!succ) { LED_ON; _delay_ms(1000); LED_OFF; _delay_ms(1000); } for(i = 0; i < 5; i ++) { LED_ON; _delay_ms(50); LED_OFF; _delay_ms(50); } } Now to handle any data on the endpoints, youll probably want to tight loop around code that checks each endpoint, reads data, and performs some action: if (USB_DeviceState != DEVICE_STATE_Configured) return;
Endpoint_SelectEndpoint(COMMAND_EPNUM); if (Endpoint_IsConfigured() && Endpoint_IsOUTReceived() && Endpoint_IsReadWriteAllowed()) { usb_cmd_t cmd; err = Endpoint_Read_Stream_LE(&cmd, sizeof(usb_cmd_t)); update_state(cmd); Endpoint_ResetFIFO(BULK_IN_EPNUM); Endpoint_ResetFIFO(BULK_OUT_EPNUM); Endpoint_ClearOUT(); }And thats the whole deal. Some things to take note of: 1) I dont know why I needed Endpoint_ResetFIFO() my results lagged by one message without them but I feel certain this is not the correct way to fix the issue. Perhaps I need to reset the endpoints some time after configuration and before use, but Im not sure which callback to use for that, if thats the case. 2) C needs phantom types. Many of these functions arent intended for use with CONTROL endpoints. See the LUFA documentation for which functions to use if you have non-BULK endpoints. 3) Be sure to number your ENDPOINTS starting at 1 (the *_EPNUM values). Ive seen unusual behavior when numbering started higher not sure if that was against standards or not. Conclusion At a minimum, you must declare a USB_Descriptor_Device_t variable, three USB_Descriptor_String_t variables (Language, Manufacturer, Product), a custom USB_Descriptor_Configuration_t structure and variable. Also declare a function named CALLBACK_USB_GetDescriptor and one called EVENT_USB_Device_ConfigurationChanged(void) which calls Endpoint_ConfigureEndpoint(*_EPNUM, EP_TYPE_{BULK, INT, CONTROL, ISOC}, ENDPOINT_DIR_{IN,OUT}, *_EPSIZE, ENDPOINT_BANK_{DOUBLE,SINGLE}); for each endpoint in the configuration. Finally use Endpoint_SelectEndpoint(*_EPNUM) followed by Endpoint_Is{INReady,OutReceived}() && Endpoint_IsReadWriteAllowed() to select an endpoint and check for data. Finish all this by reading your stream Endpoint_Read_Stream_LE(buf, len) and issue a call to Endpoint_Clear{IN,OUT}() when done.