LUFA Library  210130
HID Class Host Mode Driver

Data Structures

struct  USB_ClassInfo_HID_Host_t
 HID Class Host Mode Configuration and State Structure. More...
 

Macros

#define HID_ERROR_LOGICAL   0x80
 

Enumerations

enum  HID_Host_EnumerationFailure_ErrorCodes_t {
  HID_ENUMERROR_NoError = 0 ,
  HID_ENUMERROR_InvalidConfigDescriptor = 1 ,
  HID_ENUMERROR_NoCompatibleInterfaceFound = 2 ,
  HID_ENUMERROR_PipeConfigurationFailed = 3
}
 

Functions

uint8_t HID_Host_ConfigurePipes (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo, uint16_t ConfigDescriptorSize, void *ConfigDescriptorData) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3)
 
bool HID_Host_IsReportReceived (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)
 
uint8_t HID_Host_ReceiveReport (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo, void *Buffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2)
 
uint8_t HID_Host_ReceiveReportByID (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo, const uint8_t ReportID, void *Buffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3)
 
uint8_t HID_Host_SendReportByID (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo, const uint8_t ReportID, const uint8_t ReportType, void *Buffer, const uint16_t ReportSize) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(4)
 
uint8_t HID_Host_SetBootProtocol (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)
 
uint8_t HID_Host_SetIdlePeriod (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo, const uint16_t MS) ATTR_NON_NULL_PTR_ARG(1)
 
uint8_t HID_Host_SetReportProtocol (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)
 
static void HID_Host_USBTask (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)
 

Detailed Description

Module Source Dependencies

The following files must be built with any user project that uses this module:

Module Description

Host Mode USB Class driver framework interface, for the HID USB Class driver.

Macro Definition Documentation

◆ HID_ERROR_LOGICAL

#define HID_ERROR_LOGICAL   0x80

Error code for some HID Host functions, indicating a logical (and not hardware) error.

Enumeration Type Documentation

◆ HID_Host_EnumerationFailure_ErrorCodes_t

Enum for the possible error codes returned by the HID_Host_ConfigurePipes() function.

Enumerator
HID_ENUMERROR_NoError 

Configuration Descriptor was processed successfully.

HID_ENUMERROR_InvalidConfigDescriptor 

The device returned an invalid Configuration Descriptor.

HID_ENUMERROR_NoCompatibleInterfaceFound 

A compatible HID interface was not found in the device's Configuration Descriptor.

HID_ENUMERROR_PipeConfigurationFailed 

One or more pipes for the specified interface could not be configured correctly.

Function Documentation

◆ HID_Host_ConfigurePipes()

uint8_t HID_Host_ConfigurePipes ( USB_ClassInfo_HID_Host_t *const  HIDInterfaceInfo,
uint16_t  ConfigDescriptorSize,
void *  ConfigDescriptorData 
)

Host interface configuration routine, to configure a given HID host interface instance using the Configuration Descriptor read from an attached USB device. This function automatically updates the given HID Host instance's state values and configures the pipes required to communicate with the interface if it is found within the device. This should be called once after the stack has enumerated the attached device, while the host state machine is in the Addressed state.

Attention
Once the device pipes are configured, the HID device's reporting protocol must be set via a call to either the HID_Host_SetBootProtocol() or HID_Host_SetReportProtocol() function.
Parameters
[in,out]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.
[in]ConfigDescriptorSizeLength of the attached device's Configuration Descriptor.
[in]ConfigDescriptorDataPointer to a buffer containing the attached device's Configuration Descriptor.
Returns
A value from the HID_Host_EnumerationFailure_ErrorCodes_t enum.

◆ HID_Host_IsReportReceived()

bool HID_Host_IsReportReceived ( USB_ClassInfo_HID_Host_t *const  HIDInterfaceInfo)

Determines if a HID IN report has been received from the attached device on the data IN pipe.

Precondition
This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.
Parameters
[in,out]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.
Returns
Boolean true if a report has been received, false otherwise.

◆ HID_Host_ReceiveReport()

uint8_t HID_Host_ReceiveReport ( USB_ClassInfo_HID_Host_t *const  HIDInterfaceInfo,
void *  Buffer 
)

Receives a HID IN report from the attached HID device, when a report has been received on the HID IN Data pipe.

Precondition
This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.
Attention
The destination buffer should be large enough to accommodate the largest report that the attached device can generate.
Parameters
[in,out]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.
[in]BufferBuffer to store the received report into.
Returns
An error code from the Pipe_Stream_RW_ErrorCodes_t enum.

◆ HID_Host_ReceiveReportByID()

uint8_t HID_Host_ReceiveReportByID ( USB_ClassInfo_HID_Host_t *const  HIDInterfaceInfo,
const uint8_t  ReportID,
void *  Buffer 
)

Receives a HID IN report from the attached device, by the report ID.

Precondition
This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.
Note
When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method is unavailable.
Parameters
[in,out]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.
[in]ReportIDReport ID of the received report if ControlRequest is false, set by the to the Report ID to fetch.
[in]BufferBuffer to store the received report into.
Returns
A value from the USB_Host_SendControlErrorCodes_t enum.

◆ HID_Host_SendReportByID()

uint8_t HID_Host_SendReportByID ( USB_ClassInfo_HID_Host_t *const  HIDInterfaceInfo,
const uint8_t  ReportID,
const uint8_t  ReportType,
void *  Buffer,
const uint16_t  ReportSize 
)

Sends an OUT or FEATURE report to the currently attached HID device, using the device's OUT pipe if available, or the device's Control pipe if not.

Precondition
This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.
Note
When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, the ReportID parameter is removed from the parameter list of this function.
Parameters
[in,out]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.
[in]ReportIDReport ID of the report to send to the device, or 0 if the device does not use report IDs.
[in]ReportTypeType of report to issue to the device, either HID_REPORT_ITEM_Out or HID_REPORT_ITEM_Feature.
[in]BufferBuffer containing the report to send to the attached device.
[in]ReportSizeReport size in bytes to send to the attached device.
Returns
An error code from the USB_Host_SendControlErrorCodes_t enum if the DeviceUsesOUTPipe flag is set in the interface's state structure, a value from the Pipe_Stream_RW_ErrorCodes_t enum otherwise.

◆ HID_Host_SetBootProtocol()

uint8_t HID_Host_SetBootProtocol ( USB_ClassInfo_HID_Host_t *const  HIDInterfaceInfo)

Switches the attached HID device's reporting protocol over to the Boot Report protocol mode, on supported devices.

Note
When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method must still be called to explicitly place the attached device into boot protocol mode before use.
Parameters
[in,out]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.
Returns
HID_ERROR_LOGICAL if the device does not support Boot Protocol mode, a value from the USB_Host_SendControlErrorCodes_t enum otherwise.

◆ HID_Host_SetIdlePeriod()

uint8_t HID_Host_SetIdlePeriod ( USB_ClassInfo_HID_Host_t *const  HIDInterfaceInfo,
const uint16_t  MS 
)

Sets the idle period for the attached HID device to the specified interval. The HID idle period determines the rate at which the device should send a report, when no state changes have occurred; i.e. on HID keyboards, this sets the hardware key repeat interval.

Parameters
[in,out]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.
[in]MSIdle period as a multiple of four milliseconds, zero to disable hardware repeats
Returns
A value from the USB_Host_SendControlErrorCodes_t enum.

◆ HID_Host_SetReportProtocol()

uint8_t HID_Host_SetReportProtocol ( USB_ClassInfo_HID_Host_t *const  HIDInterfaceInfo)

Switches the attached HID device's reporting protocol over to the standard Report protocol mode. This also retrieves and parses the device's HID report descriptor, so that the size of each report can be determined in advance.

Attention
Whether this function is used or not, the CALLBACK_HIDParser_FilterHIDReportItem() callback from the HID Report Parser this function references must be implemented in the user code.
Note
When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method is unavailable.
Parameters
[in,out]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.
Returns
A value from the USB_Host_SendControlErrorCodes_t enum if an error occurs while retrieving the HID Report descriptor or the setting of the Report protocol, HID_ERROR_LOGICAL if the HID interface does not have a valid HID_ReportInfo_t structure set in its configuration, a mask of HID_ERROR_LOGICAL and a value from the HID_Parse_ErrorCodes_t otherwise.

◆ HID_Host_USBTask()

static void HID_Host_USBTask ( USB_ClassInfo_HID_Host_t *const  HIDInterfaceInfo)
inlinestatic

General management task for a given Human Interface Class host class interface, required for the correct operation of the interface. This should be called frequently in the main program loop, before the master USB management task USB_USBTask().

Parameters
[in,out]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.