USB HID Library
  mikroPascal PRO for FT90x Libraries > Hardware Libraries > 
  

USB HID Library

Universal Serial Bus (USB) provides a serial bus standard for connecting a wide variety of devices, including computers, cell phones, game consoles, PDA’s, etc.

USB HID Library contains HID routines that support HID class devices in full speed and high speed mode, and also the generic routines that can be used with vendor specified drivers.

USB HID Class

The HID class consists primarily of devices that are used by humans to control the operation of computer systems. Typical examples of HID class devices include :

Many typical HID class devices include indicators, specialized displays, audio feedback, and force or tactile feedback. Therefore, the HID class definition includes support for various types of output directed to the end user.

Descriptor File

Each project based on the USB HID library should include a descriptor source file which contains vendor id and name, product id and name, report length, and other relevant information. To create a descriptor file, use the integrated USB HID terminal of mikroBasic PRO for FT90x(Tools › USB HID Terminal). The default name for descriptor file is USBdsc.c, but you may rename it.

Due to the specific nature of USB HID module, bear in mind that when defining endpoint descriptors, don't define two descriptors with the same number (numerical representation) of endpoints and different directions.
This means that USB HID library example has endpoints defined as 1(IN) and 2(OUT), which shouldn't be defined as 1(IN) i 1(OUT).

Library Routines

HID_Enable

Prototype

sub procedure HID_Enable(dim readbuff as ^byte, dim writebuff as ^byte)
Description

Enables USB HID communication in full speed mode.
Parameters
  • readbuff: Read Buffer.
  • writebuff: Write Buffer.

These parameters are used for HID communication.
Returns

Nothing.
Requires

Nothing.
Example 
HID_Enable(@readbuff,@writebuff)
Notes

This function needs to be called before using other routines of USB HID Library.

HID_EnableHS

Prototype

sub procedure HID_EnableHS(dim readbuff as ^byte, dim writebuff as ^byte)
Description

Enables USB HID communication in high speed mode.
Parameters
  • readbuff: Read Buffer.
  • writebuff: Write Buffer.

These parameters are used for HID communication.
Returns

Nothing.
Requires

Before using this function, USB_SetDevQualifier and USB_SetOtherSpeedConfig should be called.
Example 
HID_EnableHS(@readbuff,@writebuff)
Notes

This function needs to be called before using other routines of USB HID Library.

HID_Read

Prototype

sub function HID_Read() as byte
Description

Receives message from host and stores it in the Read Buffer.
Parameters

None.
Returns

If the data reading has failed, the function returns 0. Otherwise, it returns number of characters received from the host.
Requires

USB HID needs to be enabled before using this function. See HID_Enable.
Example 
while(HID_Read() = 0)
wend
Notes

None.

HID_Write

Prototype

sub function HID_Write(dim writebuff as ^byte, dim len as byte) as byte
Description

Function sends data from Write Buffer writebuff to host.
Parameters
  • writebuff: Write Buffer, same parameter as used in initialization; see HID_Enable.
  • len: specifies a length of the data to be transmitted.
Returns

If the data transmitting has failed, the function returns 0. Otherwise, it returns number of transmitted bytes.
Requires

USB HID needs to be enabled before using this function. See HID_Enable.
Example 
while(HID_Write(@writebuff,64) = 0)
wend
Notes

Function call needs to be repeated as long as data is not successfuly sent.

This is a blocking routine which can block the program flow. Calling USB_Break routine from the interrupt will unblock the program execution.

HID_Disable

Prototype

sub procedure HID_Disable()
Description

Disables USB HID communication.
Parameters

None.
Returns

Nothing.
Requires

USB HID needs to be enabled before using this function. See HID_Enable.
Example 
HID_Disable()
Notes

None.

USB_Interrupt_Proc

Prototype

sub procedure USB_Interrupt_Proc()
Description

This routine is used for servicing various USB HID bus events. Should be called inside USB HID interrupt routine.
Parameters

None.
Returns

Nothing.
Requires

Nothing.
Example 
sub procedure USB1Interrupt() iv IVT_ADDR_USB1INTERRUPT
  USB_Interrupt_Proc()
end sub
Notes

Do not use this function with USB_Polling_Proc, only one should be used. To enable servicing through interrupt, USB_INTERRUPT constant should be set (it is set by default in descriptor file).

USB_Polling_Proc

Prototype

sub procedure USB_Polling_Proc()
Description

This routine is used for servicing various USB HID bus events. It should be periodically, preferably every 100 microseconds.
Parameters

None.
Returns

Nothing.
Requires

Nothing.
Example 
while TRUE
  USB_Polling_Proc()
  kk = HID_Read()
  if (kk <> 0) then
    for cnt = 0 to 63
      writebuff[cnt] = readbuff[cnt]
    next cnt
    HID_Write(@writebuff,64)
  end if
wend
Notes

Do not use this functions with USB_Interrupt_Proc. To enable servicing by polling, USB_INTERRUPT constant should be set to 0 (it is located in descriptor file).

Gen_Enable

Prototype

sub procedure Gen_Enable(dim readbuff as ^byte, dim writebuff as ^byte)
Description

Initializes the USB HID module in full speed mode.
Parameters
  • readbuff: Read Buffer.
  • writebuff: Write Buffer.
Returns

Nothing.
Requires

USB HID communication needs to be enabled in full speed mode before using this function. See HID_Enable.
Example 
Gen_Enable(@readbuff,@writebuff)
Notes

None.

Gen_EnableHS

Prototype

sub procedure Gen_EnableHS(dim readbuff as ^byte, dim writebuff as ^byte)
Description

Initializes the USB HID module in high speed mode.
Parameters
  • readbuff: Read Buffer.
  • writebuff: Write Buffer.
Returns

Nothing.
Requires
Example 
Gen_EnableHS(@readbuff,@writebuff)
Notes

None.

Gen_Read

Prototype

sub function Gen_Read(dim readbuff as ^byte, dim length as byte, dim ep as byte) as byte
Description

Generic routine that receives the specified data from the specified endpoint.
Parameters
  • readbuff: Received data.
  • length: The length of the data that you wish to receive.
  • ep: Endpoint number you want to receive the data into.
Returns

Returns the number of received bytes, otherwise 0.
Requires

USB HID needs to be enabled before using this function. See HID_Enable.
Example 
while(Gen_Read(@readbuff,64,1) = 0)
wend
Notes

None.

Gen_Write

Prototype

sub function Gen_Write(dim writebuff as ^byte, dim as length as byte, dim ep as byte) as byte
Description

Sends the specified data to the specified endpoint.
Parameters
  • writebuff: The data that you want to send.
  • length: the length of the data that you wish to send.
  • ep: Endpoint number you want to send the data into.
Returns

Returns the number of transmitted bytes, otherwise 0.
Requires

USB HIDneeds to be enabled before using this function. See HID_Enable.
Example 
while(Gen_Write(@writebuff,64,1) = 0)
wend
Notes

This is a blocking routine which can block the program flow. Calling USB_Break routine from the interrupt will unblock the program execution.

USB_Break

Prototype

sub procedure USB_Break()
Description

HID_Write and Gen_Write are blocking routines and they can block the program flow. Calling USB_Break() routine from the interrupt will unblock the program execution. Calling this routine from interrupt will unblock the program execution. This mechanism is similar to WDT.
Parameters

None.
Returns

Nothing.
Requires Nothing.
Example 

          		
        


        

          Notes
          
            
None.

          		
        


      

    


    

    
USB_SetDevQualifier


    

    


      

      

        

          Prototype
          
            
sub procedure USB_SetDevQualifier(dim qualifier as ^const uint8_t);

          		
        


        

          Description
          
            
This routine sets device qualifier descriptor, which is necessary for proper functioning of the USB HID module in high speed mode.

          		
        


        

          Parameters
          
            
    
							
  • qualifier: pointer to the device qualifier descriptor.
    • 
						

          		
        


        

          Returns
          
            
Nothing.

          		
        


        

          Requires
          
            
Nothing.

          		
        


        

          Example
          


          		
        


        

          Notes
          
            
Call this routine before using HID_EnableHS and Gen_EnableHS routines.

          		
        

        
      

    


    

    
USB_SetOtherSpeedConfig


    

    


      

      

        

          Prototype
          
            
sub procedure USB_SetOtherSpeedConfig(dim config as ^const uint8_t)

          		
        


        

          Description
          
            
This routine sets other speed configuration descriptor, which is necessary for proper functioning of the USB HID module in high speed mode.

          		
        


        

          Parameters
          
            
    
							
  • config: pointer to the other speed configuration descriptor.
    • 
						

          		
        


        

          Returns
          
            
Nothing.

          		
        


        

          Requires
          
            
Nothing.

          		
        


        

          Example
          


          		
        


        

          Notes
          
            
Call this routine before using HID_EnableHS and Gen_EnableHS routines.

          		
        

        
      

    


    

    

    

            Copyright (c) 2002-2015 mikroElektronika. All rights reserved.
      
What do you think about this topic ?  Send us feedback!
    



      
Want more examples and libraries? 
     
Find them on
     LibStock - A place for the code