Unit USBKEYBOARD
From Ultibo.org
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:LongWord; var Argument2:LongWord):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
