USBLib API Guide
1.00.00.01
|
Data Structures | |
struct | tHIDKeyboardInstance |
struct | tUSBDHIDKeyboardDevice |
Macros | |
#define | NUM_HID_SECTIONS |
#define | KEYB_MAX_CHARS_PER_REPORT 6 |
#define | KEYB_IN_REPORT_SIZE 8 |
#define | KEYB_OUT_REPORT_SIZE 1 |
#define | USBD_HID_KEYB_EVENT_SET_LEDS USBD_HID_KEYB_EVENT_BASE |
#define | KEYB_SUCCESS 0 |
This return code from USBDHIDKeyboardKeyStateChange() indicates success. More... | |
#define | KEYB_ERR_TOO_MANY_KEYS 1 |
#define | KEYB_ERR_TX_ERROR 2 |
#define | KEYB_ERR_NOT_FOUND 3 |
#define | KEYB_ERR_NOT_CONFIGURED 4 |
Enumerations | |
enum | tKeyboardState { HID_KEYBOARD_STATE_UNCONFIGURED, HID_KEYBOARD_STATE_IDLE, HID_KEYBOARD_STATE_WAIT_DATA, HID_KEYBOARD_STATE_SEND } |
Functions | |
void * | USBDHIDKeyboardInit (uint32_t ui32Index, tUSBDHIDKeyboardDevice *psHIDKbDevice) |
void * | USBDHIDKeyboardCompositeInit (uint32_t ui32Index, tUSBDHIDKeyboardDevice *psHIDKbDevice, tCompositeEntry *psCompEntry) |
void | USBDHIDKeyboardTerm (void *pvKeyboardDevice) |
void * | USBDHIDKeyboardSetCBData (void *pvKeyboardDevice, void *pvCBData) |
uint32_t | USBDHIDKeyboardKeyStateChange (void *pvKeyboardDevice, uint8_t ui8Modifiers, uint8_t ui8UsageCode, bool bPress) |
void | USBDHIDKeyboardPowerStatusSet (void *pvKeyboardDevice, uint8_t ui8Power) |
bool | USBDHIDKeyboardRemoteWakeupRequest (void *pvKeyboardDevice) |
#define NUM_HID_SECTIONS |
#define KEYB_MAX_CHARS_PER_REPORT 6 |
The maximum number of simultaneously-pressed, non-modifier keys that the HID BIOS keyboard protocol can send at once. Attempts to send more pressed keys than this results in a rollover error being reported to the host and KEYB_ERR_TOO_MANY_KEYS being returned from USBDHIDKeyboardKeyStateChange().
Referenced by USBDHIDKeyboardCompositeInit().
#define KEYB_IN_REPORT_SIZE 8 |
#define KEYB_OUT_REPORT_SIZE 1 |
#define USBD_HID_KEYB_EVENT_SET_LEDS USBD_HID_KEYB_EVENT_BASE |
This event indicates that the keyboard LED states are to be set. The ui32MsgValue parameter contains the requested state for each of the LEDs defined as a collection of ORed bits where a 1 indicates that the LED is to be turned on and a 0 indicates that it should be turned off. The individual LED bits are defined using labels HID_KEYB_NUM_LOCK, HID_KEYB_CAPS_LOCK, HID_KEYB_SCROLL_LOCK, HID_KEYB_COMPOSE and HID_KEYB_KANA.
#define KEYB_SUCCESS 0 |
This return code from USBDHIDKeyboardKeyStateChange() indicates success.
#define KEYB_ERR_TOO_MANY_KEYS 1 |
This return code from USBDHIDKeyboardKeyStateChange() indicates that an attempt has been made to record more than 6 simultaneously pressed, non-modifier keys. The USB HID BIOS keyboard protocol allows no more than 6 pressed keys to be reported at one time. Until at least one key is released, the device reports a roll over error to the host each time it is asked for the keyboard input report.
#define KEYB_ERR_TX_ERROR 2 |
This return code from USBDHIDKeyboardKeyStateChange() indicates that an error was reported while attempting to send a report to the host. A client should assume that the host has disconnected if this return code is seen.
#define KEYB_ERR_NOT_FOUND 3 |
USBDHIDKeyboardKeyStateChange() returns this value if it is called with the bPress parameter set to false but with a ui8UsageCode parameter which does does not indicate a key that is currently recorded as being pressed. This may occur if an attempt was previously made to report more than 6 pressed keys and the earlier pressed keys are released before the later ones. This condition is benign and should not be used to indicate a host disconnection or serious error.
#define KEYB_ERR_NOT_CONFIGURED 4 |
USBDHIDKeyboardKeyStateChange() returns this value if it is called before the USB host has connected and configured the device. Any key usage code passed is stored and passed to the host once configuration completes.
enum tKeyboardState |
void * USBDHIDKeyboardInit | ( | uint32_t | ui32Index, |
tUSBDHIDKeyboardDevice * | psHIDKbDevice | ||
) |
Initializes HID keyboard device operation for a given USB controller.
ui32Index | is the index of the USB controller which is to be initialized for HID keyboard device operation. |
psHIDKbDevice | points to a structure containing parameters customizing the operation of the HID keyboard device. |
An application wishing to offer a USB HID keyboard interface to a USB host must call this function to initialize the USB controller and attach the keyboard device to the USB bus. This function performs all required USB initialization.
On successful completion, this function returns the psHIDKbDevice pointer passed to it. This must be passed on all future calls to the HID keyboard device driver.
When a host connects and configures the device, the application callback receives USB_EVENT_CONNECTED after which calls can be made to USBDHIDKeyboardKeyStateChange() to report key presses and releases to the USB host.
References tUSBDHIDKeyboardDevice::pfnCallback, tUSBDHIDKeyboardDevice::ppui8StringDescriptors, tHIDKeyboardInstance::sHIDDevice, tUSBDHIDKeyboardDevice::sPrivateData, and USBDHIDKeyboardCompositeInit().
void * USBDHIDKeyboardCompositeInit | ( | uint32_t | ui32Index, |
tUSBDHIDKeyboardDevice * | psHIDKbDevice, | ||
tCompositeEntry * | psCompEntry | ||
) |
Initializes HID keyboard device operation for a given USB controller.
ui32Index | is the index of the USB controller which is to be initialized for HID keyboard device operation. |
psHIDKbDevice | points to a structure containing parameters customizing the operation of the HID keyboard device. |
psCompEntry | is the composite device entry to initialize when creating a composite device. |
This call is very similar to USBDHIDKeyboardInit() except that it is used for initializing an instance of the HID keyboard device for use in a composite device. If this HID keyboard is part of a composite device, then the psCompEntry should point to the composite device entry to initialize. This is part of the array that is passed to the USBDCompositeInit() function.
References tHIDKeyboardInstance::eKeyboardState, HID_KEYB_USAGE_RESERVED, HID_KEYBOARD_STATE_UNCONFIGURED, KEYB_MAX_CHARS_PER_REPORT, tUSBDHIDKeyboardDevice::pfnCallback, tUSBDHIDDevice::pfnRxCallback, tUSBDHIDKeyboardDevice::ppui8StringDescriptors, tUSBDHIDDevice::psReportIdle, tHIDKeyboardInstance::pui8KeysPressed, tHIDKeyboardInstance::sHIDDevice, tUSBDHIDKeyboardDevice::sPrivateData, tHIDKeyboardInstance::sReportIdle, tUSBDHIDKeyboardDevice::ui16MaxPowermA, tUSBDHIDDevice::ui16MaxPowermA, tUSBDHIDKeyboardDevice::ui16PID, tUSBDHIDDevice::ui16PID, tHIDReportIdle::ui16TimeTillNextmS, tUSBDHIDKeyboardDevice::ui16VID, tUSBDHIDDevice::ui16VID, tHIDReportIdle::ui32TimeSinceReportmS, tHIDReportIdle::ui8Duration4mS, tHIDKeyboardInstance::ui8KeyCount, tHIDKeyboardInstance::ui8LEDStates, tUSBDHIDDevice::ui8NumInputReports, tHIDKeyboardInstance::ui8Protocol, tUSBDHIDDevice::ui8Protocol, tUSBDHIDKeyboardDevice::ui8PwrAttributes, tUSBDHIDDevice::ui8PwrAttributes, tHIDReportIdle::ui8ReportID, tUSBDHIDDevice::ui8Subclass, tHIDKeyboardInstance::ui8USBConfigured, USB_HID_PROTOCOL_KEYB, USB_HID_PROTOCOL_REPORT, and USB_HID_SCLASS_BOOT.
Referenced by USBDHIDKeyboardInit().
void USBDHIDKeyboardTerm | ( | void * | pvKeyboardDevice | ) |
Shuts down the HID keyboard device.
pvKeyboardDevice | is the pointer to the device instance structure as returned by USBDHIDKeyboardInit(). |
This function terminates HID keyboard operation for the instance supplied and removes the device from the USB bus. Following this call, the pvKeyboardDevice instance may not me used in any other call to the HID keyboard device other than USBDHIDKeyboardInit().
References tHIDKeyboardInstance::sHIDDevice, tUSBDHIDKeyboardDevice::sPrivateData, tHIDKeyboardInstance::ui8USBConfigured, and USBDHIDTerm().
void * USBDHIDKeyboardSetCBData | ( | void * | pvKeyboardDevice, |
void * | pvCBData | ||
) |
Sets the client-specific pointer parameter for the keyboard callback.
pvKeyboardDevice | is the pointer to the device instance structure as returned by USBDHIDKeyboardInit(). |
pvCBData | is the pointer that client wishes to be provided on each event sent to the keyboard callback function. |
The client uses this function to change the callback pointer passed in the first parameter on all callbacks to the pfnCallback function passed on USBDHIDKeyboardInit().
If a client wants to make runtime changes in the callback pointer, it must ensure that the pvKeyboardDevice structure passed to USBDHIDKeyboardInit() resides in RAM. If this structure is in flash, callback data changes is not possible.
References tUSBDHIDKeyboardDevice::pvCBData.
uint32_t USBDHIDKeyboardKeyStateChange | ( | void * | pvKeyboardDevice, |
uint8_t | ui8Modifiers, | ||
uint8_t | ui8UsageCode, | ||
bool | bPress | ||
) |
Reports a key state change to the USB host.
pvKeyboardDevice | is the pointer to the device instance structure as returned by USBDHIDKeyboardInit(). |
ui8Modifiers | contains the states of each of the keyboard modifiers (left/right shift, ctrl, alt or GUI keys). Valid values are logical OR combinations of the labels HID_KEYB_LEFT_CTRL, HID_KEYB_LEFT_SHIFT, HID_KEYB_LEFT_ALT, HID_KEYB_LEFT_GUI, HID_KEYB_RIGHT_CTRL, HID_KEYB_RIGHT_SHIFT, HID_KEYB_RIGHT_ALT and HID_KEYB_RIGHT_GUI. Presence of one of these bit flags indicates that the relevant modifier key is pressed and absence indicates that it is released. |
ui8UsageCode | is the usage code of the key whose state has changed. If only modifier keys have changed, HID_KEYB_USAGE_RESERVED should be passed in this parameter. |
bPress | is true if the key has been pressed or false if it has been released. If only modifier keys have changed state, this parameter is ignored. |
This function adds or removes a key usage code from the list of keys currently pressed and schedules a report transmission to the host to inform it of the new keyboard state. If the maximum number of simultaneous key presses are already recorded, the report to the host contains the rollover error code, HID_KEYB_USAGE_ROLLOVER instead of key usage codes and the caller receives return code KEYB_ERR_TOO_MANY_KEYS.
References HID_KEYB_USAGE_RESERVED, tHIDKeyboardInstance::pui8Report, tHIDKeyboardInstance::sHIDDevice, and tUSBDHIDKeyboardDevice::sPrivateData.
void USBDHIDKeyboardPowerStatusSet | ( | void * | pvKeyboardDevice, |
uint8_t | ui8Power | ||
) |
Reports the device power status (bus or self powered) to the USB library.
pvKeyboardDevice | is the pointer to the keyboard device instance structure. |
ui8Power | indicates the current power status, either USB_STATUS_SELF_PWR or USB_STATUS_BUS_PWR. |
Applications which support switching between bus or self powered operation should call this function whenever the power source changes to indicate the current power status to the USB library. This information is required by the USB library to allow correct responses to be provided when the host requests status from the device.
References tHIDKeyboardInstance::sHIDDevice, tUSBDHIDKeyboardDevice::sPrivateData, and USBDHIDPowerStatusSet().
bool USBDHIDKeyboardRemoteWakeupRequest | ( | void * | pvKeyboardDevice | ) |
Requests a remote wake up to resume communication when in suspended state.
pvKeyboardDevice | is the pointer to the keyboard device instance structure. |
When the bus is suspended, an application which supports remote wake up (advertised to the host via the configuration descriptor) may call this function to initiate remote wake up signaling to the host. If the remote wake up feature has not been disabled by the host, this causes the bus to resume operation within 20mS. If the host has disabled remote wake up, false is returned to indicate that the wake up request was not successful.
References tHIDKeyboardInstance::sHIDDevice, tUSBDHIDKeyboardDevice::sPrivateData, and USBDHIDRemoteWakeupRequest().