2011-03-24

Error 800B0003 - The form specified for the subject is not one supported or known by the specified trust provider

You're trying to digitally sign a file, aren't you?
And until this post, you weren't aware that only a specific set of files, such as executables, DLLs or cat files could be signed on Windows, but that random blurb, such as text files couldn't.

Well, now you know. If you see this error, it simply means that Windows does not recognize the input file as something it is able to affix a digital signature on.

2011-03-21

Programatically setting and applying Local Group Policies on Windows

One of the most annoying aspects of device driver installation on Windows, and one of the main gripe people are expected to have with the current libwdi (which has since been fixed programmatically using the technique exposed below), is the Windows default of creating a system restore point each time it installs a new driver. Having seen restore point creations that take more than 5 minutes, and ending up in failure as a result, since 5 minutes is the default timeout for a point creation, I have been looking at ways to change this default behaviour.

Enters the Local Group Policy. If you're lucky enough to run a version of Windows that enables it, you might be aware of the gpedit mmc tool (launch the command gpedit.msc to access it), which can be used to alter various Windows settings, a.k.a. Group Policies. In general, Group Policies are settings that are applied by Active Directory administrators in a networked environment, but the non networked part, called Local Group Policy can also be used by the end users to control the behaviour of their local machine or user account, should the network administrator decide not to override those. Of special interest to us is the Administrative Templates → System → Device Installation → "Prevent creation of a system restore point during device activity..." setting, which you can access after launching gpedit.msc. It works, and is exactly what we have been looking for.

But then again, we don't want to rely on end users to change this setting themselves, especially if they are running the Basic or Home edition of Windows 7 or Vista where gpedit is not available. We want to do it programmatically.

If you use the RegFormApp tool from NirSoft, to monitor what gpedit actually does when enabling this setting, you find that it simply creates a new DisableSystemRestore DWORD in the registry at:
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Group Policy Objects\{<some-guid>}Machine\Software\Policies\Microsoft\Windows\DeviceInstall\Settings

Brilliant. The much decried Registry might actually prove its worth, if all you have to do to toggle system restore point creation on driver installation, is modify a key there... except, we're talking about a Microsoft way of implementing a solution, and it would be way too simple if Windows' own Local Group Policy settings were stored in the registry. The key created by gpedit there is in fact useless for the programmer, because it's just a some temporary storage for gpedit and not at all where the system looks when deciding whether it should create a restore point. As a matter of fact, the GUID changes every time you run gpedit.

So now we need to figure out a way to set our Local Group Policy programmatically, as gpedit does, and you can trust that it's not going to be as simple as what we were hoping for. Thankfully, if you look hard enough, you may end up on the Microsoft's USGCB Tech Blog page dealing with Utilities for automating Local Group Policy management. These tools are precisely the kind of sample we are looking for, as the ImportRegPol there can pick up a .pol file and apply the LPGO associated with it, and they come with the source.

To cut a long story short, you will need to use an IGroupPolicyObject Interface object, and below is the C source (with no error checking whatsoever) that one can use to disable the creation of a restore point during driver installation on Windows Vista and Windows 7:
#include <gpedit.h>

DWORD val, val_size=sizeof(DWORD);
HRESULT hr;
IGroupPolicyObject* pLGPO;
HKEY machine_key, dsrkey;
// MSVC is finicky about these ones => redefine them
const IID my_IID_IGroupPolicyObject = 
 { 0xea502723, 0xa23d, 0x11d1, {0xa7, 0xd3, 0x0, 0x0, 0xf8, 0x75, 0x71, 0xe3} };
const IID my_CLSID_GroupPolicyObject = 
 { 0xea502722, 0xa23d, 0x11d1, {0xa7, 0xd3, 0x0, 0x0, 0xf8, 0x75, 0x71, 0xe3} };
GUID ext_guid = REGISTRY_EXTENSION_GUID;
// This next one can be any GUID you want
GUID snap_guid = { 0x3d271cfc, 0x2bc6, 0x4ac2, {0xb6, 0x33, 0x3b, 0xdf, 0xf5, 0xbd, 0xab, 0x2a} };

// Create an instance of the IGroupPolicyObject class
CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);
CoCreateInstance(&my_CLSID_GroupPolicyObject, NULL, CLSCTX_INPROC_SERVER,
 &my_IID_IGroupPolicyObject, (LPVOID*)&pLGPO);

// We need the machine LGPO (if C++, no need to go through the lpVtbl table)
pLGPO->lpVtbl->OpenLocalMachineGPO(pLGPO, GPO_OPEN_LOAD_REGISTRY);
pLGPO->lpVtbl->GetRegistryKey(pLGPO, GPO_SECTION_MACHINE, &machine_key);

// The disable System Restore is a DWORD value of Policies\Microsoft\Windows\DeviceInstall\Settings
RegCreateKeyEx(machine_key, "Software\\Policies\\Microsoft\\Windows\\DeviceInstall\\Settings",
 0, NULL, 0, KEY_SET_VALUE | KEY_QUERY_VALUE, NULL, &dsrkey, NULL);
 
// Create the value
val = 1;
RegSetKeyValue(dsrkey, NULL, "DisableSystemRestore", REG_DWORD, &val, sizeof(val));
RegCloseKey(dsrkey);

// Apply policy and free resources
pLGPO->lpVtbl->Save(pLGPO, TRUE, TRUE, &ext_guid, &snap_guid);
RegCloseKey(machine_key);
pLGPO->lpVtbl->Release(pLGPO);
Disabling of system restore during driver installation - coming soon to a libwdi powered application near you!

2011-03-15

AVR development with LUFA - TILTHW

  1. If you're going to switch between .USBSpecification = VERSION_BCD(01.10) and .USBSpecification = VERSION_BCD(02.00) and you're using a specific Windows driver (i.e. not HID, Mass Storage, etc.), then your device will only get installed properly until you reinstall that driver. Windows does not like having the USB specs of an existing device changed.

  2. The API changes quite a lot from release to release. Some would make a big deal out of it, but it really isn't. Just be careful that if you see an old LUFA guide, some of its calls might be obsolete. For instance some calls like EVENT_USB_Device_UnhandledControlRequest have been obsoleted.

  3. Stream serial debug output (printf) is easy once
    • you use the following in your source:
      #include <LUFA/Drivers/Peripheral/Serial.h>
      (...)
          Serial_Init(115200, true);
          Serial_CreateStream(NULL);
    • you make sure that $(LUFA_SRC_SERIAL) is referenced in your makefile sources (SRC = ...) along with $(LUFA_SRC_USB), as it is not included automatically.

  4. If you're getting undefined references to Endpoint_Read_Stream_LE and friends, you probably have LUFA_OPTS += -D CONTROL_ONLY_DEVICE defined in your makefile. Comment it out.

  5. On an AVR90USB162, there's only so much space that can be used for printf strings apparently, regardless of how much flash is being used. If you have too many serial debug statements, you may find that serial output is garbled until you eliminate some of them. Make sure you only use serial debug sparingly.

  6. EVENT_USB_Device_ConfigurationChanged() is NOT a good place to do serial debug output statement.

  7. If you are using multiple interfaces on Windows, you DO want to add a delay in EVENT_USB_Device_ConfigurationChanged()

  8. Use NULL as last parameter in the EP R/W calls (eg. Endpoint_Read_Stream_LE), unless you want to open a big bag of hurt!

  9. If you're using the same endpoint number for IN and OUT (eg. 0x01 & 0x81), you need to use Endpoint_SetEndpointDirection() to toggle the direction after selecting the EP. Oh, and don't use ENDPOINT_DESCRIPTOR_DIR_IN or ENDPOINT_DESCRIPTOR_DIR_OUT, use ENDPOINT_DIR_IN and ENDPOINT_DIR_OUT instead.

2011-03-14

Thunderbird and inline patch attachments

If you're running Thunderbird, depending on how you ever dealt with some types of attachments in the past, there is a chance that, according to how you told Thunderbird to handle some of the types of attachments, you now get an undesirable attachment behaviour.

For instance, if you ever told Thunderbird how it should open a .patch file (eg. with TortoiseGit), you might find that, patches you send are no longer sent as inline text (text/plain), but instead are sent as non-inline (application/force-download). This can be a problem for people reading those patches with dumb e-mail clients, so you might be looking for a way to restore the inline behaviour.

Well, this is usually all handled in the mimeTypes.rdf in your profile. For instance, to get a .patch file to always be sent as inline, you could ensure that you have the following entry:
  <RDF:Description RDF:about="urn:mimetype:text/plain"
                   NC:fileExtensions="patch"
                   NC:description="Patch File"
                   NC:value="text/plain"
                   NC:editable="true">
    <NC:handlerProp RDF:resource="urn:mimetype:handler:text/plain"/>
  </RDF:Description>

In case this isn't enough, another parameter which you want to check is Tools → Advanced → Options → General Tab → Config Editor and then look for mail.content_disposition_type. From what I understand, a value of 0 means that, anything that is not overridden in mimeTypes.rdf will be sent as inline. A value of 1 means that everything is sent as attachment, and a value of 2 means that everything, except images, is sent as attachment, so you probably want to have 0 there.

2011-03-13

Troubleshooting USB device development...

...or how I learned to stop worrying and love Windows' Code 10 ("This device cannot start.")

Let's face it, when it comes to USB device development, the USB stack on Windows is a lot more unforgiving than its Linux counterpart. Now, the problem of course is, Windows being Windows, it does its hardest at hiding what the technical details of a problem are, but instead will spew generic error codes that are only just a notch above useless.

Today's error: the dreaded "This device cannot start. (Code 10)" from the device manager (or CM_PROB_FAILED_START if you're using a WDK related app)  whenever it sees an USB device that it doesn't like. As Tim Roberts puts it here,
CM_PROB_FAILED_START means that your driver loaded, passed through DriverEntry, passed through AddDevice, and then failed during IRP_MN_START_DEVICE.
In layman's terms, this means that the issue occurs during the USB transfers that Windows issues with the device, after the driver has been setup and the device instance has been (re)created. Indeed, Windows does not simply stop communicating with the USB device once it's been instantiated internally; there are a few additional commands that are issued, such as retrieving the String Descriptors, as well setting the Configuration or setting the interface, if Alt Interfaces are provided. Officially of course, Windows does not offer a user API to control the latter, but it still needs to issue these control commands to the device, in order to place it in a known state. And if your device firmware is improperly setup (eg. stalls on any of these commands), Windows will fail the device altogether.

So now of course the question becomes, how can I tell if any of the later Control Transfers are failing?


LogMan and NetMon

To do that, you want an USB analyzer (or you can try the USB consortium's USB Command Verifier, however, despite asking for $2000 a pop for a VID, the USB IF are cheapskate enough not to provide an app that comes with signed Windows drivers, so you have to run a pretty intrusive EHCI driver in test mode). If you're on a 64 bit system, or a recent version of Windows, and you want a free solution, this can be problematic, as SnoopyPro doesn't seem to work that well there. However, in recent versions of Windows, you can get some decent snooping of the USB transfers through NetMon and the CodePlex USB Parsers. The whole process is detailed in this post.

Once you have these tools, run the following from an elevated command prompt to start a trace (NB: you can dump hub traffic as well, as per the Microsoft post, but if you're troubleshooting a standard USB device, you probably don't care much about that part):
Logman start Usbtrace -p Microsoft-Windows-USB-USBPORT -ets -nb 128 640 -bs 128 -o dump.etl
Then just plug in your device, so that you get the Code 10 / CM_PROB_FAILED_START error, and then stop the trace with:
Logman stop Usbtrace -ets


Analysing the trace

And now you have a trace in NetMon. Now what? Well, a couple of things.
First, you might want to isolate the Control Transfers that deal with your device only. If you're using a device with VID 0x1234, this can be done as follows (There's probably a way to simplify this - haven't found it yet...):
USBPort.USBPORT_ETW_EVENT_DEVICE_INITIALIZE.fid_USBPORT_Device.idVendor == 0x1234 OR
USBPort.USBPORT_ETW_EVENT_DISPATCH_URB_FUNCTION_CONTROL_TRANSFER.fid_USBPORT_Device.idVendor == 0x1234 OR
USBPort.USBPORT_ETW_EVENT_COMPLETE_URB_FUNCTION_CONTROL_TRANSFER_DATA.fid_USBPORT_Device.idVendor == 0x1234 OR
USBPort.USBPORT_ETW_EVENT_DISPATCH_URB_FUNCTION_CONTROL_TRANSFER_EX.fid_USBPORT_Device.idVendor == 0x1234 OR
USBPort.USBPORT_ETW_EVENT_COMPLETE_URB_FUNCTION_CONTROL_TRANSFER_EX_DATA.fid_USBPORT_Device.idVendor == 0x1234 OR
USBPort.USBPORT_ETW_EVENT_COMPLETE_INTERNAL_URB_FUNCTION_CONTROL_TRANSFER.fid_USBPORT_Device.idVendor == 0x1234 OR
USBPort.USBPORT_ETW_EVENT_ENDPOINT_OPEN.fid_USBPORT_Device.idVendor == 0x1234
That's better. But more importantly, you want to check for errors, which could be done like this for a Pipe Stall:

USBPort.USBPORT_ETW_EVENT_COMPLETE_INTERNAL_URB_FUNCTION_CONTROL_TRANSFER.ControlTransfer.Urb.fid_URB_Hdr_Status == 0xc0000004

Or by the much more generic error filter from Load Filters -> Standard Filters -> USB -> USB Error Events, which translates to the following:
(USBPort AND NetEvent.Header.Descriptor.Opcode == 34) OR
(USBHub AND NetEvent.Header.Descriptor.Opcode == 11) OR
(NetEvent.Header.Descriptor.Level == 0x2) OR
(USBHub AND NetEvent.Header.Descriptor.Id == 210) OR
(Property.USBUrbStatus != "success" && Property.USBUrbStatus != "")

If you're lucky, then you might find that your device has raised something like USBD_STATUS_STALL_PID during one of the post Device_Initialize Control transfers. If so, then you're halfway there: find the corresponding section of code in your firmware, fix it, and Windows should be a lot happier about your device...

2011-03-11

Atmel AVR USB - Using LUFA with the AVR Studio 5 IDE

OK, so now we have our working makefile that builds our LUFA app using nothing but a DOS prompt and the AVR Studio 5 toolchain.

But how about being able to do both the development and compilation from the AVR Studio UI, to have something that resembles a serious development environment at last?

Supposedly the only step, since Atmel were kind enough to provide a conversion tool in AVRS5, is to convert the .aps file we got from LUFA and use the result. I'm still going to use the Joystick demo from the previous post to demonstrate that, since its makefile was fixed to work with AVRS5.


idiotic idiosyncrasies

So File -> Import AVR Studio 4 Project, then browse to the Demos\Device\ClassDriver\Joystick\Joystick.aps.
Now, if you don't select the right directory, Microsoft (this one's an MS idiotic idiosyncrasy, as they do the same in regular Visual Studio) will duplicate the files into a new location, instead of simply reusing the existing one. There's enough data duplication in the world already, so let's avoid that. The original source location is the location we want to use for the project.
So you thought that selecting the Demos\Device\ClassDriver\Joystick\ directory for the Solution Folder would do the trick? Wrong. Whatever you pick, Microsoft will create an extra subdirectory using the solution name in there, so if you use Demos\Device\ClassDriver\Joystick\, all the files will be duplicated into Demos\Device\ClassDriver\Joystick\Joystick\.
No bother then, you say, I'll just use Demos\Device\ClassDriver\ and AVR Studio will then pick up the existing Joystick\ directory and reuse the original files... My young little Padawan, you have a lot to learn about how people are hell bent on making sure convenience is unreachable in this world!

If you try that, you'll get the error:
Project Import Failed : The process cannot access the file 'D:\lufa-lib\Demos\Device\ClassDriver\Joystick\makefile' because it is being used by another process. [Activity : Converting AVR Studio 4 ExternalMakeFileSettings]

Yup, the whole process fails because the file that the process wants to modify is being accessed by the process itself. The thing is, either Atmel or MS is so adamant about duplicating files all over the place, for no good reason, that they haven't considered this really wild idea that someone would ever want not to duplicate the bloody file, and therefore fail to consider that if source and dest are the same, they shouldn't try to copy the files. This is so utterly idiotic!

The workaround? Actually use Demos\Device\ClassDriver\Joystick\ for the Solution Folder, so that the files are duplicated into a Joystick\ subdirectory, close AVR Studio, move the Joystick.avrgccproj file from Joystick\Joystick\ to Joystick\, and then manually edit the Joystick.avrsln file with a text editor and replace the "Joystick\Joystick.avrgccproj" reference there with "Joystick.avrgccproj".
Then delete the Joystick\ subdirectory, and you should be set as Nature (but not Microsoft) intended, i.e. with all of the solution, the project files and the source in the same single directory.

Once you've done that, you should be able to open your LUFA solution and get it to compile straight from AVRS5. Neat!

The only small issue that seems to exist is that when issuing "Rebuild Solution" in AVRS5, which calls "make clean all" behind the scenes, we run into the "opening dependency file .dep/Joystick.o.d: No such file or directory" error again. This seems to be a makefile issue, with the -include $(shell mkdir .dep) $(wildcard .dep/*) line being executed before the clean command, and thus not being able to re-create the .dep\ directory.

Atmel AVR USB - Starting with LUFA, using AVR Studio 5 and the commandline

That's right, we're going to do it the hard way (i.e. sans WinAVR) because we like it better when things don't work straight out of the box. If you don't want to patch stuff, just download WinAVR and be done with it.


I for one welcome our new LUFA overlords

LUFA is so easy to get started with (at least when using WinAVR), it should almost be illegal. I wish libusb would get there, but given our slow rate of getting anything that is convenient for users actually integrated, I doubt we ever will... Anyway, first order of the day is to get the latest LUFA, which we'll pick from SVN. Or you can just pick the latest zip archive from the official website but if you're using LUFA_101122 or earlier, please be aware that there is a bug with the Minimus implementation with regards to the HWB button. To clone from SVN, just have a look here.

Now, the interesting thing of course is, if you look in LUFA\Drivers\Board, you'll see that there is a MINIMUS directory. That means our current test board is supported straight out of the box. Yay!

There are a bunch of demos and projects as well, which is also where you measure the usefulness of a library (once again, unlike libusb, which chose to remove proposed samples, despite having a very limited supply of 'em included...). To test LUFA with the Minimus, we're going to pick the Joystick demo from Demos\Device\ClassDriver. Of course, we don't have a joystick on our board, and just one usable button, so that'll be a pretty limited "joystick", but Windows should still list the device, and if everything works as expected, we should be able to see our button presses in real-time in Windows device properties, so it's not that bad of a trade-off.


Minimus's minimal reconfiguration

The way you set things up for your target board in LUFA is by editing the relevant variables at the top of the makefile. If you go to the Demos\Device\ClassDriver\Joystick directory, you'll see that, apart from the source, you only have one makefile as well as Joystick.aps, which is the AVR Studio 4 project file that actually calls the makefile for compilation.

There's only very little we need to modify here. If you're using a Minimus board, here's what you want:
# MCU name
MCU = at90usb162

# Target architecture (see library "Board Types" documentation).
ARCH = AVR8

# Target board
BOARD = MINIMUS

# Processor frequency.
F_CPU = 16000000


Compiling with AVR Studio 5 from the commandline

As pointed out earlier, we're not going to install WinAVR, because that would be too easy. We got a perfectly good avr-gcc toolchain installed with AVR Studio 5, so we might as well use it. Oh, and we're not going to use the AVR Studio 4 → AVR Studio 5 conversion process on the .aps just yet, because:
  1. You might be interested in using AVR Studio 5 for compilation outside of the GUI
  2. We will run into issues with the default makefile, that are better fixed first from the commandline, before moving to AVR Studio
Using AVR Studio from DOS prompt is actually very easy. You just need to add the following to your PATH System environmental variable (provided you used the default path during AVR Studio installation:
C:\Program Files (x86)\Atmel\AVR Studio 5.0\extensions\Application\AVR Toolchain\bin;
Once that's done, just open a prompt and navigate to the Joystick directory. Then run make, and...
D:\lufa-lib\Demos\Device\ClassDriver\Joystick>make
The system cannot find the path specified.
The system cannot find the path specified.
ECHO is off.
-------- begin --------
avr-gcc (AVR_8_bit_GNU_Toolchain_3.2.0_253) 4.5.1
Copyright (C) 2010 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

The system cannot find the path specified.
The system cannot find the path specified.
-f was unexpected at this time.
make: *** [sizebefore] Error 255
Dang!

I'll just cut to the chase here:
The "The system cannot find the path specified." occur whenever a "/dev/null" redirection is done in the Makefile. As to the "-f was unexpected at this time" (now, aren't you glad you found this blog), it occurs from the if test -f $(TARGET).elf statement that is done in "sizebefore:". That's right Dorothy, we're not using a UNIX shell anymore...
A quick glance at the "sizebefore:" and "sizeafter:" statements tell us that they're completely optional. So let's just remove them, which means that you must change the line:
# Default target.
all: begin gccversion sizebefore build sizeafter end
into:
# Default target.
all: begin gccversion build end
As well as remove these references in the:
# Listing of phony targets.
.PHONY : all begin finish end sizebefore sizeafter gccversion \
section at the end of the file.


The Joystick's in the mind, man...

Let's try that again, shall we?
D:\lufa-lib\Demos\Device\ClassDriver\Joystick>make
The system cannot find the path specified.
The system cannot find the path specified.
ECHO is off.
-------- begin --------
avr-gcc (AVR_8_bit_GNU_Toolchain_3.2.0_253) 4.5.1
Copyright (C) 2010 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

The system cannot find the path specified.
The system cannot find the path specified.
-f was unexpected at this time.
make: *** [sizebefore] Error 255

D:\lufa-lib\Demos\Device\ClassDriver\Joystick>make
The system cannot find the path specified.
The system cannot find the path specified.
ECHO is off.
-------- begin --------
avr-gcc (AVR_8_bit_GNU_Toolchain_3.2.0_253) 4.5.1
Copyright (C) 2010 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

ECHO is off.
Compiling C: Joystick.c
avr-gcc -c -mmcu=at90usb162 -I. -gdwarf-2 -DF_CPU=16000000UL -DF_CLOCK=16000000UL -DBOARD=BOARD_MINIMUS -DARCH=ARCH_AVR8 -D USB_DEVICE_ONLY -D FIXED_CONTROL_ENDPOINT_SIZE=8 -D FIXED_NUM_CONFIGURATIONS=1 -D USE_FLASH_DESCRIPTORS -D USE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=./Joystick.lst -I../../../../ -std=c99 -MMD -MP -MF .dep/Joystick.o.d Joystick.c -o Joystick.o
In file included from Joystick.h:49:0,
                 from Joystick.c:37:
../../../../LUFA/Drivers/Board/Joystick.h:120:31: fatal error: Board/Joystick.h: No such file or directory
compilation terminated.
make: *** [Joystick.o] Error 1

That's a bit better. But yeah, the Board does indeed not define a joystick, so let's add a virtual one. The Joystick.h from LUFA\Drivers\Board\BUMBLEB will actually do just fine (it's using Port D but doesn't conflict with our LEDs or switches), so we just copy that file over to LUFA\Drivers\Board\MINIMUS. Ideally, you want to edit the __JOYSTICK_BUMBLEB_H__ macro in there to __JOYSTICK_MINIMUS_H__. Then you also need to edit LUFA\Drivers\Board\Joystick.h to add the lines:
        #elif (BOARD == BOARD_MINIMUS)
            #include "MINIMUS/Joystick.h"
Alrighty, let's try again...


"Come on makefile, you used to be cool!"
D:\lufa-lib\Demos\Device\ClassDriver\Joystick>make
The system cannot find the path specified.
The system cannot find the path specified.
ECHO is off.
-------- begin --------
avr-gcc (AVR_8_bit_GNU_Toolchain_3.2.0_253) 4.5.1
Copyright (C) 2010 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

ECHO is off.
Compiling C: Joystick.c
avr-gcc -c -mmcu=at90usb162 -I. -gdwarf-2 -DF_CPU=16000000UL -DF_CLOCK=16000000UL -DBOARD=BOARD_MINIMUS -DARCH=ARCH_AVR8 -D USB_DEVICE_ONLY -D FIXED_CONTROL_ENDPOINT_SIZE=8 -D FIXED_NUM_CONFIGURATIONS=1 -D USE_FLASH_DESCRIPTORS -D USE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=./Joystick.lst -I../../../../ -std=c99 -MMD -MP -MF .dep/Joystick.o.d Joystick.c -o Joystick.o
Joystick.c:188:1: fatal error: opening dependency file .dep/Joystick.o.d: No such file or directory
compilation terminated.
make: *** [Joystick.o] Error 1
Ah, that dreaded "fatal error: opening dependency file .dep/Joystick.o.d: No such file or directory" error...
Once again, to cut to the chase, you'll notice that we haven't fixed the "The system cannot find the path specified." /dev/null errors. Well, what do you know, the dependency problems actually comes from the .dep directory creation step not being able to execute because it references /dev/null.
The fix is simple (though output polluting): In the makefile, change the following:
# Create object files directory
$(shell mkdir $(OBJDIR) 2>/dev/null)

# Include the dependency files.
-include $(shell mkdir .dep 2>/dev/null) $(wildcard .dep/*)
into:
# Create object files directory
$(shell mkdir $(OBJDIR))

# Include the dependency files.
-include $(shell mkdir .dep) $(wildcard .dep/*)

Try again.
(...)
ECHO is off.
Creating load file for Flash: Joystick.hex
avr-objcopy -O ihex -R .eeprom -R .fuse -R .lock Joystick.elf Joystick.hex
ECHO is off.
Creating load file for EEPROM: Joystick.eep
avr-objcopy -j .eeprom --set-section-flags=.eeprom="alloc,load" \
        --change-section-lma .eeprom=0 --no-change-warnings -O ihex Joystick.elf Joystick.eep || exit 0
ECHO is off.
Creating Extended Listing: Joystick.lss
avr-objdump -h -S -z Joystick.elf > Joystick.lss
ECHO is off.
Creating Symbol Table: Joystick.sym
avr-nm -n Joystick.elf > Joystick.sym
--------  end  --------
Yes, we have our hex file!! The system works!
If you flash the hex, you should now get a nice little "LUFA Joystick Demo" in your devices, and if you go to the Game controller settings → Properties, you should be able to see the status of the HWB button in realtime.

Now, using AVR Studio 5 with LUFA wasn't that difficult after all was it?
In the next post, I'll show you how to run everything from the AVR Studio UI, so that you're all set for LUFA development.

2011-03-10

Atmel AVR USB - First app

Time to get our toolchain installed then. You'll see plenty of posts mentioning the need to install WinAVR around, but with the latest toolchain from Atmel, it looks like a separate installation of WinAVR has become a thing of the past, and we won't actually need to install anything but latest official Atmel toolchain, which is called AVR Studio.

Now, Atmel did the smart thing here: They picked up the Visual Studio 2010 base from Microsoft which they wrapped around avr-gcc and avr-libc. We've come a long way from substandard proprietary toolchains...

So off you go to download AVR Studio 5 (free, but registration required). Installation takes a little while but is a no brainer. Sadly, no Flip integration is provided yet, so we'll have to generate a .hex and still use Flip manually to transfer the files. On the other hand, it should be possible to port the libusb 1.0 and commandline based dfu-programmer to Windows, to provide a flashing tool that integrates with AVR Studio.


Creating a project for Minimus USB

Alrighty, let's create our first LED blinking app then. Creatively, I'm going to call it 'Blinky'.
In AVR Studio, click "New Project" and use the "AVR GCC", "Empty AVR GCC Project" template (which should be selected by default). The Minimus USB, or any AT90USB162 based board don't seem to exist in the Atmel/User Boards lists, so don't bother trying to pick a template there. Change the default Name to 'Blinky' and click OK.
On the next screen, in the Device Family, select "megaAVR, 8-bit", and pick up AT90USB162 (or any other Atmel chip you might be using). Click OK and you're done. AVR Studio will even create a source template for you, how nice!

One thing you'll notice when compiling a new project is that the default settings are not to generate a .hex. To fix that, simply right click on the project, in the solution explorer, and in the Build tab, on the "Generate Files" line make sure the ".hex" checkbox is set (for both Release and Debug).


Blinking code

Armed with the knowledge of where the LEDs and HWB button are connected (PD5 and PD6 for the LEDs, PD7 for HWB), let's write us some code to blink the LEDs. We might as well look at the samples for inspiration.

First thing we'll do, since we need to add some delay when toggling the LEDs, is use some of the handy functions from the avr-libc. util/delay.h provides a _delay_ms() call that should do the trick. The only thing is you need to define F_CPU to your board's frequency, before the #include, for the delay calls to be accurate. The Minimus USB uses a 16 MHz Xtal, therefore our blinking code can be:

#include <avr/io.h>
#define F_CPU 16.000E6
#include <util/delay.h>

void init_ports(void)
{
    PORTB = 0b00000000;
    DDRB = 0b00000000;

    PORTC = 0b00000000;
    DDRC = 0b00000000;

    PORTD = 0b00000000;
    DDRD = 0b01100000;      // Set LEDs as output
}

int main(void)
{
    init_ports();
    
    while(1)
    {
        if (PIND & 0b10000000) {
            PORTD = PORTD & ~0b01000000;
            PORTD = PORTD |  0b00100000;
            _delay_ms(200);
        
            PORTD = PORTD & ~0b00100000;
            PORTD = PORTD |  0b01000000;
            _delay_ms(200);
        } else {
            PORTD = PORTD | 0b01100000;
        }
    }
}


The (loose) PIND & 0b10000000 test is added to turn off both LEDS when HWB is pressed.This should compile alright.
Note that you might want to pay attention to the warnings generated when compiling (on the "Errors" tab), especially the one that says, when using delay.h in Debug mode:
"Compiler optimizations disabled; functions from won't work as designed". Using delay.h will be fine for Release, but if you find that your delays are off in Debug, don't be surprised.


That friggin' watchdog timer

OK then, let's use Flip to transfer the hex, then click "Start Application" and have a satisfied look at our red and blue LEDs alternating... except they don't! Only the red LED blinks, and definitely not at 200 ms. AVR Dude, what the hell?!?

Oh, and it gets better, if you unplug the board, and plug it back, then suddenly everything works. What's going on here?

Part of the answer can be found in the Flip user guide:


4. What is the difference between starting the application with the Reset box checked off or not?
• If you start the application with the Reset box checked, the device will start after a Watchdog reset and this watchdog will remain active. You need to disable the Watchdog in your application. Resetting the device, ensures there is no side effect from resources used by the boot-loader before starting the user application.

Lo and behold, if you uncheck the Reset box and reflash/restart the app, everything works as expected. Of course, if you're unaware that the Flip Reset box is the culprit, you're bound to run into this issue, eventually figure out that it has to do with the WatchDog, and want to disable it in your program, so we might as well take care of that little bugger.

Now, I found that the code samples from all the LED blinkers out there, that are supposed to disable the watchdog, as well as the watchdog disable code from the AT90USB162 datasheet didn't work at all. Even including <avr/wdt.h> and calling wdt_disable() alone didn't work (but at least you could do something like wdt_enable(WDTO_8S); to make the delay before reset much longer, in order to give you a chance to issue a wdt_reset() before it expires).
There have been a few discussions on the AVRFreaks forums related to this, and the first way I found to disable watchdog and make it work with a Minimus USB, for programs transferred using Flip with Reset enabled, was the one provided by curtvm's from this post.

If you include wd.h and call WD_DISABLE(), the Watchdog timer finally gets disabled. But then, looking at what the LUFA samples were doing, it appears that using avr/wdt.h also works, provided that you issue and MCUSR &= ~(1 << WDRF) before calling wdt_disable().
Thus, our final code, which now works regardless of whether the Watchdog is initially enabled or not, becomes:
#include <avr/io.h>
#define F_CPU 16.000E6
#include <util/delay.h>
#include <avr/wdt.h>

void init_ports(void)
{
    PORTB = 0b00000000;
    DDRB = 0b00000000;

    PORTC = 0b00000000;
    DDRC = 0b00000000;

    PORTD = 0b00000000;
    DDRD = 0b01100000;      // Set LEDs as output
}

int main(void)
{
    MCUSR &= ~(1 << WDRF);
    wdt_disable();
    init_ports();
    
    while(1)
    {
        if (PIND & 0b10000000) {
            PORTD = PORTD & ~0b01000000;
            PORTD = PORTD |  0b00100000;
            _delay_ms(200);
        
            PORTD = PORTD & ~0b00100000;
            PORTD = PORTD |  0b01000000;
            _delay_ms(200);
        } else {
            PORTD = PORTD | 0b01100000;
        }
    }
}

Tested and confirmed. Great, now we're all set to produce more interesting AVR USB apps, like ones using LUFA for instance...

Atmel AVR USB - Let's get cracking!

Recently purchased a Minimus USB clone as these have gotten relatively cheap thanks to all the current PS3 hacking (Disclaimer: I don't have a PS3 and don't care much about what other non-development use these boards are also being targeted at).

All this to say that getting an Atmel AT90USB162 based board, or similar, has now gotten cheap enough that you might as well get one, if you're planning to play with USB, using Atmel AVR chips.

The following post assumes that you're completely new to AVR development, and aims at helping you getting started. I'll assume the use of a Minimus USB board and Windows, for the rest of this guide.


Flip... flops?

Except for the bootloader, the flash should be pretty much blank on arrival, yet you probably found a test program that tests the LEDs or something, that you want to run to confirm that the board is good. There's an USB bootloader in there, to take care of the flashing, but to be able to use it you'll need the following:
  1. the flashing application itself, which is Java based and called "Flip"
  2. an USB driver for the application to use
If you head to the Atmel website you'll find the Flip 3.4.2 downloads. If you don't have Java installed already, you should obviously pick the one that has the JRE included, and install the application. That takes care of step 1, but we still need some drivers to have the app communicate with the device. These drivers are located in "C:\Program Files (x86)\Atmel\Flip 3.4.2\usb" (If you used the default installation path).
Now the good news here is that they are using the libusb-win32 Windows driver (smart choice!). The bad news however is that, as per Flip 3.4.2, they are not using the signed libusb0.sys drivers, or anything WHQL. Therefore, if you're running on Windows 7 or Vista x64, the driver installation will fail. Ouch!
Thankfully, you don't have to use the Atmel driver files from the Flip application, and the latest libusb-win32 ones, which are signed, will work just fine. The easiest way to install them then is to download the latest libusb-win32 binary release, extract the zip and then run the inf-wizard.exe you'll find in there, with your device plugged in. Or you can also download the latest Zadig.exe, select Options->Advanced Mode, and change the target driver from WinUSB. which is the default, to libusb0.

Once the driver is successfully installed, you can run Flip, and if you press Ctrl+U to bring the USB communications menu (or go to Settings -> Communication -> USB), you should now be able to open the device with Flip properly identifying your chip. Groovy.

I also should point out that a more detailed guide (with pictures) on how to use Flip with AT90USB chips is also available from Atmel.


Bootloader mode or not bootloader mode: that is the question

One item that might be of interest to you, if you're completely new to using bootloaders to reprogram the flash, is that once you successfully transfer an application to the flash and get it to run, the bootloader will obviously no longer be accessible, and if your app does not do anything with USB, it will be innaccessible from your computer.

So how do you get back to USB bootloader mode for reflashing? Simple:
Just make sure the HWB button is pressed when you press the RST button.

So in essence the method to enter the bootloader is 1. Press RST, 2. press HWB, 3. release RST, 4. release HWB - easy.
This of course assumes that the Hardware Boot Enable Fuse (HWBE) has been set on the board and that PD7 is connected to a HWB button. For more info, see chapter 23.5 of the AT90USB162 datasheet.


Is it Blinky? Or is it just Clyde?

"Enough of these preliminaries, let's get these LEDs blinking already!"

Alright, I hear ya. But if you assume that any LED blinking app listed on the Minimus USB website would work, you assumed wrong. The only one that actually successfully blinks the LEDs is the one you will find in the minimus_led_test.rar, and even that one, depending on how you run it, might not actually blink the LEDs because of how its program, but because of the watchdog timer (more about this in the next post).

So, provided you extracted the minimus_led_test.hex, and you have Flip in programming mode, the way to go is:
  1. File -> Load Hex file and pick up the .hex. The FLASH Buffer information will now be populated
  2. Click the 'Run' button, which will erase, program and verify the flash (default options). Note that if you try to flash without erasing first, you will get a "Device protection is set" error. You always need to erase the flash first
  3. Click the "Start Application" button
Your LEDs blinking yet? Good. Now let's get ourselves sorted to write our own LED blinker app.
We'll setup a toolchain that generates Intel .hex files, and then flash these files using the same method above.