Unit USBKEYBOARD

From Ultibo.org
Revision as of 03:17, 17 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 Keyboard Driver unit

USB Keyboard Devices

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

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

HID_REGISTER_KEYBOARD := False;
USB_KEYBOARD_REGISTER_DRIVER := True;

This driver does not recognize devices that do not report themselves as boot keyboards.

Constants


USB keyboard specific constants NAME_*
USBKEYBOARD_DRIVER_NAME = 'USB Keyboard Driver (HID boot protocol)'; Name of USB keyboard driver
USBKEYBOARD_KEYBOARD_DESCRIPTION = 'USB HID Keyboard'; Description of USB keyboard device


USB HID interface subclass USB_HID_SUBCLASS_*
See USB HID v1.11 specification
 
USB_HID_SUBCLASS_NONE = 0; Section 4.2
USB_HID_SUBCLASS_BOOT = 1; Section 4.2


USB HID interface protocol USB_HID_BOOT_PROTOCOL_*
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


USB HID class descriptor USB_HID_DESCRIPTOR_*
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


USB HID request USB_HID_REQUEST_*
See USB HID v1.11 specification
 
USB_HID_REQUEST_GET_REPORT = $01; Section 7.2
USB_HID_REQUEST_GET_IDLE = $02; Section 7.2
USB_HID_REQUEST_GET_PROTOCOL = $03; Section 7.2
USB_HID_REQUEST_SET_REPORT = $09; Section 7.2
USB_HID_REQUEST_SET_IDLE = $0A; Section 7.2
USB_HID_REQUEST_SET_PROTOCOL = $0B; Section 7.2


USB HID protocol USB_HID_PROTOCOL_*
See USB HID v1.11 specification
 
USB_HID_PROTOCOL_BOOT = 0; Section 7.2.5
USB_HID_PROTOCOL_REPORT = 1; Section 7.2.5


USB HID report USB_HID_REPORT_*
See USB HID v1.11 specification
 
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


USB HID report Ids USB_HID_REPORTID_*
See USB HID v1.11 specification
 
USB_HID_REPORTID_NONE = 0; Section 7.2.1


USB HID boot protocol USB_HID_BOOT_LEFT_*, USB_HID_BOOT_RIGHT_*
USB_HID_BOOT_LEFT_CTRL = (1 shl 0);  
USB_HID_BOOT_LEFT_SHIFT = (1 shl 1);  
USB_HID_BOOT_LEFT_ALT = (1 shl 2);  
USB_HID_BOOT_LEFT_GUI = (1 shl 3);  
USB_HID_BOOT_RIGHT_CTRL = (1 shl 4);  
USB_HID_BOOT_RIGHT_SHIFT = (1 shl 5);  
USB_HID_BOOT_RIGHT_ALT = (1 shl 6);  
USB_HID_BOOT_RIGHT_GUI = (1 shl 7);  


USB HID boot protocol report data USB_HID_BOOT_REPORT_*
USB_HID_BOOT_REPORT_SIZE = 8; Appendix B of HID Device Class Definition 1.11


USB HID boot protocol output USB_HID_BOOT_*_LED
USB_HID_BOOT_NUMLOCK_LED = (1 shl 0);  
USB_HID_BOOT_CAPSLOCK_LED = (1 shl 1);  
USB_HID_BOOT_SCROLLLOCK_LED = (1 shl 2);  
USB_HID_BOOT_COMPOSE_LED = (1 shl 3);  
USB_HID_BOOT_KANA_LED = (1 shl 4);  
 
USB_HID_BOOT_LEDMASK = USB_HID_BOOT_NUMLOCK_LED or USB_HID_BOOT_CAPSLOCK_LED or USB_HID_BOOT_SCROLLLOCK_LED or USB_HID_BOOT_COMPOSE_LED or USB_HID_BOOT_KANA_LED;  


USB HID boot protocol output data USB_HID_BOOT_OUTPUT_*
USB_HID_BOOT_OUTPUT_SIZE = 1; Appendix B of HID Device Class Definition 1.11
 
USB_HID_BOOT_USAGE_NUMLOCK = SCAN_CODE_NUMLOCK; 83
USB_HID_BOOT_USAGE_CAPSLOCK = SCAN_CODE_CAPSLOCK; 57
USB_HID_BOOT_USAGE_SCROLLLOCK = SCAN_CODE_SCROLLLOCK; 71


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 boot keyboard report

PUSBKeyboardReport = ^TUSBKeyboardReport;

TUSBKeyboardReport = array[0..7] of Byte;

   

USB keyboard device

PUSBKeyboardDevice = ^TUSBKeyboardDevice;

TUSBKeyboardDevice = record

Keyboard Properties
Keyboard:TKeyboardDevice;  
USB Properties
HIDInterface:PUSBInterface; USB HID Keyboard Interface
ReportRequest:PUSBRequest; USB request for keyboard report data
ReportEndpoint:PUSBEndpointDescriptor; USB Keyboard Interrupt IN Endpoint
HIDDescriptor:PUSBHIDDescriptor; USB HID Descriptor for keyboard
ReportDescriptor:Pointer; USB HID Report Descriptor for keyboard
LastCode:Word; The scan code of the last key pressed
LastCount:LongWord; The repeat count of the last key pressed
LastReport:TUSBKeyboardReport; The last keyboard report received
PendingCount:LongWord; Number of USB requests pending for this keyboard
WaiterThread:TThreadId; Thread waiting for pending requests to complete (for keyboard detachment)


Public variables

None defined

Function declarations


Initialization functions 

procedure USBKeyboardInit;
Description: Initialize the USB keyboard driver
Note Called only during system startup


USB keyboard functions 

function USBKeyboardDeviceRead(Keyboard:PKeyboardDevice; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Implementation of KeyboardDeviceRead API for USB Keyboard
Note Not intended to be called directly by applications, use KeyboardDeviceRead instead. 


function USBKeyboardDeviceControl(Keyboard:PKeyboardDevice; Request:Integer; Argument1:PtrUInt; var Argument2:PtrUInt):LongWord;
Description: Implementation of KeyboardDeviceControl API for USB Keyboard
Note Not intended to be called directly by applications, use KeyboardDeviceControl instead. 


function USBKeyboardDriverBind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Bind the Keyboard 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 USBKeyboardDriverUnbind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Unbind the Keyboard 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 USBKeyboardReportWorker(Request:PUSBRequest);
Description: Called (by a Worker thread) to process a completed USB request from a USB keyboard IN interrupt endpoint
Request The USB request which has completed 


procedure USBKeyboardReportComplete(Request:PUSBRequest);
Description: Called when a USB request from a USB keyboard 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 helper functions 

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


function USBKeyboardCheckPressed(Keyboard:PUSBKeyboardDevice; ScanCode:Byte):Boolean;
Description: Check if the passed scan code has been pressed (True if not pressed in last report)
Keyboard The USB keyboard device to check for
ScanCode The keyboard scan code to check
Note Caller must hold the keyboard lock 


function USBKeyboardCheckRepeated(Keyboard:PUSBKeyboardDevice; ScanCode:Byte):Boolean;
Description: Check if the passed scan code was the last key pressed and if the repeat delay has expired
Keyboard The USB keyboard device to check for
ScanCode The keyboard scan code to check
Note Caller must hold the keyboard lock 


function USBKeyboardCheckReleased(Keyboard:PUSBKeyboardDevice; Report:PUSBKeyboardReport; ScanCode:Byte):Boolean;
Description: Check if the passed scan code has been released (True if not pressed in current report)
Keyboard The USB keyboard device to check for
Report The USB keyboard report to compare against (Current)
ScanCode The keyboard scan code to check
Note Caller must hold the keyboard lock 


function USBKeyboardDeviceSetLEDs(Keyboard:PUSBKeyboardDevice; LEDs:Byte):LongWord;
Description: Set the state of the LEDs for a USB keyboard device
Keyboard The USB keyboard device to set the LEDs for
LEDs The LED state to set (eg KEYBOARD_LED_NUMLOCK)
Return USB_STATUS_SUCCESS if completed or another USB error code on failure 


function USBKeyboardDeviceSetIdle(Keyboard:PUSBKeyboardDevice; Duration,ReportId:Byte):LongWord;
Description: Set the idle duration (Time between reports when no changes) for a USB keyboard device
Keyboard The USB keyboard device to set the idle duration for
Duration The idle duration to set (Milliseconds divided by 4)
ReportId The report Id to set the idle duration for (eg USB_HID_REPORTID_NONE)
Return USB_STATUS_SUCCESS if completed or another USB error code on failure 


function USBKeyboardDeviceSetProtocol(Keyboard:PUSBKeyboardDevice; Protocol:Byte):LongWord;
Description: Set the report protocol for a USB keyboard device
Keyboard The USB keyboard 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 USBKeyboardDeviceGetHIDDescriptor(Keyboard:PUSBKeyboardDevice; Descriptor:PUSBHIDDescriptor):LongWord;
Description: Get the HID Descriptor for a USB keyboard device
Keyboard The USB keyboard device to get the descriptor for
Descriptor Pointer to a USB HID Descriptor structure for the returned data
Descriptor USB_STATUS_SUCCESS if completed or another USB error code on failure 


function USBKeyboardDeviceGetReportDescriptor(Keyboard:PUSBKeyboardDevice; Descriptor:Pointer; Size:LongWord):LongWord;
Description: Get the Report Descriptor for a USB keyboard device
Keyboard The USB keyboard 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_USBKEYBOARD&oldid=5614"