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 Library contains HID routines that support HID class devices, 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 :

Keyboards and pointing devices, for example: standard mouse devices, trackballs, and joysticks.
Front-panel controls, for example: knobs, switches, buttons, and sliders.
Controls that might be found on devices such as telephones, VCR remote controls, games or simulation devices, for example: data gloves, throttles, steering wheels, and rudder pedals.
Devices that may not require human interaction but provide data in a similar format to HID class devices, for example, bar-code readers, thermometers, or voltmeters.

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 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 mikroPascal PRO for ARM(Tools › USB HID Terminal). The default name for descriptor file is USBdsc.mpas, but you may rename it.

HID_Enable

Prototype	procedure HID_Enable(readbuff : ^byte; writebuff : ^byte);
Description	Enables USB HID communication.
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_Read

Prototype	function HID_Read() : 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	// retry until success while(HID_Read() = 0) do ;
Notes	None.

HID_Write

Prototype	function HID_Write(writebuff : ^byte; len : byte) : 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	// retry until success while(HID_Write(@writebuff,64) = 0) do ;
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	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	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	procedure USB1Interrupt(); iv IVT_ADDR_USB1INTERRUPT; begin USB_Interrupt_Proc(); end;
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	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 do begin USB_Polling_Proc(); kk := HID_Read(); if (kk <> 0) then begin for cnt := 0 to 64 writebuff[cnt] := readbuff[cnt]; HID_Write(@writebuff,64); end; end;
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	procedure Gen_Enable(readbuff : ^byte; writebuff : ^byte);
Description	Initialize the USB module of the MCU.
Parameters	`readbuff:` Read Buffer. `writebuff:` Write Buffer.
Returns	Nothing.
Requires	USB needs to be enabled before using this function. See HID_Enable.
Example	Gen_Enable(@readbuff,@writebuff);
Notes	None.

Gen_Read

Prototype	function Gen_Read(readbuff : ^byte; length : byte; ep : byte) : 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) do ;
Notes	None.

Gen_Write

Prototype	function Gen_Write(writebuff : ^byte; length : byte; ep : byte) : 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) do ;
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	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.

Library Example

This example establishes connection with the HID terminal that is active on the PC. Upon connection establishment, the HID Device Name will appear in the respective window. After that software will wait for data and it will return received data back. Examples uses USBdsc.mpas descriptor file, which is in the same folder, and can be created by the HID Terminal.

Copy Code To Clipboard

program HID_Read_Write_Polling;

var cnt, kk : byte;

var readbuff : array[64] of byte;
var writebuff : array[64] of byte;

begin
  HID_Enable(@readbuff,@writebuff);
  while TRUE do
    begin
      USB_Polling_Proc();               // Call this routine periodically
      kk := HID_Read();
      if (kk <> 0) then
      begin
        for cnt:=0 to 63 do
          writebuff[cnt]:=readbuff[cnt];
        HID_Write(@writebuff,64);
      end ;
    end;
end.