USB Library 26.05.

2014

USB Library
mikroC PRO for PIC Libraries > Hardware Libraries >

USB 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 mikroC PRO
for PIC (Tools › USB HID Terminal). The default name for descriptor file is USBdsc.c, but you may rename it.
Important :
The USB library routines have been changed. Please, have this in mind when migrating projects from previous versions of the
compiler.
Also, this relates to the descriptor source file, so it is necessary to create a new descriptor file in order to make your project
work.

Library Routines
HID_Enable
HID_Read
HID_Write
HID_Disable
USB_Interrupt_Proc
USB_Polling_Proc
Gen_Enable
Gen_Read
Gen_Write

HID_Enable
Prototype void HID_Enable(char *readbuff, char *writebuff);
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 char HID_Read(void);

http://www.mikroe.com/download/eng/documents/compilers/mikroc/pro/pic/help/usb_hid_library.htm 1/4
USB Library 26.05.2014

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())
;
Notes None.

HID_Write
Prototype char HID_Write(char *writebuff, char len);
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))
;
Notes Function call needs to be repeated as long as data is not successfuly sent.

HID_Disable
Prototype void HID_Disable(void);
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 void USB_Interrupt_Proc(void);
Description This routine is used for servicing various USB bus events. Should be called inside USB interrupt routine.
Parameters None.
Returns Nothing.
Requires Nothing.
Example void interrupt() {
USB_Interrupt_Proc();
}
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 void USB_Polling_Proc(void);
Description This routine is used for servicing various USB bus events. It should be periodically, preferably every 100 microseconds.
Parameters None.
Returns Nothing.
Requires Nothing.
Example while(1) {
USB_Polling_Proc();
kk = HID_Read();
if (kk != 0) {
for(cnt=0; cnt < 64; cnt++)
writebuff[cnt]=readbuff[cnt];
HID_Write(&writebuff,64);
}
}
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).

http://www.mikroe.com/download/eng/documents/compilers/mikroc/pro/pic/help/usb_hid_library.htm 2/4
USB Library 26.05.2014

Gen_Enable
Prototype void Gen_Enable(char* readbuff, char* writebuff);
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 Gen_Enable.
Example Gen_Enable(&readbuff,&writebuff);
Notes None.

Gen_Read
Prototype char Gen_Read(char *readbuff, char length, char ep);
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 needs to be enabled before using this function. See Gen_Enable.
Example while(Gen_Read(readbuff,64,1)==0)
;
Notes None.

Gen_Write
Prototype char Gen_Write(char* writebuff, char length, char ep);
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 needs to be enabled before using this function. See Gen_Enable.
Example while(Gen_Write(writebuff,64,1)==0)
;
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.c descriptor file, which is in the same folder, and can be created by the HID Terminal.

Copy Code To Clipboard

unsigned char readbuff[64] absolute 0x500; // Buffers should be in USB RAM, please consult datasheet
unsigned char writebuff[64] absolute 0x540;
char cnt;
char kk;

void interrupt(){
USB_Interrupt_Proc(); // USB servicing is done inside the interrupt
}
void main(void){
ADCON1 |= 0x0F; // Configure all ports with analog function as digital
CMCON |= 7; // Disable comparators
HID_Enable(&readbuff,&writebuff); // Enable HID communication
while(1){
while(!HID_Read())
;

for(cnt=0;cnt<64;cnt++)
writebuff[cnt]=readbuff[cnt];

http://www.mikroe.com/download/eng/documents/compilers/mikroc/pro/pic/help/usb_hid_library.htm 3/4
USB Library 26.05.2014

while(!HID_Write(&writebuff,64))
;
}
}

HW Connection
USB connection scheme
Copyright (c) 2002-2012 mikroElektronika. All rights reserved.
What do you think about this topic ? Send us feedback!
Want more examples and libraries?
Find them on

http://www.mikroe.com/download/eng/documents/compilers/mikroc/pro/pic/help/usb_hid_library.htm 4/4