Getting a simple CDC demo (serial port via USB) working with a PIC32 (PIC32MX575)

This is just a quick write-up to save others some debugging time. The adventure is called: Get the "cdc_serial_emulator" example supplied of Microchip Harmony (/harmony/v0_70b/apps/usb/device/cdc_serial_emulator) up and running on my custom PIC32 board.

Once one understands the inner workings of the firmeware, the first steps are quite simple. First of all I modified the code which assumed we would run on an Explorer Board. Therefore I commented everything uncompilable and unneeded in bsp_sys_init.c out.

Now that I was able to compile the project, I was ready to enter the USB descriptor hell. And believe it or not, my Windows 7 machine was the most helpful tool for my first steps. Every time I plugged my board in, those annoying "USB device connected" sounds let me know if the communication worked or not. Of course, it didn't  by default. The reason is the clock frequency of the PIC. The USB module has an internal PLL which generates the required 48 MHz. This PLL is fed by the main oscillator and therefore everything needs to be setup correctly. I used (for no special reason) a 20 MHz crystal instead of the 8 MHz crystal assumed by the example.

Therefore I needed to tweak the config settings found in system_init.c: 
OSCO Pin(OSCIOFNC)                        = Enable
Primary Oscillator Configuration(POSCMOD) = External (Highspeed)
Secondary Oscillator Enable(FSOSCEN)      = Disabled
Oscillator Selection Bits(FNOSC)          = Primary osc with PLL

#pragma config OSCIOFNC = ON, POSCMOD = HS, FSOSCEN = OFF, FNOSC = PRIPLL

PLL Input Divider (FPLLIDIV)               = Divide by 5 
(20 Mhz / 5 = 4 MHz) 
PLL Multiplier (FPLLMUL)                   = Multiply by 20

(4 MHz * 20 = 80MHz)
System PLL Output Clock Divider (FPLLODIV) = Divide by 1
(80 MHz / 1 = 80 MHz system clock)
Peripheral Clock Divisor (FPBDIV)          = Divide by 1
(80 MHz / 1 = 80 MHz peripheral clock)

Watchdog Timer Enable (FWDTEN)                 = Disabled
Clock Switching and Monitor Selection (FCKSM)  
 = Clock Switch Enable, Fail Safe Clock Monitoring Enable

#pragma config FPLLIDIV = DIV_5, FPLLMUL = MUL_20, FPLLODIV = DIV_1
#pragma config FWDTEN = OFF, FCKSM = CSECME, FPBDIV = DIV_1 

Enable PLL for USB clock generation 

#pragma config UPLLEN   = ON

Divide external input clock by 5 before it is fed into the USB PLL.
20 MHz / 5 = 4 MHz (This is multiplied by 24 and then divided by 2 - see Reference Manual Page 27-3). This will result in the desired 48 MHz USB reference clock.

#pragma config UPLLIDIV = DIV_5

As this only took 3 evenings to figure out, this can be considered the easy part...The problem was, that neither Linux nor OSX would recognize the device as serial port (the device itself was found). Therefore it was clear that the timing was ok, but the USB descriptor wasn't.

After days of debugging (mostly on OSX using USBProbe) I switched to Linux and tried "lsusb -v". And there you go: The CDC-Descriptor provided by microchip was/is wrong! lsusb said something like "INVALID CDC(UNION) 0x04 0x24 0x06 0x00. Looking at the descriptor, this was really the input in system_config.c:


    // Size of the descriptor
    sizeof(USB_CDC_UNION_FUNCTIONAL_DESCRIPTOR_HEADER),
    // CS_INTERFACE
    USB_CDC_DESC_CS_INTERFACE,
    // Type of functional descriptor
    USB_CDC_FUNCTIONAL_UNION,
    //com interface number
    0,

Compared to any other CDC device I tried, this was missing one byte as the record (descriptor) has to look like LENGTH, TYPE, SUBTYPE, MASTER_INTERFACE, SLAVE_INTERFACE - so this was clearly missing one byte. Therefore I changed to code to:

0x05, // Size (5 bytes)
0x24, // DescriptorType: CS_INTERFACE
0x06, // DescriptorSubtype: Union Functional Descriptor
0x00, // MasterInterface
0x01, // SlaveInterface0

Of course, that didn't work out of the box - as I changed the descriptor by adding one byte, I had to fix the size at the begin of the descriptor:

/* Configuration 1 Descriptor */
const uint8_t configDescriptor1[]={
   
    /* Configuration Descriptor */
    //sizeof(USB_CFG_DSC),    // Size of this descriptor in bytes
    0x09,
    // CONFIGURATION descriptor type
    USB_DESCRIPTOR_CONFIGURATION,
    // Total length of data for this cfg
    67,0, // This was 66 originally

Using this, both, my Mac and Linux machines now recognize the device and supply a tty for it :-)