Unit USBMOUSE

From Ultibo.org
Revision as of 04:02, 16 November 2022 by Ultibo (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Return to Unit Reference


Description

Ultibo USB Mouse Driver unit

USB Mouse Devices

The USB mouse driver in this unit uses HID Boot Protocol only and has been replaced by the HIDMouse unit which provides complete HID Report Protocol support for USB mice. It is retained here for legacy uses and backwards compatibility only.

To use this driver in place of the default HID Mouse driver set the following configuration variables in your application during system initialization. 

HID_REGISTER_MOUSE := False;
USB_MOUSE_REGISTER_DRIVER := True;

This driver does not recognize devices that do not report themselves as boot mice, does not correctly recognize the wheel on many devices and is known to be incompatible with the touch pad included in some portable wireless keyboards.

Constants


USB mouse specific constants USBMOUSE_*
USBMOUSE_DRIVER_NAME = 'USB Mouse Driver (HID boot protocol)'; Name of USB mouse driver
USBMOUSE_MOUSE_DESCRIPTION = 'USB HID Mouse'; Description of USB mouse device


USB HID types USB_HID_*
HID Interface Subclass types (See USB HID v1.11 specification)
USB_HID_SUBCLASS_NONE = 0; Section 4.2
USB_HID_SUBCLASS_BOOT = 1; Section 4.2
 
HID Interface Protocol types (See USB HID v1.11 specification)
USB_HID_BOOT_PROTOCOL_NONE = 0; Section 4.3
USB_HID_BOOT_PROTOCOL_KEYBOARD = 1; Section 4.3
USB_HID_BOOT_PROTOCOL_MOUSE = 2; Section 4.3
 
HID Class Descriptor Types (See USB HID v1.11 specification)
USB_HID_DESCRIPTOR_TYPE_HID = $21; Section 7.1
USB_HID_DESCRIPTOR_TYPE_REPORT = $22; Section 7.1
USB_HID_DESCRIPTOR_TYPE_PHYSICAL_DESCRIPTOR = $23; Section 7.1
 
HID Request types
USB_HID_REQUEST_GET_REPORT = $01;  
USB_HID_REQUEST_GET_IDLE = $02;  
USB_HID_REQUEST_GET_PROTOCOL = $03; Section 7.2
USB_HID_REQUEST_SET_REPORT = $09;  
USB_HID_REQUEST_SET_IDLE = $0A;  
USB_HID_REQUEST_SET_PROTOCOL = $0B; Section 7.2
 
HID Protocol types
USB_HID_PROTOCOL_BOOT = 0; Section 7.2.5
USB_HID_PROTOCOL_REPORT = 1; Section 7.2.5
 
HID Report types
USB_HID_REPORT_INPUT = 1; Section 7.2.1
USB_HID_REPORT_OUTPUT = 2; Section 7.2.1
USB_HID_REPORT_FEATURE = 3; Section 7.2.1
 
HID Report IDs
USB_HID_REPORTID_NONE = 0; Section 7.2.1
 
HID Boot Protocol Button bits
USB_HID_BOOT_LEFT_BUTTON = (1 shl 0);  
USB_HID_BOOT_RIGHT_BUTTON = (1 shl 1);  
USB_HID_BOOT_MIDDLE_BUTTON = (1 shl 2);  
USB_HID_BOOT_SIDE_BUTTON = (1 shl 3);  
USB_HID_BOOT_EXTRA_BUTTON = (1 shl 4);  
 
HID Boot Protocol Report data
USB_HID_BOOT_REPORT_SIZE = 3; Appendix B of HID Device Class Definition 1.11
USB_HID_BOOT_DATA_SIZE = 8; Allocate more than the minimum to allow for extra data


Type definitions


USB HID descriptor

PUSBHIDDescriptor = ^TUSBHIDDescriptor;

TUSBHIDDescriptor = packed record

bLength:Byte;  
bDescriptorType:Byte;  
bcdHID:Word;  
bCountryCode:Byte;  
bNumDescriptors:Byte;  
bHIDDescriptorType:Byte;  
wHIDDescriptorLength:Word;  
Note: Up to two optional bHIDDescriptorType/wHIDDescriptorLength pairs after the Report descriptor details

USB mouse device

PUSBMouseDevice = ^TUSBMouseDevice;

TUSBMouseDevice = record

Mouse Properties
Mouse:TMouseDevice;  
USB Properties
HIDInterface:PUSBInterface; USB HID Mouse Interface
ReportRequest:PUSBRequest; USB request for mouse report data
ReportEndpoint:PUSBEndpointDescriptor; USB Mouse Interrupt IN Endpoint
HIDDescriptor:PUSBHIDDescriptor; USB HID Descriptor for mouse
ReportDescriptor:Pointer; USB HID Report Descriptor for mouse
PendingCount:LongWord; Number of USB requests pending for this mouse
WaiterThread:TThreadId; Thread waiting for pending requests to complete (for mouse detachment)


Public variables

None defined

Function declarations


Initialization functions 

procedure USBMouseInit;
Description: Initialize the USB mouse driver
Note Called only during system startup


USB mouse functions 

function USBMouseDriverBind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Bind the Mouse driver to a USB device if it is suitable
Device The USB device to attempt to bind to
Interrface The USB interface to attempt to bind to (or nil for whole device)
Return USB_STATUS_SUCCESS if completed, USB_STATUS_DEVICE_UNSUPPORTED if unsupported or another error code on failure. 


function USBMouseDriverUnbind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Unbind the Mouse driver from a USB device
Device The USB device to unbind from
Interrface The USB interface to unbind from (or nil for whole device)
Return USB_STATUS_SUCCESS if completed or another error code on failure 


procedure USBMouseReportWorker(Request:PUSBRequest);
Description: Called (by a Worker thread) to process a completed USB request from a USB mouse IN interrupt endpoint
Request The USB request which has completed 


procedure USBMouseReportComplete(Request:PUSBRequest);
Description: Called when a USB request from a USB mouse IN interrupt endpoint completes
Request The USB request which has completed
Note Request is passed to worker thread for processing to prevent blocking the USB completion


USB mouse helper functions 

function USBMouseCheckDevice(Device:PUSBDevice):Boolean;
Description: Check if the supplied USB device is suitable for detection as a HID Mouse Device
Device The USB device to check
Return True if the device is suitable or False if it is not 


function USBMouseDeviceSetProtocol(Mouse:PUSBMouseDevice; Protocol:Byte):LongWord;
Description: Set the report protocol for a USB mouse device
Mouse The USB mouse device to set the report protocol for
Protocol The report protocol to set (eg USB_HID_PROTOCOL_BOOT)
Return USB_STATUS_SUCCESS if completed or another USB error code on failure 


function USBMouseDeviceGetHIDDescriptor(Mouse:PUSBMouseDevice; Descriptor:PUSBHIDDescriptor):LongWord;
Description: Get the HID Descriptor for a USB mouse device
Mouse The USB mouse device to get the descriptor for
Descriptor Pointer to a USB HID Descriptor structure for the returned data
Return USB_STATUS_SUCCESS if completed or another USB error code on failure 


function USBMouseDeviceGetReportDescriptor(Mouse:PUSBMouseDevice; Descriptor:Pointer; Size:LongWord):LongWord;
Description: Get the Report Descriptor for a USB mouse device
Mouse The USB mouse device to get the descriptor for
Descriptor Pointer to a buffer to return the USB Report Descriptor
Size The size in bytes of the buffer pointed to by Descriptor
Return USB_STATUS_SUCCESS if completed or another USB error code on failure


Return to Unit Reference

Retrieved from "https://ultibo.org/mediawiki_ultibo_org/index.php?title=Unit_USBMOUSE&oldid=5603"