Memos From the Cube

I’ve caved. I’ve started to write my own book on USB communications, focusing on the Atmel USB AVR line of microcontrollers. No idea how it’ll turn out, but it should be fun either way. The end result should be easy enough for competent AVR programmers to use - since the USBXXX AVRs cover the physical USB layer transparently, the book can skip over all that to reduce confusion. I’ve posted a thread on AVRFreaks about the book outline, so post in there if you want your voice heard!

I got an email from a Stefan Salewski PHD (read: much smarter guy than I) who informed me about his own GPL USBXXX driver. Check it out here. It lacks a lot of the features that MyUSB has, but produces much tighter code due to being a bare-bones approach.

Yesterday I received my brand new RZRAVEN boards, courtesy of Atmel. Unfortunately, like so many others, my units came with broken speakers; good thing Atmel says they’ll be working on ways to prevent such problems when the kits start shipping. No firmware available for the boards yet, so I’m restricted to playing with the default firmware. I’ve already added the RZUSBSTICK board to the MyUSB library, which was a very easy task due to the lack of peripherals on the board and the fact that it’s based on the AT90USB1287 AVR.

I’ve been pleasantly surprised to see a fantastic blog post about my old ButtLoad project on someone else’s site, complete with a few neat pictures and a trip report for the construction of a version modified using Nard Awater’s plans to make it USB enabled. I do recommend checking out the post, it’s a fun read. Great to hear ButtLoad’s being useful!

I’ve now modified the USB DFU bootloader included with MyUSB slightly, as I just realised that the different target AVRs are supposed to return different PID (Product ID) values in the USB descriptors so that FLIP can identify the chip model. That and other minor corrections will be in the 1.3.2 release. Thanks to everyone who’s been emailing me with questions, comments and bugs about the project.

Yesterday I thought I’d try something a little different, and see if a lecture style presentation would be a suitable replacement for traditional text tutorials. I whipped up a few slides on the basics of USB (download it here) and posted it to AVRFreaks for comments. The general consensus - which I agree with having tried it out - is that text tutorials are superior for complicated topics, although I believe the narrated lectures would work for getting basic concepts down.

First law of computer software engineering: there will be bugs. That’s well known. The not-so well know bit is that 30% of the bugs will be discovered immediately after a public release.

I’m already working on a 1.3.2 release to fix up any outstanding issues. So far it’s limited to the demos only (specifically, a few glitches in the CDC and USBtoSerial demos. I’ve also changed the code so that the control endpoint size is determined by the device descriptors, rather than being a fixed number of bytes. That adds more flexibility, as the control endpoint size can be adjusted as needed between projects with no library modifications.

I’m running out of ideas for MyUSB, so I might have to finish it up soon and start with something else new (no idea what at this point, I’ve got a terrible imagination). Or perhaps I’ll start to write a book about AVRs and USB, to try to earn a little money.

I’ll be unavaliable over the next four days (Easter break). So if your computer melts down or your USBKEY mugs you in a blind alley due to your use of MyUSB, I won’t be around to hear it for a little while.

Keep those bug reports and feature requests coming!

I’ve just released 1.3.1 of MyUSB, which (as the version number indicates) is just a minor point release. However, it does include a whole boatload of fixes, and one or two convenient new things too. Newly added is the DFU bootloader (the only one outside Atmel, to the best of my knowledge) as well as endpoint interrupt Keyboard and Mouse device demos.

The changelog is as follows:

• Fixed USB to Serial demo - class value in the descriptors was incorrect
• Control endpoint size changed from 64 bytes to 8 bytes to save on USB FIFO RAM and to allow low speed mode devices to enumerate properly
• USB to Serial demo data endpoints changed to dual-banked 16 byte to allow the demo to work on USB AVRs with limited USB FIFO RAM
• Changed demo endpoint numbers to use endpoints 3 and 4 for double banking, to allow limited USB device controller AVRs (AT90USB162, AT90USB82) to function correctly
• Updated Audio Out demo to use timer 1 for AVRs lacking a timer 3 for the PWM output
• Fixed incorrect USB_DEV_OPT_HIGHSPEED entry in the Mass Storage device demo makefile
• Optimized Mass Storage demo for a little extra transfer speed
• Added LED indicators to the Keyboard demo for Caps Lock, Num Lock and Scroll Lock
• Added Endpoint_Read_Stream, Endpoint_Write_Stream, Pipe_Read_Stream and Pipe_Write_Stream functions (including Big and Little Endian variants)
• Made Dataflash functions inline for speed, removed now empty Dataflash.c driver file
• Added new SetSystemClockPrescaler() macro - thanks to Joerg Wunsch
• Fixed Endpoint_ClearStall() to function correctly on full USB controller AVRs (AT90USBXXX6/7)
• Endpoint_Setup_In_Clear() and Endpoint_Setup_Out_Clear() no longer set FIFOCON, in line with the directives in the datasheet
• Fixed PLL prescaler defines for all AVR models and frequencies
• Fixed ENDPOINT_INT_IN and ENDPOINT_INT_OUT definitions
• Added interrupt driven keyboard and mouse device demos
• Combined USB_Device_ClearFeature and USB_Device_SetFeature requests into a single routine for code size savings
• Added missing Pipe_GetCurrentPipe() macro to Pipe.h

This is a bug-fix release, and all current users should update. No migration issues are present in the new library version.

Wiki updates to reflect on the minor changes to follow.

Good news! Finally - after a lot of effort - I’ve managed to do what only Atmel have done so far; complete a working (and FLIP compatible) USB DFU bootloader. Unlike Atmel’s, mine will be completely open source and will be included in the minor 1.3.1 MyUSB release.

Speaking of the new release, it will incorporate quite a few fixes to the library, including patches to make 16MHz USB AVRs work correctly once again. It will also contain fixes to allow low speed devices to enumerate properly and a bunch of other reasonably important patches. Release will be in the next few days, and I will be strongly recommending all users update. Being only a minor release, it will not contain any migration issues.

I’m working on MyUSB 1.3.1, which will be a minor point release to fix a few minor issues in the 1.3.0 release. The demos will be patched so that more of them work on the AT90USBXXX2 AVRs - the 1.3.0 release has several demos which either use more USB FIFO memory than available or used endpoints which don’t support double banking on the smaller reduced device USB AVRs. Also added are some some new Endpoint and Pipe stream read/write functions, which provide a safe API for the exchange of a set amount of bytes stored in a buffer.

I’ll include the unfinished bootloader, just in case anyone else feels like debugging the remaining flash write code and gets it working.

I’m happy to say that my two month old Toshiba Satellite A200/02H now works flawlessly. After one trip to the repair center and a new motherboard later, I was still having the same random “black screen of death” problems which plague the Satellite series laptops. However, a few days ago Toshiba posted a fix in the form of a BIOS update which resolves the issue. Huzzah!

There’s been a bit of confusion concerning the USB Device Descriptors, so I thought I’d do another informational post to clear things up a bit.

All USB devices contain descriptors. These descriptors describe the important aspects of the device to the host, and are read during enumeration so that the appropriate drivers can be loaded for each connected device. There are many types of descriptors, but for basic devices only a few are used; Device Descriptors, Configuration Descriptors, Interface Descriptors and Endpoint Descriptors.

Let’s consider a canned example, that of a USB still camera. Such a camera might have two different USB connection modes; Mass Storage (for drag-drop access like a USB flash disk) and Still Image (for use with supporting camera software). It might also allow the host to use the microphone on the camera, and use the camera element as a low resolution webcam.

We’ll now be designing the descriptors required for such a device, starting with the Device Descriptor.

Device Descriptor
The Device Descriptor is mandatory, and only one is allowed for each USB device. It contains important information about the device, including the manufacturer/product IDs (assigned via USB.org, and provide a unique combination which can identify a device and indicate driver compatibility), Class and Protocol values, total configurations and power requirements.

Some devices (e.g. most Mice and Keyboards) are pretty simple, and only provide one function. These sorts of devices can declare their overall function in the device descriptor’s Class/Protocol values - which should be sourced off the list of defined classes at USB.org - which the host can read. For more complex devices which do not belong to one clear class, these are set as 0×00, which indicates to the host that the classes should be sourced from the interface descriptors of the current configuration.

Descriptors So Far:

• Device Descriptor

Configuration Descriptor
USB devices may have multiple configurations, although these are uncommonly used in practice. Each configuration descriptor completely defines a set of interfaces for the available functions. Configurations are mutually exclusive to one-another; the host may select any one of the configurations at any one time, but cannot use multiple configurations at once.

The Configuration Descriptor contains a set of Interface and Endpoint descriptors, in a flat structure. The actual layout of the configuration descriptor is hierarchical but when transmitted to the host it is sent as a flat datastream.

Our USB camera would have two configurations, one with the Video (camera), Audio (microphone) and Mass Storage features, and another containing Video (camera), Audio (microphone) and Still Image features. As the configurations are separate the common features between configurations need to be repeated inside each independent configuration descriptor.

Descriptors So Far:

• Device Descriptor
• Configuration Descriptor (0)
• Configuration Descriptor (1)

Interface Descriptor
Each device function has one or more interface descriptors associated with it. For example, with our hypothetical USB camera, we would have one interface for the Mass Storage (or Still Image) feature, another for the Video (camera) feature and a third for the Audio (microphone). The interface descriptors indicate the interface’s class and protocol and number of associated endpoints. One other interesting feature of the Interface Descriptors is the Alternate Setting value; like the Configuration descriptor each interface can have multiple entries which can change the interface’s function depending on which one is selected.

Our USB camera will have an alternate setting interface for the audio class; even if a device’s features is not selected, bandwidth is still used by the host for checking the interface’s endpoints. Thus, for audio interfaces (which use up a lot of data), an alternate setting with no endpoints is added so that when the microphone is unused, the host can turn off the endpoint and save on USB bandwidth.

Each interface descriptor will have its Class and Protocol values filled out with the values defined at USB.org for the appropriate functions of each interface.

We’ll assume that the Mass Storage/Still Image class requires two endpoints, and the Video class uses a single endpoint for the purposes of this demonstration.

Descriptors So Far:

• Device Descriptor
• Configuration Descriptor (0)
  • Interface Descriptor (Mass Storage Class, Alternate Settings 0, Alternate Setting 0, 2 Endpoints)
  • Interface Descriptor (Video Class, Alternate Settings 0, Alternate Setting 0, 1 Endpoint)
  • Interface Descriptor (Audio Class, Alternate Settings 1, Alternate Setting 0, 1 Endpoint)
  • Interface Descriptor (Audio Class, Alternate Settings 1, Alternate Setting 1, 0 Endpoints)

• Configuration Descriptor (1)
  • Interface Descriptor (Still Image Class, Alternate Settings 0, Alternate Setting 0, 2 Endpoints)
  • Interface Descriptor (Video Class, Alternate Settings 0, Alternate Setting 0, 1 Endpoint)
  • Interface Descriptor (Audio Class, Alternate Settings 1, Alternate Setting 0, 1 Endpoint)
  • Interface Descriptor (Audio Class, Alternate Settings 1, Alternate Setting 1, 0 Endpoints)

Endpoint Descriptor

Lastly for our simple device, we have the Endpoint Descriptor. Each interface will have 0 or more endpoints, each of which allow for the exchange of data between the device and the host. Each endpoint descriptor indicates the type of endpoint (BULK, CONTROL, INTERRUPT, ISOCHRONOUS), address and (for INTERRUPT endpoints) the polling interval between endpoint interrupts.

Each endpoint must be given a unique address. The value of each address is actually not important, except for the most significant bit, which when set indicates to the host that the endpoint is of the IN type, for sending data from the device into the host. Address 0 is reserved, and is used for the control endpoint that is present on all USB devices for host-device control requests. Endpoint 0 does not need an explicit Endpoint Descriptor — it is mandatory and thus does not need to be described.

We must place each endpoint after the interface to which it belongs. This is how interface-endpoint relationships are established; if an interface declares it has three endpoints, three Endpoint Descriptors must be placed directly after the Interface Descriptor. This is why the address is not important to anything other than the device (which then uses the address to read data in and out of the appropriate endpoints).

Descriptors So Far:

• Device Descriptor
• Configuration Descriptor (0)
  • Interface Descriptor (Mass Storage Class, Alternate Settings 0, Alternate Setting 0, 2 Endpoints)
    • Endpoint Descriptor (BULK, OUT, Address 1, 64 Bytes)
    • Endpoint Descriptor (BULK, IN, Address 2, 64 Bytes)
  • Interface Descriptor (Video Class, Alternate Settings 0, Alternate Setting 0, 1 Endpoint)
    • Endpoint Descriptor (BULK, IN, Address 3, 64 Bytes)
  • Interface Descriptor (Audio Class, Alternate Settings 1, Alternate Setting 0, 1 Endpoint)
    • Endpoint Descriptor (ISOCHRONOUS, IN, Address 4, 128 Bytes)
  • Interface Descriptor (Audio Class, Alternate Settings 1, Alternate Setting 1, 0 Endpoints)

• Configuration Descriptor (1)
  • Interface Descriptor (Still Image Class, Alternate Settings 0, Alternate Setting 0, 2 Endpoints)
    • Endpoint Descriptor (BULK, OUT, Address 1, 64 Bytes)
    • Endpoint Descriptor (BULK, IN, Address 2, 64 Bytes)
  • Interface Descriptor (Video Class, Alternate Settings 0, Alternate Setting 0, 1 Endpoint)
    • Endpoint Descriptor (BULK, IN, Address 3, 64 Bytes)
  • Interface Descriptor (Audio Class, Alternate Settings 1, Alternate Setting 0, 1 Endpoint)
    • Endpoint Descriptor (ISOCHRONOUS, IN, Address 4, 128 Bytes)
  • Interface Descriptor (Audio Class, Alternate Settings 1, Alternate Setting 1, 0 Endpoints)

Putting them all together

Now we have the basic hierarchical structure of our descriptors for our USB camera. We need to flatten them into three structures - one Device, two Configuration. To do that, we just add the items to the struct in the order of the above, with children following parents:

Device Descriptor

Configuration Descriptor (0)

Interface Descriptor (Mass Storage Class, Alternate Settings 0, Alternate Setting 0, 2 Endpoints)
Endpoint Descriptor (BULK, OUT, Address 1, 64 Bytes)
Endpoint Descriptor (BULK, IN, Address 2, 64 Bytes)
Interface Descriptor (Video Class, Alternate Settings 0, Alternate Setting 0, 1 Endpoint)
Endpoint Descriptor (BULK, IN, Address 3, 64 Bytes)
Interface Descriptor (Audio Class, Alternate Settings 1, Alternate Setting 0, 1 Endpoint)
Endpoint Descriptor (ISOCHRONOUS, IN, Address 4, 128 Bytes)
Interface Descriptor (Audio Class, Alternate Settings 1, Alternate Setting 1, 0 Endpoints)

Configuration Descriptor (1)

Interface Descriptor (Still Image Class, Alternate Settings 0, Alternate Setting 0, 2 Endpoints)
Endpoint Descriptor (BULK, OUT, Address 1, 64 Bytes)
Endpoint Descriptor (BULK, IN, Address 2, 64 Bytes)
Interface Descriptor (Video Class, Alternate Settings 0, Alternate Setting 0, 1 Endpoint)
Endpoint Descriptor (BULK, IN, Address 3, 64 Bytes)
Interface Descriptor (Audio Class, Alternate Settings 1, Alternate Setting 0, 1 Endpoint)
Endpoint Descriptor (ISOCHRONOUS, IN, Address 4, 128 Bytes)
Interface Descriptor (Audio Class, Alternate Settings 1, Alternate Setting 1, 0 Endpoints)

Nothing to it. Of course, there are plenty of details about descriptors not covered here, but I just wanted to clear up the general confusion about what to change to create the desired behaviour.

MyUSB 1.3.0, which was released two days ago, is now fully documented in the site wiki. As per the usual procedure with each MyUSB library version release, I’ve created a migration page in the Wiki to aid in the migration of projects based on old library versions to the latest version.

I’ve since discovered a flaw in the USB to Serial converter demonstration sample project, which prevents the correct drivers from being installed. A fix will be uploaded in the next few days, but it can be manually fixed via the following change.

In MyUSB/Demos/USBtoSerial/Descriptors.c, change the value of the class attribute of DeviceDescriptor (first structure in the file) from the value 0x00 to 0x02. This declares the device correctly as being a CDC class device, and allows Windows to use its own drivers for it (once helped along by the INF file located in the USBtoSerial directory).

MyUSB 1.3.0 has now been officially released. The changelog is as follows:

• Unneccesary control endpoint config removed from device mode
• Fixed device standard request interpreter accidentally processing some class-specific requests
• Added USE_RAM_DESCRIPTORS and USE_EEPROM_DESCRIPTORS compile time options to instruct the library to use descriptors stored in RAM or EEPROM rather than flash memory
• All demos now disable watchdog on startup, in case it has been enabled by fuses or the bootloader
• USB_DEV_OPT_LOWSPEED option now works correctly
• Added ability to set the USB options statically for a binary size reduction via the USE_STATIC_OPTIONS compile time define
• USB_Init no longer takes a Mode parameter if compiled for a USB device with no host mode option, or if forced to a particular mode via the USB_HOST_ONLY or USB_DEVICE_ONLY compile time options
• USB_Init no longer takes an Options parameter if options statically configured by USE_STATIC_OPTIONS
• Endpoint_Ignore_* and Pipe_Ignore_* made smaller by making the dummy variable non-volatile so that the compiler can throw away the result more efficiently
• Added in an optional GroupID value to each scheduler entry, so that groups of tasks can once again be controlled by the new Scheduler_SetGroupTaskMode() routine
• Added support for AT90USB162 and AT90USB82 AVR models
• Added support for the STK525 and STK526 boards
• Added support for custom board drivers to be supplied by selecting the board type as BOARD_USER, and placing board drivers in <APP DIRECTORY>/Board/
• PLL is now stopped and USB clock is frozen when detatched from host in device mode, to save power
• Joystick defines are now in synch with the schematics - orientation will be rotated for the USBKEY
• Fixed USB_DEV_IsUSBSuspended() - now checks the correct register
• Fixed data transfers to devices when in host mode
• Renamed USB_DEV_OPT_HIGHSPEED to USB_DEV_OPT_FULLSPEED and USB_HOST_IsDeviceHighSpeed() to USB_HOST_IsDeviceFullSpeed() to be in line with the official USB speed names (to avoid confusion with the real high speed mode, which is unavaliable on the USB AVRs)

I’m really excited about this release - it contains many new features and expands the scope of the library to all the current AVR USB models and Atmel USB development boards. It also contains quite a few breaking changes, which I’ll be documenting ASAP; expect Wiki updates very soon.

As indicated by previous posts, the Still Image Host and new DFU Bootloader are not included in this release. The DFU bootloader is very near completion however, with much progress in the last 24 hours.

I’d like to publically thank all those who have tested this release for me, providing invaluable support. KMR, CHirst, Prime and other members of AVRFreaks, and those who have provided reports via email.

Lastly, thank you to all those who have contacted me regarding the library. Whether it’s just a friendly email stating who you are and how you’re planning on using it, bug reports or feature requests, I appreciate all the feedback and it motivates me to continue my work. A BIG thanks to all who have donated financially to me — your support funds future development and new projects.

I’m now moving MyUSB 1.3.0 to the status of a public pre-release for further beta testing. The new code can be downloaded here:

http://fourwalledcubicle.com/files/MyUSB%201.3.0%20PRERELEASE.zip

The Still Image Host demo and Bootloader are unfinished, and will *not* be present in the official 1.3.0 release. This new code contains several changes (see SCRATCHPAD.txt and ChangeLog.txt) which enhance the library, but break projects which use other library versions. These haven’t been documented yet, but the demos and the two mentioned text files should assist in the porting of older code over to the new library.

All the demos can now be built for the USBKEY, STK525, STK526 or for a user-supplied board. It should also compile across the full AT90USBXXX range, including the new USB82 and USB162 AVRs. Please notify me of any problems you encounter, so they can be fixed before the full release scheduled for Friday night.