14.4 USB HID Joystick

Now that the main components of the USB device has been set up, it’s time to worry about the application specific implementation. There are three files that we need to modify before we can compile and load the device.

main.c

The first of these is “main.c”. In the Microchip version of the file, there are a ton of “#pragma” directives used to declare data and program space on the PIC18. On the C30 compiler for the PIC24, “#pragma” directives are not supported. You can safely delete these lines. You can also delete all lines with the directive pertaining to “#if defined(__18CXX)” since we are exclusively covering PIC24 usage. We are also defining all board specific variables and types in our “bsp.c” and “bsp.h” files, so we can go ahead and delete the joystick report type definitions and variable declaration in the “main.c” file as well. We must keep the global USB function that are located towards the end of the file. In the end your “main.c” file should look something like this:

/******************************************************************************
Engscope.com
Authro: JL
Created		May 27, 2010
Modified	Mar 27, 2010
USB Framework
******************************************************************************/

//headers for QP
#include "dev.h"

//configuration bits
_CONFIG1(JTAGEN_OFF & GCP_OFF & GWRP_OFF & FWDTEN_OFF)
		//jtag off
		//write protect off
		//emulation off
		//watchdog off

_CONFIG2(IESO_OFF & PLLDIV_DIV2 & FNOSC_PRIPLL & FCKSM_CSECMD \
	& IOL1WAY_OFF & OSCIOFNC_OFF & POSCMOD_EC)
		//secondary oscillator off
		//set pll to 24Mhz
		//use fast RC
		//disable clock switching
		//use osco
		//unlimited writes to RP
		//disable primary oscillator

_CONFIG3(WPDIS_WPDIS & SOSCSEL_IO)
		//disable write protect	

/** PRIVATE PROTOTYPES *********************************************/
static void InitializeSystem(void);

//main entry
int main(void)
{
	//initialize the Board Support Package
	BSP_init();

    //initialize USB
    InitializeSystem();

	//attach device
	#if defined(USB_INTERRUPT)
        USBDeviceAttach();
    #endif

	//loop forever
	while(1){
	}
}

/********************************************************************
 * Function:        static void InitializeSystem(void)
 *
//... rest of global USB functions

Device Descriptor

Now we need to describe our USB device to the USB host. This is done through the file “usb_descriptors.c”. When you open the file, you will notice that it is structured exactly like the USB hierarchy.

/* Device Descriptor */
ROM USB_DEVICE_DESCRIPTOR device_dsc=
{
    0x12,    // Size of this descriptor in bytes
    USB_DESCRIPTOR_DEVICE,  // DEVICE descriptor type
    0x0200,                 // USB Spec Release Number in BCD format
    0x00,                   // Class Code
    0x00,                   // Subclass code
    0x00,                   // Protocol code
    USB_EP0_BUFF_SIZE,      // Max packet size for EP0, see usb_config.h
    MY_VID,                 // Vendor ID, see usb_config.h
    MY_PID,                 // Product ID, see usb_config.h
    0x0001,                 // Device release number in BCD format
    0x01,                   // Manufacturer string index
    0x02,                   // Product string index
    0x00,                   // Device serial number string index
    0x01                    // Number of possible configurations
};

/* Configuration 1 Descriptor */
ROM BYTE configDescriptor1[]={
    /* Configuration Descriptor */
    0x09,//sizeof(USB_CFG_DSC),    // Size of this descriptor in bytes
    USB_DESCRIPTOR_CONFIGURATION,                // CONFIGURATION descriptor type
    DESC_CONFIG_WORD(0x0029),   // Total length of data for this cfg
    1,                      // Number of interfaces in this cfg
    1,                      // Index value of this configuration
    0,                      // Configuration string index
    _DEFAULT | _SELF,               // Attributes, see usb_device.h
    50,                     // Max power consumption (2X mA)

	/************************ JOYSTICK INTERFACE START************************/
    /* Interface Descriptor */
    0x09,//sizeof(USB_INTF_DSC),   // Size of this descriptor in bytes
    USB_DESCRIPTOR_INTERFACE,               // INTERFACE descriptor type
    0,                      // Interface Number
    0,                      // Alternate Setting Number
    2,                      // Number of endpoints in this intf
    HID_INTF,               // Class code
    0,     // Subclass code
    0,     // Protocol code
    0,                      // Interface string index

    /* HID Class-Specific Descriptor */
    0x09,//sizeof(USB_HID_DSC)+3,    // Size of this descriptor in bytes RRoj hack
    DSC_HID,                // HID descriptor type
    DESC_CONFIG_WORD(0x0111),                 // HID Spec Release Number in BCD format (1.11)
    0x00,                   // Country Code (0x00 for Not supported)
    HID_NUM_OF_DSC,         // Number of class descriptors, see usbcfg.h
    DSC_RPT,                // Report descriptor type
    DESC_CONFIG_WORD(HID_RPT01_SIZE),   //sizeof(hid_rpt01),      // Size of the report descriptor

    /* Endpoint Descriptor */
    0x07,/*sizeof(USB_EP_DSC)*/
    USB_DESCRIPTOR_ENDPOINT,    //Endpoint Descriptor
    HID_EP | _EP_IN,            //EndpointAddress
    _INTERRUPT,                       //Attributes
    DESC_CONFIG_WORD(64),        //size
    0xFF,                        //Interval

    /* Endpoint Descriptor */
    0x07,/*sizeof(USB_EP_DSC)*/
    USB_DESCRIPTOR_ENDPOINT,    //Endpoint Descriptor
    HID_EP | _EP_OUT,            //EndpointAddress
    _INTERRUPT,                       //Attributes
    DESC_CONFIG_WORD(64),        //size
    0xFF                        //Interval
};

The file first describes the device, then the configuration, the interface, and lastly the endpoint. In addition, there is a special description for the HID class that tells the USB host which report to use when sending data back and forth. Since the Microchip example is already describing an HID device that only sends data to the USB host (recall that the joystick only sends data one way, it does not receive any data from the host), there is not much that we need to modify in the device descriptor.

Report Descriptor

In addition to describing the device, we also need to describe the report. This report descriptor tells the USB host how to use the data that is being received and how to transmit data in a way that the host can understand. Since the Microchip joystick is not the same as the joystick we are building, we need to build the report descriptor from scratch. We will use the HID descriptor tool, provided by the USB-IF to do this step. After starting a new descriptor, I have loaded the following settings and clicked on “Parse Descriptor” to properly format the indentations.

At this point, it really pays to have a brief read into USB HID Standard. The document describes the requirements for defining the abilities of an HID device. Here I define the device and states that it is used as a general desktop device and a joystick. Next I define 6 buttons which can have a value of 0 or 1, defined by the variable input descriptor (INPUT (Data,Var,Abs). However, I need to use a single byte to represent 6 buttons. I need 2 filler bits in order to fill up the byte, which is defined by the constant input descriptor (INPUT (Cnst,Var,Abs)).

You can then use the “save as header” feature in the HID descriptor tool to get the C version of the descriptor directly. Then copy and paste the code into the report descriptor section of the “usb_descriptor.c” file. In the end your report descriptor should look like this:

ROM struct{BYTE report[HID_RPT01_SIZE];}hid_rpt01={{
    0x05, 0x01,                    // USAGE_PAGE (Generic Desktop)
    0x09, 0x05,                    // USAGE (Joystick)
    0xa1, 0x01,                    //   COLLECTION (Application)
    0x05, 0x09,                    //   USAGE_PAGE (Button)
    0x19, 0x01,                    //   USAGE_MINIMUM (Button 1)
    0x29, 0x06,                    //   USAGE_MAXIMUM (Button 6)
    0x15, 0x00,                    //   LOGICAL_MINIMUM (0)
    0x25, 0x01,                    //   LOGICAL_MAXIMUM (1)
    0x95, 0x06,                    //   REPORT_COUNT (6)
    0x75, 0x01,                    //   REPORT_SIZE (1)
    0x81, 0x02,                    //   INPUT (Data,Var,Abs)
    0x95, 0x01,                    //   REPORT_COUNT (1)
    0x75, 0x02,                    //   REPORT_SIZE (2)
    0x81, 0x03,                    //   INPUT (Cnst,Var,Abs)
    0xc0
}
};

String Descriptors

Finally, USB supports custom strings embedded into the device. These are character strings that are used when the operating system wants to refer to the device. In our example, I have named the device “Simple HID Joystick”. This will cause the device to show up in the “Devices and Printers” folder of Windows with the proper name.

String 0 must always indicate the language code. String 1 and greater can be any custom string that you might want to use for the device. Under the Microchip USB framework, the strings are defined as a ROM, and collectively pointed with a pointer:

//Language code string descriptor
ROM struct{BYTE bLength;BYTE bDscType;WORD string[1];}sd000={
sizeof(sd000),USB_DESCRIPTOR_STRING,{0x0409
}};

//Manufacturer string descriptor
ROM struct{BYTE bLength;BYTE bDscType;WORD string[8];}sd001={
sizeof(sd001),USB_DESCRIPTOR_STRING,
{'E','N','G','S','C','O','P','E'
}};

//Product string descriptor
ROM struct{BYTE bLength;BYTE bDscType;WORD string[19];}sd002={
sizeof(sd002),USB_DESCRIPTOR_STRING,
{'S','i','m','p','l','e',' ','H','I','D',' ','J','o','y','s','t','i','c','k'
}};

//Array of string descriptors
ROM BYTE *ROM USB_SD_Ptr[]=
{
    (ROM BYTE *ROM)&sd000,
    (ROM BYTE *ROM)&sd001,
    (ROM BYTE *ROM)&sd002
};

You can then specify which string to use for the manufacturer and product name in the device descriptor.

/* Device Descriptor */
ROM USB_DEVICE_DESCRIPTOR device_dsc=
{
    0x12,    // Size of this descriptor in bytes
    USB_DESCRIPTOR_DEVICE,  // DEVICE descriptor type
    0x0200,                 // USB Spec Release Number in BCD format
    0x00,                   // Class Code
    0x00,                   // Subclass code
    0x00,                   // Protocol code
    USB_EP0_BUFF_SIZE,      // Max packet size for EP0, see usb_config.h
    MY_VID,                 // Vendor ID, see usb_config.h
    MY_PID,                 // Product ID, see usb_config.h
    0x0001,                 // Device release number in BCD format
    0x01,                   // Manufacturer string index
    0x02,                   // Product string index
    0x00,                   // Device serial number string index
    0x01                    // Number of possible configurations
};

usb_config.c

The last file that needs to be modified is the “usb_config.c” file. This file contains your VID and PID information, as well as ROM memory reservations.

If you need a refresh of the function of the VID and PID values, please read section 2 of the USB tutorial. We will be borrowing Mircrochip’s VID, and randomly giving ourselves a PID of 0×0100.

#define MY_VID 0x04D8
#define MY_PID 0x0100

Since we have changed the length of our report descriptor, we will need to change the size of the ROM memory reservations. Here I have modified the size of my report descriptor by changing the symbol “HID_RPT01_SIZE”.

/** ENDPOINTS ALLOCATION *******************************************/
/* HID */
#define HID_INTF_ID             0x00
#define HID_EP 					1
#define HID_INT_OUT_EP_SIZE     64
#define HID_INT_IN_EP_SIZE      64
#define HID_NUM_OF_DSC          1
#define HID_RPT01_SIZE          29

Finishing Touches

We also need to create a file that sends out data in the struct through the API defined by Microchip. These files are called “nlib_hid.c” and “nlib_hid.h”. There is really nothing very interesting to see in these files, but basically they take care of transmitting the tokens and keeping track of whether a transfer is completed or not. The “nlib_hid.h” contains the function prototypes, while “nlib_hid.c” is where the action takes place, shown below:

#include 
#include "nlib_hid.h"

static USB_HANDLE devLastTransmission;	//transmission status
static HID_CONTROLS hid_input;	//stores current control values (button on/off, axis etc)
static int endPoint;	//this stores the EP number on initiation

//this is the function called during the process, updates Input Controls
static void (*processInput)(HID_CONTROLS *);

//this is the Initiation routine for custom user code
void hid_Init(int ep, void (*proc)(HID_CONTROLS *))
{
	//get the end point number
	endPoint = ep;

	//initialize the variable holding the handle for the last transmission
    devLastTransmission = 0;

	//link the function pointer
	processInput = proc;

	//hid_input should be zero by default (declaration zeros everything)
}//end UserInit

//function takes IO and pocoesses
void hid_Proc(void)
{
    // User Application USB tasks
    if((USBDeviceState < CONFIGURED_STATE)||(USBSuspendControl==1)) return;

	//for interface 0
    //If the last transmision is complete
    if(!HIDTxHandleBusy(devLastTransmission))
    {
		//processInput(&hid_input);	//process the input before transmitting it
		processInput(&hid_input);

		//Send the packet over USB to the host.
		devLastTransmission = HIDTxPacket(endPoint, (BYTE*)&hid_input, sizeof(hid_input));
    }
}//end ProcessIO

The main function called hid_Proc() takes the data structure that we defined earlier for our buttons and transfers it through the USB bus. It keeps track of whether the USB connection is ready for the next transfer. The “hid_input” variable, which was defined in our “bsp.h” is declared in here as a static. We update the values of variable hid_input through the function BSP_ProcHid() and transfers the variable with hid_Proc().

First Connection and Enumeration

I have taken the liberty of including the modified code below. The code should compile and ready to be loaded into a PIC24 device.

Engscope Simple HID Joystick Project
Please read the disclaimer before downloading.

After compiling and loading the hex file, Windows will automatically load the drivers. If you cannot get past this step, then either your firmware was not loaded properly or something in the hardware is not working. Keep checking your circuit to find the culprit if you are having problems with enumeration (look for bad voltages, bad oscillators, shorts, opens etc.). The compiled code is verified and working on my systems.

You can then open the “Set up USB game controllers” utility to test the device.

Lastly, to see the actually data being transferred from the device to the USB host, we can pop up the Simple HID Write tool and select the Simple HID Joystick.

The first byte indicates the report number, which is used if you have multiple reports on a simple device (e.g. a mouse/keyboard combo can use two reports to separate the data and functionality). Since we only have one report, the first byte is always 0×00. The second byte is defined by our report descriptor. You will see that the first 6 bits will change when the buttons are pressed, and the top 2 bits are always zero.

There you have it. We have just created a custom 6 button joystick.

Table of Contents