Atmega 32u4 Based Generic USB Mouse (Part 1/25)

A Mouse is a common computer peripheral apart from the keyboard. Even the touchpad is not able to dent the popularity of mouse. Nowadays the keyboards, as well as mouse, connect through the computers via USB cable or the fancier one connect to the PCs wirelessly through Bluetooth. This project is an attempt to demonstrate the functioning of a generic USB mouse. The 8-bit USB AVR – Atmega 32u4 is used as the USB device controller in the project. In order to avoid complexity, the project uses AVR based Lightweight USB Framework (LUFA) as the firmware.

Fig. 1: Prototype of Arduino based USB Mouse

Usually, the USB mouse has optical sensor to detect the desired direction of navigation across the screen. Instead of using an optical sensor, the project will use tactile switches to input navigational directions across the screen. The LUFA firmware is used and its device driver class for the mouse is modified to program the project. By using LUFA firmware, the device driver code to implement USB protocol shall not need to be written explicitly. What all shall be required is understanding the firmware code and modifying it to suit the project functioning. The project works similar to two button mouse and has the input switches for the following functions -:

• Move Pointer Left

• Move Pointer Right

• Move Pointer Upwards

• Move Pointer Down

• Right Click

• Left Click

The project has switches for user inputs, Atmega 32u4 as the controller chip (onboard Arduino Pro Micro) and USB cable to connect to the personal computer.

PREQUISITES

This project is based Arduino Pro Micro which has the USB AVR – Atmega 32u4 as the sitting MCU. In order to understand this project, one must have basic knowledge of the AVR microcontrollers and the embedded C programming for AVRs. WinAVR Studio is used to write, edit and compile the project code, so closely following the project shall require familiarizing with the above stated IDE as well. Though modifying the LUFA code for this project has little to do with the USB protocol, understanding USB protocol is recommended to understand how actually the project is working. In fact, if anyone has already worked on some other microcontroller, it will not be much pain to understand and follow this project as the project code is more or less about getting input from the GPIO pins of AVR MCU and modifying the LUFA device driver for mouse accordingly.

Fig. 2: Image showing prototype USB mouse tested with a PC

COMPONENTS REQUIRED

1. Arduino Pro Micro

2. Breadboard

3. Connecting wires

4. Push buttons

5. Micro USB cable

6. 10K resistors

SOFTWARE TOOLS REQUIRED

1. WinAVR Studio

2. AVR Dude

3. LUFA Firmware

BLOCK DIAGRAM

Fig. 3: Block Diagram of Arduino based DIY USB Mouse

CIRCUIT CONNECTIONS

The project uses Arduino Pro Micro as the USB controller chip. A set of six tactile switches is connected to the port B of the Arduino. The switches are connected to pins 1, 3, 2, 6, 5 and 4 of the port B with functions assigned to them according to the following table -:

Fig. 4: Table listing Arduino pins and respective mouse functions

The Program code for the project is burnt to the Arduino Pro Micro using AVR Dude. The Arduino board is connected to the USB port of a PC by a USB cable.

HOW THE PROJECT WORKS

In this project, the USB protocol is implemented by the LUFA framework. For configuring the controller chip to work as USB Mouse, the HID Class Driver of the LUFA framework will be used. The Human Interface Device (HID) class takes care of the transfers between the host device and the human controlled USB peripherals like USB Keyboard, Mouse or Joystick.

When a USB device is attached to the host (PC), the host sends a request for configuration details in the form of a control transfer. The connected device has to respond with appropriate descriptors to get configured and do further operations. Only after configuration, the device can communicate with the host in the form of interrupt, isochronous or bulk transfers for executing the operations for which the device has been made. In the case of mouse, after configuring with the host device, it has to communicate with the host in the form of interrupt transfers for the intended mouse-like operations. The process of identification and configuration of the device with the host is called enumeration.

A mouse is a HID class USB device and LUFA framework has HID class related module in the LUFA-Source-Folder /LUFA/Drivers/USB/Class/Device folder. Other device class related module are also in the same folder. The LUFA framework has demo projects for different USB device classes in the LUFA-Source-FolderDemosDeviceClassDriver folder. For implementing the project, demo project for mouse provided in the LUFA framework will be modified and complied. The demo project for the mouse is in the LUFA-Source-FolderDemosDeviceClassDriver/Mouse folder. The folder contains mouse.c file which will be modified to work for our custom mouse device.

How Mouse.c identifies HID device being Mouse

The mouse.c uses Mouse_HID_Interface interface in HID_Device_USBTask() function which is being imported from the HIDDeviceClass.c (file located in LUFA-Source-Folder LUFADriversUSBClassDevice) to configure the device as mouse. The interface abstracts the low-level descriptor codes and identifies the device as mouse through an InterfaceNumber variable.

Fig. 5: Image showing prototype USB mouse tested with a PC

Usage And Data Report Descriptors

Any HID device has to exchange data with the host which should be structured in the form of reports. The report descriptor defines the report structure. A report descriptor contains the information needed by the host to determine the data format and how the data should be processed by the host. Therefore, a report descriptor basically structures the data that needs to be exchanged with the host according to the USB protocol.

For working like a mouse, the device will have to send usage report and data report descriptors specific to mouse HID Class to the host. The Usage Report informs the Host about the features or functionality of the USB device whereas the Data Report or Data Packet is used to transmit the data to the Host.

The Usage or Feature report contains the information related to the features of the device. For example, a Mouse feature report generally contains information about the number of buttons used, the number of axes, scroll wheel, the size of Data Report, minimum/maximum movement etc. In other words, this report informs the Host about the type of features needed in the device. The Host can access this report by requesting the device using GET_REPORT request. This report is transmitted using Control Transfer Type of the USB protocol.

From Where Mouse.C gets the USAGE and Data Report Descriptors

In the LUFA framework’s demo project for mouse, descriptor.c file is imported in mouse.c to send the relevant usage and data report descriptors to the host device. The descriptor.c defines a MouseReport[] structure which is used in the CALLBACK_HID_Device_CreateHIDReport() function of the mouse.c to generate mouse specific usage and data report descriptors. Inside descriptor.c the MouseReport[] structure has the values returned by HID_DESCRIPTOR_MOUSE() function. The HID_DESCRIPTOR_MOUSE() is defined in HIDClassCommon.h (located in LUFA-Source-FolderLUFADriversUSBClassCommon folder). The mouse.c imports usb.h which imports HIDCLass.h. In HIDClass.h is imported HIDClassDevice.h if the USB_CAN_BE_DEVICE is true for the controller chip to being a USB device, not the host. The HIDClassDevice.h imports HIDClassCommon.h where the HID device specific descriptor fields have been defined.

USAGE REPORT

HID_DESCRIPTOR_MOUSE() returns the following field values of the usage report descriptor specific to mouse functioning -:

Fig. 6: Table listing field values of Usage report descriptor specific to USB Mouse

These fields are set to following values in HID_DESCRIPTOR_MOUSE().

Fig. 7: Screenshot of HID_DESCRIPTOR_MOUSE function from LUFA library

There is also a PHYSICAL_MINIMUM and PHYSICAL_MAXIMUM associated with mouse movement. The LOGICAL and PHYSICAL movement information together helps in find the Resolution Multiplier for the mouse movement. The Resolution Multiplier is a scaler multiplier used to change the movement sensitivity. The resolution is calculated at the Host end using the formula -:

(Logical Maximum – Logical Minimum) / ((Physical Maximum – Physical Minimum)*10^{Unit Exponent})

For a 400 DPI mouse, the Unit Exponent is -4.

DATA REPORT

The Data Report or Data Packet contains the data that needs to be transmitted to the Host. It contains data related to the features selected via the Usage Report. Again in the HIDClassCommon.h a structure for data report of mouse is defined in the following manner.

Fig. 8: Screenshot of data report structure for USB Mouse from LUFA library

The field values specific to data report for mouse has the following definitions -:

Fig. 9: Table listing field values specific to data report of USB Mouse

HOW THE DEVICE WORKS

The AVR microcontroller is programmed to work with the tactile switches for button and directional inputs. The main() function and the CALLBACK_HID_Device_CreateHIDReport() function of the mouse.c will be modified to customize the device for working with tactile switches as source for reading button and directional inputs. Check out the program code to see the modifications implemented for this custom mouse.

PROGRAMMING GUIDE

For building the project download the LUFA framework from the github.com.The demo project provided with the LUFA framework is modified to make this custom mouse. In the extracted LUFA zip file, open Demos/Device/ClassDriver/Mouse folder. The folder has the following files and folders.

Fig. 10: Screenshot of extracted LUFA Zip File

Of these, Mouse.h, Mouse.c and Makefile need to be modified for this project.The modified files (provided at the bottom of the article in zip format) can also be downloaded from the engineersgarage and replaced with the original files. Either open the files in WinAVR Studio or Notepad++ and modify original files or replace files with the modified one. The modified or replaced Mouse.c needs to be compiled from within the LUFA’s Source folder to get the object code.

Modifying Mouse.h

The Mouse.h library file is imported in the mouse.c file and includes a set of additional libraries and defines the constants and functions for the mouse device. These include the additional libraries for the joystick, button, and LEDs which should be commented out as the project is not using optical sensors, LEDs or click buttons of typical mouse. So open Mouse.h and make the following changes -:

• Comment the #include library statements for Joystick.h, LEDS.h, and Buttons.h

• Comment the #define statements for LEDMASK_USB_NOTREADY, LEDMASK_USB_ENUMERATING, LEDMASK_USB_READY, LEDMASK_USB_ERROR

Save the file with changes.

Modifying Mouse.C file

Again in the Mouse.c, the code sections for Joystick, button board and LEDs need to be commented out. So open mouse.c and make the following changes – :

• In the main loop, comment the LEDs_SetAllLEDs()

• In SetupHardware() function, comment the Joystick_Init(), LEDs_Init(), Buttons_Init()

• In EVENT_USB_Device_Connect() function, comment the LEDs_SetAllLEDs()

• In EVENT_USB_Device_Disconnect() function, comment LEDs_SetAllLEDs()

• In EVENT_USB_Device_ConfigurationChanged() function, comment the LEDs_SetAllLEDs()

In mouse.c the main() function executes the functioning of the mouse. Inside the main function Port B where the tactile switches have been connected needs to be defined as input and all the pins of port B has to be raised to HIGH logic by default as the microcontroller will need to detect LOW logic for input from tactile switches, so add the following statements in the beginning of main() function -:

int main(void)

{

DDRB = 0x00;

PORTB = 0xff;

SetupHardware();

//LEDs_SetAllLEDs(LEDMASK_USB_NOTREADY);

GlobalInterruptEnable();

for (;;)

{

HID_Device_USBTask(&Mouse_HID_Interface);

USB_USBTask();

}

Inside the infinite, for loop, the HID_Device_USBTask() function is called where Mouse_HID_Interface interface is passed as parameter. The interface identifies the device as mouse and abstracts the low-level program code specific to mouse HID class. The function is coming from the HIDClassDevice.c module (located in LUFA/Drivers/USB/Class/Device/HIDClassDevice.c) and is used for general management task for a given HID class interface, required for the correct operation of the interface. It should be called in the main program loop, before the master USB management task USB_USBTask(). The USB_USBTask() is the main USB management task. The USB driver requires this task to be executed continuously when the USB system is active (device attached in host mode, or attached to a host in device mode) in order to manage USB communications. The function is defined in USBTask.c (Located in LUFA-Source-FolderLUFADriversUSBCore folder).

For creating Mouse Data report CALLBACK_HID_Device_CreateHIDReport() needs to be modified. The default file has the function body to detect joystick movement and click on button board.

Fig. 11: Screenshot of CALLBACK_HID_Device_CreateHIDReport Function in LUFA library

This mouse project is using tactile switches to feed directional and button inputs. Therefore, LOW bit at each button is detected and the corresponding field value in data report for mouse is changed accordingly. So replace the body of the function with the following code -:

bool

CALLBACK_HID_Device_CreateHIDReport(USB_ClassInfo_HID_Device_t* const HIDInterfaceInfo,

uint8_t* const ReportID,

const uint8_t ReportType,

void* ReportData,

uint16_t* const ReportSize)

{

USB_MouseReport_Data_t* MouseReport = (USB_MouseReport_Data_t*)ReportData;

if(!(PINB & _BV(PB4))) {

MouseReport->X = -1; // Move left in X

}

else if(!(PINB& _BV(PB5))) {

MouseReport->X = 1; // Move right in X

}

else

MouseReport->X = 0; // Do not move

if(!(PINB & _BV(PB6))) {

MouseReport->Y = -1; // Move up in Y

}

else if(!(PINB& _BV(PB2))) {

MouseReport->Y = 1; // Move down in Y

}

else

MouseReport->Y = 0; // Do not Move

if(!(PINB & _BV(PB3)))

MouseReport->Button = 1; // left mouse click

else if(!(PINB & _BV(PB1)))

MouseReport->Button = 2; // right mouse click

else

MouseReport->Button = 0; // no click

*ReportSize = sizeof(USB_MouseReport_Data_t);

return true;

}

In the body _BV() function is used to map the respective bit as a byte with only the respective bit changed in the returned byte. Save the file and create Make file for the project.

Modifying Make File

In the Mouse folder, there will be a make file that needs to be edited. The file can be edited using Notepad++. The following information needs to be edited -:

• MCU = atmega32u4

• ARCH = AVR8

• BOARD = LEONARDO

• F_CPU = 16000000

Save the file and exit. Now all the files are edited completely for the basic HID Mouse application.

Compiling Mouse.c

For compiling the source code, we will use WinAVR Programmers Notepad. Open the modified Mouse.c file and compile the code.

Burning Hex code

The hex file is generated on compiling the mouse.c file. For burning the object code to microcontroller open the Command Prompt, change the current directory to the directory containing the Hex file. This can be done using command: CD <address of the directory>. Now reset the Arduino and instantly run the command: avrdude -v -p atmega32u4 -c avr109 -P COM20 -b 57600 -D -Uflash:w:Mouse.hex:i after replacing the COM Port with the recognized one.

If the uploading process is successful, the Arduino will be shown as HID Mouse in the Device Manager. There is no need of installing any driver in the computer as Generic HID Mouse is used for the project implementation. Use the buttons to test the project device working as generic USB Mouse.

Project Source Code

###



/*

             LUFA Library

     Copyright (C) Dean Camera, 2016.


  dean [at] fourwalledcubicle [dot] com

           www.lufa-lib.org

*/


/*

  Copyright 2016  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  Permission to use, copy, modify, distribute, and sell this
  software and its documentation for any purpose is hereby granted
  without fee, provided that the above copyright notice appear in
  all copies and that both that the copyright notice and this
  permission notice and warranty disclaimer appear in supporting
  documentation, and that the name of the author not be used in
  advertising or publicity pertaining to distribution of the
  software without specific, written prior permission.
  The author disclaims all warranties with regard to this
  software, including all implied warranties of merchantability
  and fitness.  In no event shall the author be liable for any
  special, indirect or consequential damages or any damages
  whatsoever resulting from loss of use, data or profits, whether
  in an action of contract, negligence or other tortious action,
  arising out of or in connection with the use or performance of
  this software.

*/


/** file

 *

 *  Main source file for the Mouse demo. This file contains the main tasks of

 *  the demo and is responsible for the initial application hardware configuration.

 */


#include "Mouse.h"


/** Buffer to hold the previously generated Mouse HID report, for comparison

purposes inside the HID class driver. */

static uint8_t PrevMouseHIDReportBuffer[sizeof(USB_MouseReport_Data_t)];


/** LUFA HID Class driver interface configuration and state information. This structure is

 *  passed to all HID Class driver functions, so that multiple instances of the same class

 *  within a device can be differentiated from one another.

 */

USB_ClassInfo_HID_Device_t Mouse_HID_Interface =

{

.Config =

{

.InterfaceNumber              = INTERFACE_ID_Mouse,

.ReportINEndpoint             =

{

.Address              = MOUSE_EPADDR,

.Size                 = MOUSE_EPSIZE,

.Banks                = 1,

},

.PrevReportINBuffer           = PrevMouseHIDReportBuffer,

.PrevReportINBufferSize       = sizeof(PrevMouseHIDReportBuffer),

},

};



/** Main program entry point. This routine contains the overall program flow, including initial

 *  setup of all components and the main program loop.

 */

int main(void)

{

DDRB = 0x00;

PORTB = 0xff;

SetupHardware();


//LEDs_SetAllLEDs(LEDMASK_USB_NOTREADY);

GlobalInterruptEnable();


for (;;)

{

HID_Device_USBTask(&Mouse_HID_Interface);

USB_USBTask();

}

}


/** Configures the board hardware and chip peripherals for the demo's functionality. */

void SetupHardware(void)

{

#if (ARCH == ARCH_AVR8)

/* Disable watchdog if enabled by bootloader/fuses */

MCUSR &= ~(1 << WDRF);

wdt_disable();


/* Disable clock division */

clock_prescale_set(clock_div_1);

#elif (ARCH == ARCH_XMEGA)

/* Start the PLL to multiply the 2MHz RC oscillator to 32MHz and switch the CPU core to run from it */

XMEGACLK_StartPLL(CLOCK_SRC_INT_RC2MHZ, 2000000, F_CPU);

XMEGACLK_SetCPUClockSource(CLOCK_SRC_PLL);


/* Start the 32MHz internal RC oscillator and start the DFLL to increase
it to 48MHz using the USB SOF as a reference */

XMEGACLK_StartInternalOscillator(CLOCK_SRC_INT_RC32MHZ);

XMEGACLK_StartDFLL(CLOCK_SRC_INT_RC32MHZ, DFLL_REF_INT_USBSOF, F_USB);


PMIC.CTRL = PMIC_LOLVLEN_bm | PMIC_MEDLVLEN_bm | PMIC_HILVLEN_bm;

#endif


/* Hardware Initialization */

//Joystick_Init();

//LEDs_Init();

//Buttons_Init();

USB_Init();

}


/** Event handler for the library USB Connection event. */

void EVENT_USB_Device_Connect(void)

{

//LEDs_SetAllLEDs(LEDMASK_USB_ENUMERATING);

}


/** Event handler for the library USB Disconnection event. */

void EVENT_USB_Device_Disconnect(void)

{

//LEDs_SetAllLEDs(LEDMASK_USB_NOTREADY);

}


/** Event handler for the library USB Configuration Changed event. */

void EVENT_USB_Device_ConfigurationChanged(void)

{

bool ConfigSuccess = true;


ConfigSuccess &= HID_Device_ConfigureEndpoints(&Mouse_HID_Interface);


USB_Device_EnableSOFEvents();


//LEDs_SetAllLEDs(ConfigSuccess ? LEDMASK_USB_READY : LEDMASK_USB_ERROR);

}


/** Event handler for the library USB Control Request reception event. */

void EVENT_USB_Device_ControlRequest(void)

{

HID_Device_ProcessControlRequest(&Mouse_HID_Interface);

}


/** Event handler for the USB device Start Of Frame event. */

void EVENT_USB_Device_StartOfFrame(void)

{

HID_Device_MillisecondElapsed(&Mouse_HID_Interface);

}


/** HID class driver callback function for the creation of HID reports to the host.

 *

 *  param[in]     HIDInterfaceInfo  Pointer to the HID class interface 
configuration structure being referenced

 *  param[in,out] ReportID    Report ID requested by the host if non-zero, 
otherwise callback should set to the generated report ID

 *  param[in]     ReportType  Type of the report to create, 
either HID_REPORT_ITEM_In or HID_REPORT_ITEM_Feature

 *  param[out]    ReportData  Pointer to a buffer where the created report should be stored

 *  param[out]    ReportSize  Number of bytes written in the report (or zero if no report is to be sent)

 *

 *  return Boolean c true to force the sending of the report, c false to 
let the library determine if it needs to be sent

 */

bool CALLBACK_HID_Device_CreateHIDReport(USB_ClassInfo_HID_Device_t* const HIDInterfaceInfo,

                                         uint8_t* const ReportID,

                                         const uint8_t ReportType,

                                         void* ReportData,

                                         uint16_t* const ReportSize)

{

USB_MouseReport_Data_t* MouseReport = (USB_MouseReport_Data_t*)ReportData;

        

if(!(PINB & _BV(PB4))) { 

MouseReport->X = -1; // Move left in X

    }

else if(!(PINB& _BV(PB5))) {

     MouseReport->X = 1; // Move right in X

    }

else

MouseReport->X = 0; // Do not move


if(!(PINB & _BV(PB6))) {

MouseReport->Y = -1; // Move up in Y

    } 

else if(!(PINB& _BV(PB2))) {

MouseReport->Y = 1; // Move down in Y

    }

else

MouseReport->Y = 0; // Do not Move


if(!(PINB & _BV(PB3))) 

MouseReport->Button = 1; // left mouse click

else if(!(PINB & _BV(PB1))) 

MouseReport->Button = 2; // right mouse click

else

MouseReport->Button = 0; // no click




*ReportSize = sizeof(USB_MouseReport_Data_t);

return true;

}


/** HID class driver callback function for the processing of HID reports from the host.

 *

 *  param[in] HIDInterfaceInfo  Pointer to the HID class interface configuration structure being referenced

 *  param[in] ReportID    Report ID of the received report from the host

 *  param[in] ReportType  The type of report that the host has sent, 
either HID_REPORT_ITEM_Out or HID_REPORT_ITEM_Feature

 *  param[in] ReportData  Pointer to a buffer where the received report has been stored

 *  param[in] ReportSize  Size in bytes of the received HID report

 */

void CALLBACK_HID_Device_ProcessHIDReport(USB_ClassInfo_HID_Device_t* const HIDInterfaceInfo,

                                          const uint8_t ReportID,

                                          const uint8_t ReportType,

                                          const void* ReportData,

                                          const uint16_t ReportSize)

{

// Unused (but mandatory for the HID class driver) in this demo, since there are no Host->Device reports

}
###