USB Device HID API#

• USBD_HID_ConfigureBufAlignOctets()

• USBD_HID_ConfigureReportID_Qty()

• USBD_HID_ConfigurePushPopItemsQty()

• USBD_HID_ConfigureMemSeg()

• USBD_HID_ConfigureTmrTaskStk()

• USBD_HID_Init()

• USBD_HID_TmrTaskPrioSet()

• USBD_HID_Add()

• USBD_HID_ConfigAdd()

• USBD_HID_IsConn()

• USBD_HID_Rd()

• USBD_HID_Wr()

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#

1. This function is optional, if it is not called, the default value will be used.

2. 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#

1. This function is optional, if it is not called, the default value will be used.

2. 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#

1. This function is optional, if it is not called, the default value will be used.

2. 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#

1. This function is optional, if it is not called, the default value will be used.

2. 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#

1. This function is optional, if it is not called, the default value will be used.

2. 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#

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

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