USB Host HID API#

USBH_HID_ConfigureBufAlignOctets()
USBH_HID_ConfigureRxBuf()
USBH_HID_ConfigureUsageMaxNbrPerItem()
USBH_HID_ConfigureReportDescMaxLen()
USBH_HID_ConfigureOptimizeSpdCfg()
USBH_HID_ConfigureInitAllocCfg()
USBH_HID_ConfigureMemSeg()
USBH_HID_Init()
USBH_HID_StdReqTimeoutSet()
USBH_HID_UsageGet()
USBH_HID_IsBootCapable()
USBH_HID_ReportTx()
USBH_HID_ProtocolSet()
USBH_HID_ProtocolGet()
USBH_HID_IdleSet()
USBH_HID_IdleGet()

USBH_HID_ConfigureBufAlignOctets()#

Description#

Configures the alignment of the internal buffers.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

void  USBH_HID_ConfigureBufAlignOctets (CPU_SIZE_T  buf_align_octets)

Arguments#

buf_align_octets

Buffer alignment, in octets.

Returned Value#

None.

Notes / Warnings#

This function is optional, if it is not called, the default value will be used.
This function MUST be called before the HID class is initialized via the USBH_HID_Init() function.

USBH_HID_ConfigureRxBuf()#

Description#

Configures the receive buffers.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

void  USBH_HID_ConfigureRxBuf (CPU_INT08U  rx_buf_qty,
                               CPU_INT08U  rx_buf_len)

Arguments#

rx_buf_qty

Quantity of buffers available for report reception.

rx_buf_len

Len of buffers, in octets, used for report reception.

Returned Value#

None.

Notes / Warnings#

This function is optional, if it is not called, the default value will be used.
This function MUST be called before the HID class is initialized via the USBH_HID_Init() function.

USBH_HID_ConfigureUsageMaxNbrPerItem()#

Description#

Configures the maximum quantity of usages per item.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

void  USBH_HID_ConfigureUsageMaxNbrPerItem(CPU_INT08U  usage_max_nbr_per_item)

Arguments#

usage_max_nbr_per_item

Maximum number of usages associated with a given item.

Returned Value#

None.

Notes / Warnings#

This function is optional, if it is not called, the default value will be used.
This function MUST be called before the HID class is initialized via the USBH_HID_Init() function.

USBH_HID_ConfigureReportDescMaxLen()#

Description#

Configures the report descriptor buffer.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

void  USBH_HID_ConfigureReportDescMaxLen (CPU_INT16U  report_desc_max_len)

Arguments#

report_desc_max_len

Maximum length, in octets, of report desc.

Returned Value#

None.

Notes / Warnings#

This function is optional, if it is not called, the default value will be used.
This function MUST be called before the HID class is initialized via the USBH_HID_Init() function.

USBH_HID_ConfigureOptimizeSpdCfg()#

Description#

Sets the configurations required when optimize speed mode is enabled.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

void  USBH_HID_ConfigureOptimizeSpdCfg(const  USBH_HID_CFG_OPTIMIZE_SPD  *p_optimize_spd_cfg)

Arguments#

p_optimize_spd_cfg

Pointer to the structure containing the configurations for the optimize speed mode.

Returned Value#

None.

Notes / Warnings#

This function MUST be called before the HID class is initialized via the USBH_HID_Init() function.
This function MUST be called when the USBH_CFG_OPTIMIZE_SPD_EN configuration is set to DEF_ENABLED.

USBH_HID_ConfigureInitAllocCfg()#

Description#

Sets the configurations required when allocation at initialization mode is enabled.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

void  USBH_HID_ConfigureInitAllocCfg  (const  USBH_HID_CFG_INIT_ALLOC  *p_init_alloc_cfg)

Arguments#

p_init_alloc_cfg

Pointer to the structure containing the configurations for the allocation at initialization mode.

Returned Value#

None.

Notes / Warnings#

This function MUST be called before the HID class is initialized via the USBH_HID_Init() function.
This function MUST be called when the USBH_CFG_INIT_ALLOC_EN configuration is set to DEF_ENABLED.

USBH_HID_ConfigureMemSeg()#

Description#

Configures the memory segment to use when allocating control data and buffers.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

void  USBH_HID_ConfigureMemSeg (MEM_SEG  *p_mem_seg,
                                MEM_SEG  *p_mem_seg_buf)

Arguments#

p_mem_seg

Pointer to memory segment to use when allocating control data. Can be the same segment used for p_mem_seg_buf.
DEF_NULL means general purpose heap segment.

p_mem_seg_buf

Pointer to memory segment to use when allocating data buffers. Can be the same segment used for p_mem_seg.
DEF_NULL means general purpose heap segment.

Returned Value#

None.

Notes / Warnings#

This function is optional, if it is not called, the default value will be used.
This function MUST be called before the HID class is initialized via the USBH_HID_Init() function.

USBH_HID_Init()#

Description#

Initializes the HID class.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

void  USBH_HID_Init (USBH_HID_APP_FNCTS  *p_hid_app_fncts,                     RTOS_ERR            *p_err)

Arguments#

p_hid_app_fncts

Pointer to the HID application callback functions structure. Content MUST be persistent.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_SEG_OVF
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_INVALID_CFG

Returned Value#

None.

Notes / Warnings#

None.

USBH_HID_StdReqTimeoutSet()#

Description#

Assigns a new timeout delay for the HID standard requests.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

void  USBH_HID_StdReqTimeoutSet (CPU_INT32U   std_req_timeout_ms,
                                 RTOS_ERR    *p_err)

Arguments#

std_req_timeout_ms

New timeout, in milliseconds.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

USBH_HID_UsageGet()#

Description#

Gets the global usage associated to HID function.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

CPU_INT32U  USBH_HID_UsageGet (USBH_HID_FNCT_HANDLE    hid_fnct_handle,
                              RTOS_ERR               *p_err)

Arguments#

hid_fnct_handle

Handle to the HID function.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_NOT_AVAIL

Returned Value#

Usage.

Notes / Warnings#

None.

USBH_HID_IsBootCapable()#

Description#

Tests whether HID interface belongs to boot subclass.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

CPU_BOOLEAN  USBH_HID_IsBootCapable (USBH_HID_FNCT_HANDLE    hid_fnct_handle,
                                    RTOS_ERR               *p_err)

Arguments#

hid_fnct_handle

Handle to the HID function.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_NOT_AVAIL
RTOS_ERR_INVALID_STATE

Returned Value#

DEF_YES, if the function belongs to the boot subclass,
DEF_NO, if the function does not belong to the boot subclass.

Notes / Warnings#

None.

USBH_HID_ReportTx()#

Description#

Sends the report to the device.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

CPU_INT16U  USBH_HID_ReportTx (USBH_HID_FNCT_HANDLE    hid_fnct_handle,
                              CPU_INT08U              report_id,
                              void                   *p_buf,
                              CPU _INT16U             buf_len,
                              CPU _INT32U             timeout_ms,
                              RTOS_ERR               *p_err)

Arguments#

hid_fnct_handle

Handle to the HID function.

report_id

ID of the Report.

p_buf

Pointer to the the buffer that contains the report.

buf_len

Buffer length, in octets.

timeout_ms

Timeout, in milliseconds.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_POOL_EMPTY
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_STATE
RTOS_ERR_URB_ALLOC
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_EP_INVALID
RTOS_ERR_SEG_OVF
RTOS_ERR_OS_ILLEGAL_RUN_TIME
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_NULL_PTR
RTOS_ERR_WOULD_OVF
RTOS_ERR_TX
RTOS_ERR_NOT_AVAIL

Returned Value#

Number of octets sent.

Notes / Warnings#

Do not add the report id to p_buf, it will be added automatically.

USBH_HID_ProtocolSet()#

Description#

Sets the protocol (boot/report descriptor) of HID function.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

void  USBH_HID_ProtocolSet (USBH_HID_FNCT_HANDLE    hid_fnct_handle,
                           CPU_INT16U              protocol,
                           RTOS_ERR               *p_err)

Arguments#

hid_fnct_handle

Handle to the HID function.

protocol

Protocol to set.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_POOL_EMPTY
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_STATE
RTOS_ERR_URB_ALLOC
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_SEG_OVF
RTOS_ERR_EP_INVALID
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_NOT_AVAIL
RTOS_ERR_TX
RTOS_ERR_WOULD_OVF

Returned Value#

None.

Notes / Warnings#

None.

USBH_HID_ProtocolGet()#

Description#

Gets the protocol (boot/report) of the HID function.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

void  USBH_HID_ProtocolGet (USBH_HID_FNCT_HANDLE    hid_fnct_handle,
                           CPU_INT16U             *p_protocol,
                           RTOS_ERR               *p_err)

Arguments#

hid_fnct_handle

Handle the HID function.

p_protocol

Variable that receives protocol of the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_POOL_EMPTY
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_STATE
RTOS_ERR_URB_ALLOC
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_SEG_OVF
RTOS_ERR_EP_INVALID
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_NOT_AVAIL
RTOS_ERR_TX
RTOS_ERR_WOULD_OVF

Returned Value#

None.

Notes / Warnings#

None.

USBH_HID_IdleSet()#

Description#

Sets the idle duration for the given report ID.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

void  USBH_HID_IdleSet (USBH_HID_FNCT_HANDLE    hid_fnct_handle,
                       CPU_INT08U              report_id,
                       CPU_INT32U              dur,
                       RTOS_ERR               *p_err)

Arguments#

hid_fnct_handle

Handle to the HID function.

report_id

ID of the Report.

dur

Idle duration, in milliseconds.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_POOL_EMPTY
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_STATE
RTOS_ERR_URB_ALLOC
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_SEG_OVF
RTOS_ERR_EP_INVALID
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_NOT_AVAIL
RTOS_ERR_TX
RTOS_ERR_WOULD_OVF

Returned Value#

None.

Notes / Warnings#

None.

USBH_HID_IdleGet()#

Description#

Gets the idle duration for the given report ID.

Files#

usbh_hid.h/usbh_hid.c

Prototype#

CPU_INT32U  USBH_HID_IdleGet (USBH_HID_FNCT_HANDLE    hid_fnct_handle,
                             CPU_INT08U              report_id,
                             RTOS_ERR               *p_err)

Arguments#

hid_fnct_handle

Handle to the HID function.

report_id

ID of the Report.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_POOL_EMPTY
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_STATE
RTOS_ERR_URB_ALLOC
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_SEG_OVF
RTOS_ERR_EP_INVALID
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_NOT_AVAIL
RTOS_ERR_TX
RTOS_ERR_WOULD_OVF

Returned Value#

Idle duration in milliseconds.

Notes / Warnings#

None.