Hid_keyboard_device_class_api

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)

Detailed Description

Macro Definition Documentation

NUM_HID_SECTIONS

#define NUM_HID_SECTIONS

Value:

((sizeof(g_psHIDSections) /                   \
                                  sizeof(g_psHIDSections[0])) - 1)

KEYB_MAX_CHARS_PER_REPORT

#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().

KEYB_IN_REPORT_SIZE

#define KEYB_IN_REPORT_SIZE   8

KEYB_OUT_REPORT_SIZE

#define KEYB_OUT_REPORT_SIZE   1

USBD_HID_KEYB_EVENT_SET_LEDS

#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.

KEYB_SUCCESS

#define KEYB_SUCCESS   0

This return code from USBDHIDKeyboardKeyStateChange() indicates success.

KEYB_ERR_TOO_MANY_KEYS

#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.

KEYB_ERR_TX_ERROR

#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.

KEYB_ERR_NOT_FOUND

#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.

KEYB_ERR_NOT_CONFIGURED

#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.

Enumeration Type Documentation

tKeyboardState

enum tKeyboardState

Enumerator
HID_KEYBOARD_STATE_UNCONFIGURED
HID_KEYBOARD_STATE_IDLE
HID_KEYBOARD_STATE_WAIT_DATA
HID_KEYBOARD_STATE_SEND

Function Documentation

USBDHIDKeyboardInit()

void * USBDHIDKeyboardInit	(	uint32_t	ui32Index,
		tUSBDHIDKeyboardDevice *	psHIDKbDevice
	)

Initializes HID keyboard device operation for a given USB controller.

Parameters

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.

Note

The application must not make any calls to the lower level USB device interfaces if interacting with USB via the USB HID keyboard device class API. Doing so causes unpredictable (though almost certainly unpleasant) behavior.

Returns

Returns NULL on failure or the psHIDKbDevice pointer on success.

References tUSBDHIDKeyboardDevice::pfnCallback, tUSBDHIDKeyboardDevice::ppui8StringDescriptors, tHIDKeyboardInstance::sHIDDevice, tUSBDHIDKeyboardDevice::sPrivateData, and USBDHIDKeyboardCompositeInit().

USBDHIDKeyboardCompositeInit()

void * USBDHIDKeyboardCompositeInit	(	uint32_t	ui32Index,
		tUSBDHIDKeyboardDevice *	psHIDKbDevice,
		tCompositeEntry *	psCompEntry
	)

Initializes HID keyboard device operation for a given USB controller.

Parameters

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.

Returns

Returns zero on failure or a non-zero instance value that should be used with the remaining USB HID Keyboard APIs.

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().

USBDHIDKeyboardTerm()

void USBDHIDKeyboardTerm

(

void *

pvKeyboardDevice

)

Shuts down the HID keyboard device.

Parameters

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().

Returns

None.

References tHIDKeyboardInstance::sHIDDevice, tUSBDHIDKeyboardDevice::sPrivateData, tHIDKeyboardInstance::ui8USBConfigured, and USBDHIDTerm().

USBDHIDKeyboardSetCBData()

void * USBDHIDKeyboardSetCBData	(	void *	pvKeyboardDevice,
		void *	pvCBData
	)

Sets the client-specific pointer parameter for the keyboard callback.

Parameters

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.

Returns

Returns the previous callback pointer that was set for this instance.

References tUSBDHIDKeyboardDevice::pvCBData.

USBDHIDKeyboardKeyStateChange()

uint32_t USBDHIDKeyboardKeyStateChange	(	void *	pvKeyboardDevice,
		uint8_t	ui8Modifiers,
		uint8_t	ui8UsageCode,
		bool	bPress
	)

Reports a key state change to the USB host.

Parameters

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.

Returns

Returns KEYB_SUCCESS if the key usage code was added to or removed from the current list successfully. KEYB_ERR_TOO_MANY_KEYS is returned if an attempt is made to press a 7th key (the BIOS keyboard protocol can report no more than 6 simultaneously pressed keys). If called before the USB host has configured the device, KEYB_ERR_NOT_CONFIGURED is returned and, if an error is reported while attempting to transmit the report, KEYB_ERR_TX_ERROR is returned. If an attempt is made to remove a key from the pressed list (by setting parameter bPressed to false) but the key usage code is not found, KEYB_ERR_NOT_FOUND is returned.

References HID_KEYB_USAGE_RESERVED, tHIDKeyboardInstance::pui8Report, tHIDKeyboardInstance::sHIDDevice, and tUSBDHIDKeyboardDevice::sPrivateData.

USBDHIDKeyboardPowerStatusSet()

void USBDHIDKeyboardPowerStatusSet	(	void *	pvKeyboardDevice,
		uint8_t	ui8Power
	)

Reports the device power status (bus or self powered) to the USB library.

Parameters

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.

Returns

None.

References tHIDKeyboardInstance::sHIDDevice, tUSBDHIDKeyboardDevice::sPrivateData, and USBDHIDPowerStatusSet().

USBDHIDKeyboardRemoteWakeupRequest()

bool USBDHIDKeyboardRemoteWakeupRequest

(

void *

pvKeyboardDevice

)

Requests a remote wake up to resume communication when in suspended state.

Parameters

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.

Returns

Returns true if the remote wake up is not disabled and the signaling was started or false if remote wake up is disabled or if signaling is currently ongoing following a previous call to this function.

References tHIDKeyboardInstance::sHIDDevice, tUSBDHIDKeyboardDevice::sPrivateData, and USBDHIDRemoteWakeupRequest().