How using LUFA and Arduino Pro Micro, Keyboard and mouse can be made has been already demonstrated in the Atmega 32u4 based Generic USB Keyboard project and Atmega 32u4 Based USB Mouse project respectively. In this project a composite keyboard mouse will be designed. A composite device is a device that can perform multiple functions. It means that with the same hardware, the device can work like two different devices. Like in this project, the device using the same hardware function as keyboard as well as mouse. The project utilizes 8-bit USB AVR – Atmega 32u4 as the USB controller chip and uses AVR based Lightweight USB Framework (LUFA) as the firmware which is modified to implement the project.
Fig. 1: Prototype of Arduino Based USB Keyboard Mouse Composite Device
The HID device driver class for keyboard and mouse of the LUFA firmware is used in the project. The LUFA implements the device drivers with the help of interfaces. For making a composite device, two interfaces of the LUFA’s HID class drivers are called in the project code. So the composite keyboard mouse project utilizes the interface for keyboard as well as the mouse. The device switches functionality between mouse and keyboard on the press of an SPDT switch. The device has five buttons to perform different tasks. When switched to work as a keyboard, the buttons on the device have the following functions assigned – :
• Input H Alphabet to the computer
• Input I Alphabet to the computer
• Turn Caps lock ON or OFF
• Left Shift Key
When switched to work as a mouse, the buttons on the device have the following functions assigned – :
• Move Pointer Left
• Move Pointer Right
• Move Pointer Upwards
• Move Pointer Down
• Mouse Left Click
The project is based on generic USB drivers therefore, the device designed works with all types of desktop systems irrespective of the operating system installed on it.
The project uses tactile switches as the buttons, Atmega 32u4 as the controller chip (on board Arduino Pro Micro) and USB cable to connect with the personal computer.
PREREQUISITES
This project is based on 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 LUFA framework takes care of implementing the USB protocol and has APIs to abstract the lower level codes, 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 of generic keyboard-mouse composite device accordingly.
Fig. 2: Image demonstrating mouse function from Arduino Based USB Keyboard Mouse Composite Device
COMPONENTS REQUIRED
1. Arduino Pro Micro
2. Breadboard
3. Connecting wires
4. Push buttons
5. Micro USB cable
6. 10K resistors
7. SPDT switch
SOFTWARE TOOLS REQUIRED
1. WinAVR Studio
2. AVR Dude
Fig. 3: Block Diagram of Arduino Based USB Keyboard Mouse Composite Device
CIRCUIT CONNECTIONS
The project uses Arduino Pro Micro as the USB controller chip. A set of five tactile switches and an SPDT switch are connected at the port B of the Arduino. The switches are connected at pins 1, 2, 3, 5 and 6 of the port B and SPDT switch is connected at the pin 4 of Port B with functions assigned to them according to the following table – :
Fig. 4: Table listing Arduino pins and respective mouse functions
The tactile switches and the SPDT switch are connected between the port and ground. The pins of port B by default are connected to VCC and receive a HIGH logic. Pressing a tactile switch changes the status at the respective pin to LOW by short circuiting to the ground.
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
For configuring the controller chip to make device a composite keyboard and mouse, the HID Class Driver for keyboard as well as mouse of the LUFA framework are 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. The implementation of the USB protocol is carried out by the open-source drivers of the LUFA framework.
Like any other HID device, when the keyboard-mouse combo is attached to the host computer (PC), the host sends request for configuration details in the form of control transfer. The controller chip on device has to respond with appropriate descriptors to get configured and ready for further operations. Only after configuration, the device can transfer user inputs to the host in the form of interrupt transfers for executing the designated tasks. The process of identification and configuration of any USB device with the host is called enumeration.
Fig. 5: Image showing movement of cursor to left
Any device using HID class for keyboards identifies the key pressed by the keycode or combination of keycodes sent from the controller chip of the device to the host in the data input report while mouse specific HID class identifies the mouse click and mouse movement by a 3-byte long data report where first byte indicates button status, second byte indicates X coordinate and last third byte indicates Y coordinate. Any keyboard device sends a usage report and data input report to the host and receives data output report from the host at the application layer to work like a keyboard. Similarly any mouse device also sends usage report and data report to the host. The reports are a medium at application layer as per the USB protocol to facilitate enumeration and communication between the host and the device.
To learn about HID Class for Keyboard and how the usage report, data input report and data output report are structured in the HID Class for Keyboard, go through the Atmega 32u4 based Generic USB Keyboard project. To learn about the HID class for mouse and how usage report and data report for mouse are structured, go through the Atmega 32u4 based Generic USB Mouse Project. To learn about generic desktop controls for keyboard and mouse and how Usage Page and Usage IDs for different controls are standardized by the USB protocol, check out the HID Usage Table provided by the USB Implementers Forum.
When working as keyboard the device passes the following keycodes on the press of respective buttons – :
Fig. 6: Table listing Arduino pins and respective keyboard functions and keycodes
The LUFA framework has HID class related modules 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 keyboard-mouse combo provided in the LUFA framework is modified and complied. The demo project for keyboard-mouse combo is in the LUFA-Source-FolderDemosDeviceClassDriverKeyboardMouse folder. The folder contains KeyboardMouse.c file which will be modified for the projectIn the LUFA framework, the drivers for any device (like keyboard or mouse) are implemented through Interfaces. The interface abstracts the lower level codes and provide an API to program the device. For composite device, Interfaces for both the keyboard and the mouse have to be included in the project code.
How KeyboardMouse.c identifies HID device as Keyboard
The KeyboardMouse.c uses Keyboard_HID_Interface interface in HID_Device_USBTask() function which is being imported from the HIDDeviceClass.c (from LUFA-Source-Folder LUFADriversUSBClassDevice) to configure the device as keyboard. The interface abstracts the low-level descriptor codes and identifies the device as keyboard through an InterfaceNumber variable.
How KeyboardMouse.c identifies HID device being Mouse
The KeyboardMouse.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 again through an InterfaceNumber variable.
From Where KeyboardMouse.C gets the USAGE and Data Reports Descriptors
In the LUFA framework’s demo project for KeyboardMouse, KeyboardMouse.h file is imported in keyboardmouse.c to send the relevant usage and data reports descriptors to the host device. The KeyboardMouse.h imports a descriptor.h file which imports descriptor.c in which a KeyboardReport[] structure and MouseReport[] structure are defined. These structures are used in the CALLBACK_HID_Device_CreateHIDReport() function of the keyboardmouse.c to generate keyboard and mouse specific usage and data reports descriptors. Inside descriptor.c the KeyboardReport[] structure has the values returned by HID_DESCRIPTOR_KEYBOARD () function. The HID_DESCRIPTOR_KEYBOARD() is defined in HIDClassCommon.h (located in LUFA-Source-FolderLUFADriversUSBClassCommon folder). The MouseReport[] structure is also used in the CALLBACK_HID_Device_CreateHIDReport() function of the keyboardmouse.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 keyboardmouse.c imports keyboardmouse.h which imports usb.h. USB.h 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 usage descriptor fields for keyboard and mouse have been defined.
HOW THE DEVICE WORKS
The AVR microcontroller is programmed to get the user inputs from the tactile switches and has the SPDT switch to change between keyboard and mouse. The main() function and CALLBACK_HID_Device_CreateHIDReport() function of the KeyboardMouse.c are modified to detect inputs from the user and trace the status of SPDT switch. The project code according to the status of SPDT switch sends the relevant usage and data report to the host specific to keyboard or the mouse. Check out the program code to see the modifications done for implementation of this project.
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 keyboard mouse combo. In the extracted LUFA zip file, open Demos/Device/ClassDriver/KeyboardMouse folder. The folder has the following files and folders.
Fig. 7: Screenshot of LUFA Library Folder on Windows
Of these, KeyboardMouse.h, KeyboardMouse.c and Makefile needs to be modified for the 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 already modified one. The modified or replaced KeyboardMouse.c needs to be compiled from within the LUFA’s Source folder to get the object code.
Modifying KeyboardMouse.h
The KeyboardMouse.h library file is imported in the KeyboardMouse.c file and includes a set of additional libraries and defines the constants and functions for the keyboard and mouse device. These include the additional libraries for the joystick, button and LEDs which should be commented out as the project is not using these HID features. So open KeyboardMouse.h and make the following changes – :
• Comment the #include library statements for Joystick.h, LEDS.h, and Buttons.h (The include statements for these libraries are commented as any joystick, buttons board and LED board is not used in the project)
Save the file with changes.
Modifying KeyboardMouse.C file
Again in the KeyboardMouse.c, the code sections for Joystick, button board and LEDs need to be commented out. So open KeyboardMouse.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 KeyboardMouse.c the main() function executes the functioning of the device. Inside the main function, Port B where the tactile switches and SPDT switch have been connected needs to be defined as input and all the pins of port B have to be raised to HIGH logic by default as the microcontroller will need to detect LOW logic for input from the tactile switches and the SPDT switch. Therefore, modify the body of main() function as the code given belowThe statements should be added before the infinite loop otherwise the microcontroller ports could not be configured for the user inputs.
Inside the infinite for loop the HID_Device_USBTask() function is called where Keyboard_HID_Interface interface and Mouse_HID_Interface interface are passed as parameter in different function calls. The interface identifies the device as keyboard and mouse and abstracts the low level program code specific to keyboard and mouse HID class respectively. 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).
The CALLBACK_HID_Device_CreateHIDReport() takes care of passing the keyboard or mouse specific data reports. The project code identifies the device to keyboard or mouse by an if-else logic. The default file has the function body to detect joystick movement as well.
Fig. 8: Screenshot of CALLBACK_HID_Device_CreateHIDReport Function in LUFA Library
This device is using tactile switches to get the user inputs while it decides between configuring to keyboard or mouse based on the status of SPDT switch. Therefore, the status of pin 4 of port B is checked by detecting LOW or HIGH at the pin. If the pin 4 of Port B is at LOW, the device sends mouse specific data reports and if the pin 4 of Port B is HIGH, the device sends keyboard specific data reports. This is checked by tracing the status of the pin and returning 0 in either cases. Therefore, by default, the device works like a keyboard. The status of LOW bit at each button is detected and the relevant data report specific to keyboard or mouse is sent with the help of pre-defined macros. So replace the body of the CALLBACK_HID_Device_CreateHIDReport() function with the following code – :
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. In the code, the constants to represent the following generic keyboard keys are used (defined in HIDCommonClass.h, header file located in LUFA-Source-FolderLUFADriversUSBClassCommon folder).
Fig. 9: Table listing constants used in LUFA for keys used
The Data Output Report is not utilized in the project execution therefore the CALLBACK_HID_Device_ProcessHIDReport() function which process Data Output report for keyboard has been kept unchanged.
Save the file and create Make file for the project.
Modifying Make File
In the KeyboardMouse folder there is 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 project.
Compiling KeyboardMouse.c
For compiling the source code, WinAVR Programmers Notepad or Arduino IDE can be used. Open the modified KeyboardMouse.c file and compile the code.
BURNING HEX CODE
The hex file is generated on compiling the keyboardMouse.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:KeyboardMouse.hex:i after replacing the COM Port with the recognized one.
If the uploading process is successful, the Arduino board will be shown as HID Keyboard in the Device Manager. There is no need of installing any driver in the computer as Generic HID Keyboard and Mouse driver are used for the project implementation. Use the buttons to test the project device working as both keyboard and mouse.
In the next project – Atmega 32u4 Based Gamepad, learn how to make a joystick device for desktop games.
Project Source Code
###
/* LUFA Library Copyright (C) Dean Camera, 2015. dean [at] fourwalledcubicle [dot] com www.lufa-lib.org */ /* Copyright 2015 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 MediaControl project. This file contains the main tasks of * the demo and is responsible for the initial application hardware configuration. */ #include "MediaController.h" /** Buffer to hold the previously generated Media Control HID report, for comparison purposes inside the HID class driver. */ static uint8_t PrevMediaControlHIDReportBuffer[sizeof(USB_MediaReport_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 MediaControl_HID_Interface = { .Config = { .InterfaceNumber = INTERFACE_ID_HID, .ReportINEndpoint = { .Address = MEDIACONTROL_HID_EPADDR, .Size = MEDIACONTROL_HID_EPSIZE, .Banks = 1, }, .PrevReportINBuffer = PrevMediaControlHIDReportBuffer, .PrevReportINBufferSize = sizeof(PrevMediaControlHIDReportBuffer), }, }; /** 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) { SetupHardware(); DDRB = 0x00; DDRF = 0x00; PORTB = 0xff; PORTF = 0xff; //LEDs_SetAllLEDs(LEDMASK_USB_NOTREADY); GlobalInterruptEnable(); for (;;) { HID_Device_USBTask(&MediaControl_HID_Interface); USB_USBTask(); } } /** Configures the board hardware and chip peripherals for the demo's functionality. */ void SetupHardware() { #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); #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(&MediaControl_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(&MediaControl_HID_Interface); } /** Event handler for the USB device Start Of Frame event. */ void EVENT_USB_Device_StartOfFrame(void) { HID_Device_MillisecondElapsed(&MediaControl_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_MediaReport_Data_t* MediaReport = (USB_MediaReport_Data_t*)ReportData; //uint8_t JoyStatus_LCL = Joystick_GetStatus(); //uint8_t ButtonStatus_LCL = Buttons_GetStatus(); /* Update the Media Control report with the user button presses */ if(!(PINB & _BV(PB6))) { // set mute button status to logic one MediaReport->Mute = 1; } else { // reset mute button status to logic zero MediaReport->Mute = 0; } if(!(PINB & _BV(PB2))) { // set volume down button status to logic one MediaReport->VolumeDown = 1; } else { // reset volume down button status to logic zero MediaReport->VolumeDown = 0; } if(!(PINB & _BV(PB3))) { // set volume up button status to logic one MediaReport->VolumeUp = 1; } else { // reset volume up button status to logic zero MediaReport->VolumeUp= 0; } if(!(PINB & _BV(PB1))) { // set previous track button status to logic one MediaReport->PreviousTrack = 1; } else { // reset previous track button status to logic zero MediaReport->PreviousTrack = 0; } if(!(PINF & _BV(PF7))) { // set next track button status to logic one MediaReport->NextTrack = 1; } else { // reset next track button status to logic zero MediaReport->NextTrack = 0; } if(!(PINF & _BV(PF6))) { // set stop button status to logic one MediaReport->Stop = 1; } else { // reset stop button status to logic zero MediaReport->Stop = 0; } if(!(PINF & _BV(PF5))) { // set pause status to logic one MediaReport->Pause = 1; } else { // reset pause status to logic zero MediaReport->Pause = 0; } if(!(PINF & _BV(PF4))) { // set play status to logic one MediaReport->Play= 1; } else { // reset play status to logic zero MediaReport->Play = 0; } *ReportSize = sizeof(USB_MediaReport_Data_t); return false; } /** 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 }###
Circuit Diagrams
Project Datasheet
Project Video
Filed Under: Electronic Projects
Filed Under: Electronic Projects
Questions related to this article?
👉Ask and discuss on Electro-Tech-Online.com and EDAboard.com forums.
Tell Us What You Think!!
You must be logged in to post a comment.