Data Structures | Enumerations | Functions

USB HID Class Enumerations and Descriptors
[Public API]

Packet structs from the Device Class Definition for Human Interface Devices (commonly the USB HID Specification), version 1.11, chapter 6. More...

Data Structures

struct  hid_descriptor
struct  hid_optional_descriptor

Enumerations

enum  HIDDescriptorTypes { DESC_HID = 0x21, DESC_REPORT = 0x22, DESC_PHYSICAL = 0x23 }
 

HID Class Descriptor Tyes.


enum  HIDRequests {
  HID_GET_REPORT = 0x1, HID_GET_IDLE = 0x2, HID_GET_PROTOCOL = 0x3, HID_SET_REPORT = 0x9,
  HID_SET_IDLE = 0xa, HID_SET_PROTOCOL = 0xb
}
 

HID Class Requests.


enum  HIDReportTypes { HID_INPUT = 0x1, HID_OUTPUT = 0x2, HID_FEATURE = 0x3 }
 

HID Report Types.


enum  HIDProtocols { HID_PROTO_BOOT = 0, HID_PROTO_REPORT = 1 }
 

HID Protocols.


Functions

int16_t USB_HID_DESCRIPTOR_FUNC (uint8_t interface, const void **ptr)
 HID Descriptor Function.
int16_t USB_HID_REPORT_DESCRIPTOR_FUNC (uint8_t interface, const void **ptr)
 HID Report Descriptor Function.
int16_t USB_HID_PHYSICAL_DESCRIPTOR_FUNC (uint8_t interface, uint8_t index, const void **ptr)
 HID Physical Descriptor Function.
int16_t HID_GET_REPORT_CALLBACK (uint8_t interface, uint8_t report_type, uint8_t report_id, const void **report, usb_ep0_data_stage_callback *callback, void **context)
 HID Get_Report request callback.
int8_t HID_SET_REPORT_CALLBACK (uint8_t interface, uint8_t report_type, uint8_t report_id)
 HID Set_Report request callback.
uint8_t HID_GET_IDLE_CALLBACK (uint8_t interface, uint8_t report_id)
 HID Get_Idle request callback.
int8_t HID_SET_IDLE_CALLBACK (uint8_t interface, uint8_t report_id, uint8_t idle_rate)
 HID Set_Idle request callback.
int8_t HID_GET_PROTOCOL_CALLBACK (uint8_t interface)
 HID Get_Protocol request callback.
int8_t HID_SET_PROTOCOL_CALLBACK (uint8_t interface, uint8_t protocol)
 HID Set_Protocol request callback.
void hid_set_interface_list (uint8_t *interfaces, uint8_t num_interfaces)
 Set the list of HID interfaces on this device.
uint8_t process_hid_setup_request (const struct setup_packet *setup)
 Process HID Setup Request.

Detailed Description

Packet structs from the Device Class Definition for Human Interface Devices (commonly the USB HID Specification), version 1.11, chapter 6.

For more information about these structures, see the above referenced document, available from http://www.usb.org .


Function Documentation

uint8_t HID_GET_IDLE_CALLBACK ( uint8_t  interface,
uint8_t  report_id 
)

HID Get_Idle request callback.

The USB Stack will call this function when a Get_Idle request has been received from the host. The application should return the current idle rate.

Parameters:
interfaceThe interface for which the report is provided
report_idThe report index requested.
Returns:
Return the current idle rate.
int8_t HID_GET_PROTOCOL_CALLBACK ( uint8_t  interface )

HID Get_Protocol request callback.

The USB Stack will call this function when a Get_Protocol request has been received from the host. The application should return the current protocol.

Parameters:
interfaceThe interface for which the report is provided
Returns:
Return the current protocol (HID_PROTO_BOOT, HID_PROTO_REPORT) or -1 on failure.
int16_t HID_GET_REPORT_CALLBACK ( uint8_t  interface,
uint8_t  report_type,
uint8_t  report_id,
const void **  report,
usb_ep0_data_stage_callback callback,
void **  context 
)

HID Get_Report request callback.

The USB Stack will call this function when a Get_Report request has been received from the host. This function should set the report pointer to a buffer containing the report data and return the length of the report. Once the transfer has completed, callback will be called with the context pointer provided. The buffer pointed to by report should be considered to be owned by the USB stack until the callback is called and should not be modified by the application until that time.

Parameters:
interfaceThe interface for which the report is requested
report_typeThe type of report, either HID_INPUT, HID_OUTPUT, or HID_FEATURE.
report_idThe report index requested. This will be zero if the device does not use numbered reports.
reportA pointer to a pointer which should be set to the report data.
callbackA callback function to call when the transfer completes. This parameter is mandatory. Once the callback is called, the transfer is over, and the buffer can be considered to be owned by the application again.
contextA pointer to be passed to the callback. The USB stack does not dereference this pointer.
Returns:
Return the length of the report or -1 if the request is invalid. Returning -1 will cause STALL to be returned to the host.
int8_t HID_SET_IDLE_CALLBACK ( uint8_t  interface,
uint8_t  report_id,
uint8_t  idle_rate 
)

HID Set_Idle request callback.

The USB Stack will call this function when a Set_Idle request has been received from the host. The application should use the provided value as the idle rate.

Parameters:
interfaceThe interface for which the report is provided
report_idThe report index requested. Zero means all reports.
idle_rateThe idle rate to set, in multiples of 4 milliseconds.
Returns:
Return 0 on success and -1 on failure.
void hid_set_interface_list ( uint8_t *  interfaces,
uint8_t  num_interfaces 
)

Set the list of HID interfaces on this device.

Provide a list to the HID class implementation of the interfaces on this device which should be treated as HID devices. This is only necessary for multi-class composite devices to make sure that requests are not confused between interfaces. It should be called before usb_init().

Parameters:
interfacesAn array of interfaces which are HID class.
num_interfacesThe size of the interfaces array.
int8_t HID_SET_PROTOCOL_CALLBACK ( uint8_t  interface,
uint8_t  protocol 
)

HID Set_Protocol request callback.

The USB Stack will call this function when a Set_Protocol request has been received from the host, and will provide the protocol to set as either HID_PROTO_BOOT, or HID_PROTO_REPORT.

Parameters:
interfaceThe interface for which the report is provided
protocolThe protocol to set. Either HID_PROTO_BOOT, or HID_PROTO_REPORT.
Returns:
Return 0 on success or -1 on failure.
int8_t HID_SET_REPORT_CALLBACK ( uint8_t  interface,
uint8_t  report_type,
uint8_t  report_id 
)

HID Set_Report request callback.

The USB Stack will call this function when a Set_Report request has been received from the host. There are two ways to handle this:

0. For unknown requests, return -1. This will send a STALL to the host. 1. For known requests the callback should call usb_start_receive_ep0_data_stage() with a buffer to be filled with the report data and a callback which will get called when the data stage is complete. The callback is required, and the data buffer passed to usb_start_receive_ep0_data_stage() must remain valid until the callback is called.

It is worth noting that only one control transfer can be active at any given time. Once HID_SET_REPORT_CALLBACK() has been called, it will not be called again until the next transfer, meaning that if the application-provided HID_SET_REPORT_CALLBACK() function performs option 1 above, the callback function passed to usb_start_receive_ep0_data_stage() will be called before any other setup transfer can happen again. Thus, it is safe to use the same buffer for all control transfers if desired.

Parameters:
interfaceThe interface for which the report is provided
report_typeThe type of report, either HID_INPUT, HID_OUTPUT, or HID_FEATURE.
report_idThe report index requested. This will be zero if the device does not use numbered reports.
Returns:
Return 0 if the request can be handled or -1 if it cannot. Returning -1 will cause STALL to be returned to the host.
uint8_t process_hid_setup_request ( const struct setup_packet setup )

Process HID Setup Request.

Process a setup request which has been unhandled as if it is potentially a HID setup request. This function will then call appropriate callbacks into the appliction if the setup packet is one recognized by the HID specification.

Parameters:
setupA setup packet to handle
Returns:
Returns 0 if the setup packet could be processed or -1 if it could not.
int16_t USB_HID_DESCRIPTOR_FUNC ( uint8_t  interface,
const void **  ptr 
)

HID Descriptor Function.

The USB Stack will call this function to retrieve the HID descriptor for each HID interface when requested by the host. This function is mandatory for HID devices.

Parameters:
interfaceThe interface for which the descriptor is requested
ptrA Pointer to a pointer which should be set to the requested HID descriptor by this function.
Returns:
Return the length of the HID descriptor in bytes or -1 if the descriptor does not exist.
int16_t USB_HID_PHYSICAL_DESCRIPTOR_FUNC ( uint8_t  interface,
uint8_t  index,
const void **  ptr 
)

HID Physical Descriptor Function.

The USB Stack will call this function to retrieve the physical descriptor for each HID interface when requested by the host. This function, and physical descriptors, are optional.

Parameters:
interfaceThe interface for which the descriptor is requested
indexThe physical descriptor set to return. Index zero requests a special descriptor describing the number of descriptor sets and their sizes. See the HID specification, version 1.11, section 7.1.1.
ptrA Pointer to a pointer which should be set to the requested physical descriptor by this function
Returns:
Return the length of the physical descriptor in bytes or -1 if the descriptor does not exist.
int16_t USB_HID_REPORT_DESCRIPTOR_FUNC ( uint8_t  interface,
const void **  ptr 
)

HID Report Descriptor Function.

The USB Stack will call this function to retrieve the HID report descriptor for each HID interface when requested by the host. This function is mandatory for HID devices.

Parameters:
interfaceThe interface for which the descriptor is requested
ptrA Pointer to a pointer which should be set to the requested HID report descriptor by this function.
Returns:
Return the length of the HID report descriptor in bytes or -1 if the descriptor does not exist.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator