Memos From the Cube

Ok, let me begin with a quick question. Suppose you’re designing a USB peripheral for a PC, and are using Windows to test it out. Now, the development process is fairly lengthy, so you’ll be writing and testing in stages to see how each module performs.

Right. Now assume you’re writing a USB Mass Storage device. You’re not sure how much of it is working. What would you expect Windows to do when it sees something is amiss during the device enumeration?

If you answered “pop up a detailed error report”, you’d be wrong. Totally wrong, in fact. The best Windows can do is - if you’re lucky - eventually pop up with a balloon saying that the device could not be enumerated “because it has a problem”. Extremely helpful. If you’re unlucky, Windows will just sit there with the device installation balloon frozen on the last device interface it tried to instantiate.

Now, for the million dollar question. What would you expect Windows to do once it realizes that the disk portion of the device has a problem? The answer, of course, is this:

Yes, that’s right. A faulty USB mass storage device triggers a blue screen of death. Apparently a balloon just isn’t good enough for a system calamity of this magnitude. I hope that won’t be a regular occurrence during the development period.

Despite the above setbacks, the Mass Storage Demo code is coming along reasonably well despite the SCSI standards body doing their best to make the standards as obtuse as possible. I’ve implemented only three commands so far, but at least I’m getting somewhere.

As promised, I managed to finish the USB-Serial CDC example for the MyUSB project yesterday, with the new code uploaded. I urge all current MyUSB users (I know you’re out there, somewhere!) to re-download the latest library version. It’s a drag-drop affair - simply replace your existing MyUSB library folder with the latest one and you’ll get all the new code improvements with no compatibility issues.

Today I spent a little while trying to implement the Mass-Storage class into a new demo. That’s partially complete, with the Bulk-Only transport code done, with the SCSI decoder and dataflash driver remaining to write. During the coding of the Bulk-Only implementation I realized I had made some errors in the GetFeature and ClearFeature standard device command requests, which I’ve since corrected - so please update your library version!

Finding the correct SCSI document outlining the different commands has been a nightmare, but I think I now have the correct one. It looks quite daunting to be honest, so I’m going to start with the dataflash driver first and worry about the SCSI transport decoder last. The dataflash driver, after much internal deliberation, will be designed specifically for the dataflash used in the USBKEY - this helps keep the code as tight as possible. I may provide a generic driver at a later date, capable of addressing all the dataflash members of a single dataflash family.

Also done today was proper testing of the Mouse Host example. I’ve had issues in the past with the current draw from the peripherals causing VBUS dips, resulting in the inability to fully test the host examples. I’ve now managed to shoe-horn my regulated 12V power supply into the board, saving my unregulated 12V supply to power the STK500, which is currently itself powering my DB101 board for diagnostics.

Having a proper power supply hilighted an issue with the mouse example; while my USB keyboard would work without a hitch (obviously throwing a “invalid protocol” error when used with the mouse host example) plugging in a mouse would cause continuous device connections and disconnections. Further debugging showed that the host state machine was erroring out when performing the 100ms delay after creating the host control pipe to suit the peripheral. Oddly enough, the mouse was returning a STALL request in response to nothing more than the generation of the USB frames, with no control data being sent.

Fixing the problem just became a matter of ignoring the error condition of the 100ms wait command after the host control pipe creation. I’ve no idea of the reason behind the stall, but my solution fixes the problem perfectly.

Eventually, once the mass-storage code is finished, I will be re-visiting the host demos, and flesh them out some more. Currently much of the device implementation is assumed, rather than being determined by the returned device descriptors. I want to eventually code in a host API specifically designed to manipulate the returned descriptors from a device.

If anyone has a list of the valid standard SCSI commands in a formatted and collated electronic form, I’d love to hear from you. Re-typing all the commands and command codes from the SCSI specification I have looks to be quite tedious and time consuming.

Lastly, to make the library more complete, I’ve implemented support for multiple configurations. This removes the very last of the hard-coded values in the library which couldn’t be altered in the end-application - now a device may have more than one configuration, with the appropriate configuration descriptor being returned according to the given index.

Thanks to a member of AVRFreaks, “mojojojo“, who pointed me in the right direction in the CDC specification, the MyUSB library now comes with a working CDC demonstration application. The demo is a simple one, emulating a serial port on the host and transmitting strings as the joystick is moved on the USBKEY board.

I’m now working on extending the CDC demo code to include a USB-Serial converter. That won’t take too much time - I will need to buffer both the physical serial port and the virtual serial ports, and write routines to exchange bytes between them. Hopefully I’ll have the completed USB-Serial code done by tomorrow, so remember to keep checking back!

Currently, the MyUSB library contains the following demonstration applications:

Device:

Basic two button Mouse

Basic five button Keyboard

Basic two button Joystick

Magnetic Stipe Card Reader (based on Keyboard example)

CDC Example

CDC USB-Serial Converter (unfinished)

Host:

Basic mouse host

Basic keyboard host

Combination:

Test application demonstrating the non-USB library portions, as well as a USB device capable of acting as a device or host

I’ve got a new MyUSB device in the download package, a Joystick example. Of course, being limited by the hardware of the USBKEY board, the function of the demo is rather limited (two button, and the joystick movement is digital rather than analogue) but serviceable as an example.

Here’s what the current ground-zero looks like:

Note the shiny new PoScope in the upper-left hand corner! Very cool.

I’m currently looking for people experience with the CDC USB profile to help me make a virtual COM port example. The official documentation is VERY large and dry, so I’d like someone who knows what they’re doing to give me a few pointers on what parts of the CDC specification I need to implement to get the virtual COM port up-and-running.

Of course, if you have made a project with MyUSB, I’d still like the hear from you. Photos appreciated!

Today marked my end of University exams, with my Physics For Engineers exam being my final one for the year. I’m officially free of all duties for the next three months, and it feels great!

One whole year of University down, four more to go. Boy, this year has really flew by!

Now’s the time to get to doing the things that I actually want to do - work on my projects, help out with the AVR-GCC/avr-lib-c projects, find some work and earn some money, write more tutorials and get my learner’s permit for learning to drive. Tally-ho!

Hurrah! Today, after much swearing and reverse engineering, I managed to get a USB keyboard to enumerate via MyUSB, and print out the typed alpha-numerical letters onto the display. It’s still not quite done, with a few more refinements left to do, but at least it works at all.

The mouse host code may or may not work - I lack a 9V battery which has enough oomph to power the mouse. Once I get a 6-AA to 9V adapter I should have plenty of power for testing devices.

As usual, I couldn’t have got it working at all without the reference Atmel driver to study. I’ve had lots of trouble trying to get the algorithm right, and was only illuminated on thi occasion after I had a look at Atmel’s driver. It turns out that after each control transfer, the FIFOCON bit must be cleared to reset the pipe’s buffer. That’s the exact opposite of the datasheet, which states that the FIFOCON bit should not be altered by a control pipe. Little things like that make me wish very hard for a final version of the USB1287’s datasheet, so I have a correct, concrete reference to guide me.

Finally, I’ve done it. And about time, too. MyUSB can now successfully enumerate and address my USB Keyboard, acting as a USB Host.

That’s exciting news (to me at least) as it’s a decent milestone towards getting the library complete. The host code isn’t finished by any stretch of the imagination - bugs to fix, and the API to flesh out. Lots of things are still missing, like data stages for USB control requests, and a good API for reading out data from the pipe. Still, I can now talk to the keyboard correctly, which is what I was setting out to do.

The first USB host demonstration application, which I’m currently working on, is a USB mouse host. Similar to the official Atmel demo program, it will enable the user to plug in a USB mouse, and have the mouse movement/button presses shown on the two bicolour LEDs of the USBKEY board.

Only two more days to go, before I have my last Physics exam on Tuesday. I’ll be quite relieved to have them all out of the way, so I have free time to finish MyUSB. As always, stay tuned for project updates!

Halfway through exams now, with three to go. Tomorrow brings a Java exam, Friday a C/C++ and Tuesday sports a Physics exam. I’m very shaky on the latter, so I’m doing a lot of studying up this week.

Some happy news. Thanks to a rather generous soul, Adam Eberbach, who rather liked my tutorials I wrote about AVRs, I’ll soon be the proud owner of a PoScope. It’s no replacement for a real high-bandwith scope, but it’s neat none-the-less. It’s suitable for audio-signal analysis, but also (what I’m really looking forward to) for logic analysis at 8MHz. I’d tossed up previously between trying to get a logic analyzer and trying to get a scope, but this way I’ll be able to have my cake and analyze it too.

Denver Gingerich, the man behind the MyUSB keyboard demo, has sent me a new patch for a magnetic stripe card reader. It’s now included in the MyUSB source code. Built on the keyboard demo, the project enumerates as a standard USB keyboard, and transmits read card data as a 1-0 ASCII stream over to the computer. He’s also got a nice support page set up for it, located here. Oh, and a blog post about it, too.

I’m slowly working on the host code. I’ve been fixing a number of bugs with the library, and currently the plugged-in device is just returning a USB Setup Stall request in response to my GetDescriptor control request. Further work is needed to debug the problem and get the code working. Still, at least it is being worked on. Stay tuned!

I’m a busy little bee. Along with some rain in my drought-stricken country of Australia comes a few big changes to MyUSB.

First up, the Java helper applications have been deleted. I originally wrote the apps in Java for cross-compatibility, but as Denver Gingerich (man behind the Keyboard demo application) pointed out, not everyone *has* Java.

However, one thing that everyone should have is an installation of WinAVR, or a Unix shell. Denver was kind enough to help me out with a few of Unix’s tools that I’ve not had much experience in, and the new solution is a single (if complex) line in the makefile completely replacing the Java monstrosity I had coded up.

But that’s not all. I’ve finally got around to properly separating the device and host portions of the library. You can now omit the compiling of the host-specific files when only using the device mode, and vice-versa. The selection of what parts to include is done by two new macros, which are passed to each file as it is compiled in the makefile via AVR-GCC’s -D switch. Passing USB_DEVICE_ONLY when compiling will remove all host-related code, and USB_HOST_ONLY will do the same for the device code (not passing either enables both as was the previous behavior). Everything still works the same unless the USB system is initialized into a mode that has not been compiled in, whereupon the power on error event will fire with a POWERON_ERROR_UnavailableUSBModeSpecified error code.

The MyUSB keyboard and host demo applications now pass in USB_DEVICE_ONLY on the command line, which currently saves a little over a kilobyte of space in the final binary.

The side-effect of seperating the library components is that when one of the USB_X_ONLY tokens are defined, only the events applicable to that mode are available. That removes the noise from the unhooked events output on the build output.

This morning I completed my first end-of-year exam, my Math for Engineers paper. Three hours of tedious matrix multiplication, probability distributions and the solving of several types of differential equations. I’m glad that’s over!

With the completion of my first exam comes a new update to the MyUSB codebase, which now includes Denver Gingerich’s keyboard demonstration application. I’ve also fixed a number of bugs, which means the code is even better than before. After exams have completed I’ll get back to the host code (which requires a lot of effort and time), rather than just the small bug-fixes, restructuring and additions I’m doing now. Despite the limited time I have, I think I’ve accomplished quite a lot in the past week or so, with the new event system and the decoupling of the library from the end-application.

Once again, if you’ve been using MyUSB I’d love to hear from you!

I’d also like to publicly thank Christian of Object Development for being such a good sport about letting Denver’s keyboard demo copy the keyboard USB report descriptor he made. There’s a great firmware-only USB driver (for AVRs lacking the inbuilt USB controller which MyUSB requires) over on the Object Development website, which I highly recommend to those who aren’t using the AT90USB series AVRs and thus can’t use MyUSB.