| LPCOpen Platform v1.03 LPCOpen Platform for NXP LPC Microcontrollers

- Main Page
- Modules
- Data Structures
- Files
- Related Pages

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Enumerations | Functions
HID Class Host Mode Driver
HID Class Driver

## Detailed Description

# Module Source Dependencies

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

- LPCUSBlib/Drivers/USB/Class/Host/HID.c (Makefile source module name: LPCUSBlib_SRC_USBCLASS)

# Module Description

Host Mode USB Class driver framework interface, for the HID USB Class 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 *DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3)
| 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.
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)
| Receives a HID IN report from the attached HID device, when a report has been received on the HID IN Data pipe.
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)
| Receives a HID IN report from the attached device, by the report ID.
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)
| 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.
bool | HID_Host_IsReportReceived (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)
| Determines if a HID IN report has been received from the attached device on the data IN pipe.
uint8_t | HID_Host_SetBootProtocol (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)
| Switches the attached HID device's reporting protocol over to the Boot Report protocol mode, on supported devices.
uint8_t | HID_Host_SetIdlePeriod (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo, const uint16_t MS) ATTR_NON_NULL_PTR_ARG(1)
| 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 ocurred; i.e. on HID keyboards, this sets the hardware key repeat interval.
uint8_t | HID_Host_SetReportProtocol (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)
| 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.
static void | HID_Host_USBTask (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)
| 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().

## Macro Definition Documentation

#define HID_ERROR_LOGICAL 0x80

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

Definition at line 66 of file HIDClassHost.h.

## Enumeration Type Documentation

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

Definition at line 132 of file HIDClassHost.h.

## Function Documentation

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

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.

Note
  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

  HIDInterfaceInfo | : Pointer to a structure containing a HID Class host configuration and state.
  ConfigDescriptorSize | : Length of the attached device's Configuration Descriptor.
  DeviceConfigDescriptor | : Pointer to a buffer containing the attached device's Configuration Descriptor.

Returns
  A value from the HID_Host_EnumerationFailure_ErrorCodes_t enum.

Definition at line 43 of file HIDClassHost.c.

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

  HIDInterfaceInfo | : Pointer to a structure containing a HID Class host configuration and state.

Returns
  Boolean `true` if a report has been received, `false` otherwise.

Definition at line 322 of file HIDClassHost.c.

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.

Note
  The destination buffer should be large enough to accommodate the largest report that the attached device can generate.

Parameters

  HIDInterfaceInfo | : Pointer to a structure containing a HID Class host configuration and state.
  Buffer | : Buffer to store the received report into.

Returns
  An error code from the Pipe_Stream_RW_ErrorCodes_t enum.

Definition at line 227 of file HIDClassHost.c.

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

  HIDInterfaceInfo | : Pointer to a structure containing a HID Class host configuration and state.
  ReportID | : Report ID of the received report if ControlRequest is false, set by the to the Report ID to fetch.
  Buffer | Buffer to store the received report into.

Returns
  A value from the USB_Host_SendControlErrorCodes_t enum.

Definition at line 207 of file HIDClassHost.c.

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

  HIDInterfaceInfo | : Pointer to a structure containing a HID Class host configuration and state.
  ReportID | : Report ID of the report to send to the device, or 0 if the device does not use report IDs.
  ReportType | : Type of report to issue to the device, either HID_REPORT_ITEM_Out or HID_REPORT_ITEM_Feature.
  Buffer | : Buffer containing the report to send to the attached device.
  ReportSize | : Report 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.

Definition at line 269 of file HIDClassHost.c.

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

  HIDInterfaceInfo | : Pointer 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.

Definition at line 340 of file HIDClassHost.c.

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 ocurred; i.e. on HID keyboards, this sets the hardware key repeat interval.

Parameters

  HIDInterfaceInfo | : Pointer to a structure containing a HID Class host configuration and state.
  MS | : Idle period as a multiple of four milliseconds, zero to disable hardware repeats

Returns
  A value from the USB_Host_SendControlErrorCodes_t enum.

Definition at line 368 of file HIDClassHost.c.

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.

Note
  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.
  When the `HID_HOST_BOOT_PROTOCOL_ONLY` compile time token is defined, this method is unavailable.

Parameters

  HIDInterfaceInfo | : Pointer 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.

Definition at line 387 of file HIDClassHost.c.

static void HID_Host_USBTask | ( | USB_ClassInfo_HID_Host_t *const | HIDInterfaceInfo | ) |
| inline static

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

  HIDInterfaceInfo | : Pointer to a structure containing a HID Class host configuration and state.

Returns
  Nothing

Definition at line 291 of file HIDClassHost.h.