USB Device HID API#
USBD_HID_ConfigureBufAlignOctets()#
Description#
Configures the alignment of the internal buffers.
Files#
usbd_hid.h/usbd_hid.c
Prototype#
void USBD_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
USBD_HID_Init()
function.
USBD_HID_ConfigureReportID_Qty()#
Description#
Configures the quantity of report IDs.
Files#
usbd_hid.h/usbd_hid.c
Prototype#
void USBD_HID_ConfigureReportID_Qty (CPU_INT08U report_id_qty)
Arguments#
report_id_qty
Quantity of report IDs.
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 USBD_HID_Init() function.
USBD_HID_ConfigurePushPopItemsQty()#
Description#
Configures the quantity of push/pop items.
Files#
usbd_hid.h/usbd_hid.c
Prototype#
void USBD_HID_ConfigurePushPopItemsQty (CPU_INT08U push_pop_items_qty)
Arguments#
push_pop_items_qty
Quantity of Push/pop items.
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
USBD_HID_Init()
function.
USBD_HID_ConfigureMemSeg()#
Description#
Configures the memory segment to use when allocating control data and buffers.
Files#
usbd_hid.h/usbd_hid.c
Prototype#
void USBD_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
USBD_HID_Init()
function.
USBD_HID_ConfigureTmrTaskStk()#
Description#
Configures the timer task stack.
Files#
usbd_hid.h/usbd_hid.c
Prototype#
void USBD_HID_ConfigureTmrTaskStk (CPU_INT32U stk_size_elements,
void *p_stk)
Arguments#
stk_size_elements
Size of the stack, in stack elements.
p_stk
Pointer to base of the stack.
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
USBD_HID_Init()
function.
USBD_HID_Init()#
Description#
Initialize HID class.
Files#
usbd_hid.h/usbd_hid.c
Prototype#
void USBD_HID_Init (const USBD_HID_QTY_CFG *p_qty_cfg,
RTOS_ERR *p_err)
Arguments#
p_qty_cfg
Pointer to HID class configuration structure.
p_err
Pointer to the variable that will receive one of these returned error codes from this function :
RTOS_ERR_NONE
RTOS_ERR_NOT_AVAIL
RTOS_ERR_OS_ILLEGAL_RUN_TIME
RTOS_ERR_POOL_EMPTY
RTOS_ERR_INVALID_CFG
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_SEG_OVF
Returned Value#
None.
Notes / Warnings#
None.
USBD_HID_TmrTaskPrioSet()#
Description#
Sets priority of the HID timer task.
Files#
usbd_hid.h/usbd_hid.c
Prototype#
void USBD_HID_TmrTaskPrioSet (RTOS_TASK_PRIO prio,
RTOS_ERR *p_err)
Arguments#
prio
Priority of the HID timer task.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function:
RTOS_ERR_NONE
RTOS_ERR_INVALID_ARG
Returned Value#
None.
Notes / Warnings#
None.
USBD_HID_Add()#
Description#
Adds a new instance of the HID class.
Files#
usbd_hid.h/usbd_hid.c
Prototype#
CPU_INT08U USBD_HID_Add ( CPU_INT08U subclass,
CPU_INT08U protocol,
USBD_HID_COUNTRY_CODE country_code,
const CPU_INT08U *p_report_desc,
CPU_INT16U report_desc_len,
const CPU_INT08U *p_phy_desc,
CPU_INT16U phy_desc_len,
CPU_INT16U interval_in,
CPU_INT16U interval_out,
CPU_BOOLEAN ctrl_rd_en,
USBD_HID_CALLBACK *p_hid_callback,
RTOS_ERR *p_err)
Arguments#
subclass
Subclass code.
protocol
Protocol code.
country_code
Country code ID.
p_report_desc
Pointer to the report descriptor structure. Content MUST be persistent.
report_desc_len
Report descriptor length.
p_phy_desc
Pointer to the physical descriptor structure. Content MUST be persistent.
phy_desc_len
Physical descriptor length.
interval_in
Polling interval for input transfers, in milliseconds. It must be a power of 2.
interval_out
Polling interval for output transfers, in milliseconds. It must be a power of 2. Used only when read operations are not through control transfers.
ctrl_rd_en
Enable read operations through the control transfers.
p_hid_callback
Pointer to HID descriptor and request callback structure. Content MUST be persistent.
p_err
Pointer to the variable that will receive one of these returned error codes from this function :
RTOS_ERR_NONE
RTOS_ERR_ALLOC
RTOS_ERR_CLASS_INSTANCE_ALLOC
RTOS_ERR_INVALID_ARG
RTOS_ERR_SEG_OVF
Returned Value#
Class instance number, if no errors are returned.
USBD_CLASS_NBR_NONE
, if any errors are returned.
Notes / Warnings#
None.
USBD_HID_ConfigAdd()#
Description#
Adds the HID class instance to the USB device configuration (see Note #1).
Files#
usbd_hid.h/usbd_hid.c
Prototype#
CPU_BOOLEAN USBD_HID_ConfigAdd (CPU_INT08U class_nbr,
CPU_INT08U dev_nbr,
CPU_INT08U config_nbr,
RTOS_ERR *p_err)
Arguments#
class_nbr
Class instance number.
dev_nbr
Device number.
config_nbr
Configuration index to add HID class instance to.
p_err
Pointer to the variable that will receive one of these returned error codes from this function :
RTOS_ERR_NONE
RTOS_ERR_INVALID_DEV_STATE
RTOS_ERR_IF_ALT_ALLOC
RTOS_ERR_ALLOC
RTOS_ERR_CLASS_INSTANCE_ALLOC
RTOS_ERR_IF_ALLOC
RTOS_ERR_INVALID_ARG
RTOS_ERR_EP_ALLOC
RTOS_ERR_EP_NONE_AVAIL
Returned Value#
DEF_YES
, if the HID class instance was added to USB device configuration successfully.DEF_NO
, if it fails to be added.
Notes / Warnings#
Called several times, it creates multiple instances and configurations. For example, the following architecture could be created:
HS |-- Configuration 0 (HID class 0) (HID class 1) (HID class 2) |-- Interface 0 |-- Configuration 1 (HID class 0) |-- Interface 0
Configuration Descriptor corresponding to a HID device uses the following format:
Configuration Descriptor
|-- Interface Descriptor (HID class)
|-- Endpoint Descriptor (Interrupt IN)
|-- Endpoint Descriptor (Interrupt OUT) - optional
USBD_HID_IsConn()#
Description#
Gets the HID class connection state.
Files#
usbd_hid.h/usbd_hid.c
Prototype#
CPU_BOOLEAN USBD_HID_IsConn (CPU_INT08U class_nbr)
Arguments#
class_nbr
Class instance number.
Returned Value#
DEF_YES
, if HID class is connected.DEF_NO
, it fails to connect.
Notes / Warnings#
None.
USBD_HID_Rd()#
Description#
Receives data from the host through the Interrupt OUT endpoint. This function is blocking.
Files#
usbd_hid.h/usbd_hid.c
Prototype#
CPU_INT32U USBD_HID_Rd (CPU_INT08U class_nbr,
void *p_buf,
CPU_INT32U buf_len,
CPU_INT16U timeout,
RTOS_ERR *p_err)
Arguments#
class_nbr
Class instance number.
p_buf
Pointer to the receive buffer.
buf_len
Receive the buffer length, in octets.
timeout
Timeout, in milliseconds.
p_err
Pointer to the variable that will receive one of these returned error codes from this function :
RTOS_ERR_NONE
RTOS_ERR_INVALID_DEV_STATE
RTOS_ERR_NULL_PTR
RTOS_ERR_EP_QUEUING
RTOS_ERR_RX
RTOS_ERR_NOT_READY
RTOS_ERR_EP_INVALID
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_NOT_AVAIL
RTOS_ERR_FAIL
RTOS_ERR_WOULD_OVF
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_CLASS_STATE
RTOS_ERR_INVALID_EP_STATE
RTOS_ERR_ABORT
RTOS_ERR_TIMEOUT
Returned Value#
Number of octets received, if no errors are returned.
0, if any errors are returned.
Notes / Warnings#
None.
USBD_HID_Wr()#
Description#
Sends data to the host through the Interrupt IN endpoint. This function is blocking.
Files#
usbd_hid.h/usbd_hid.c
Prototype#
CPU_INT32U USBD_HID_Wr (CPU_INT08U class_nbr,
void *p_buf,
CPU_INT32U buf_len,
CPU_INT16U timeout,
RTOS_ERR *p_err)
Arguments#
class_nbr
Class instance number.
p_buf
Pointer to the transmit buffer. If more than one input report exists, the first byte must represent the Report ID.
buf_len
Transmit buffer length, in octets.
timeout
Timeout in milliseconds.
p_err
Pointer to the variable that will receive one of these returned error codes from this function :
RTOS_ERR_NONE
RTOS_ERR_INVALID_DEV_STATE
RTOS_ERR_NULL_PTR
RTOS_ERR_EP_QUEUING
RTOS_ERR_TX
RTOS_ERR_NOT_READY
RTOS_ERR_EP_INVALID
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_NOT_AVAIL
RTOS_ERR_WOULD_OVF
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_INVALID_ARG
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_CLASS_STATE
RTOS_ERR_INVALID_EP_STATE
RTOS_ERR_ABORT
RTOS_ERR_TIMEOUT
Returned Value#
Number of octets sent, if no errors are returned.
0, if any errors are returned.
Notes / Warnings#
None.