mE's HID Library usage tips for P18 PIC's.

Here are some tips on the usage of the mikroElektronika HID (USB) library for P18 PIC's.

Important: In all USB documentation the words "IN(PUT)" and "OUT(PUT)" are frequently used to indicate the direction of data transfer. Those directions are always "USB host" (e.g. PC) related. So, "IN(PUT)" means data from the PIC to the host (data OUT from PIC point of view), "OUT(PUT)" means data from the host to the PIC (data IN from PIC point of view).

1. Declaration of the user's Receive and SendBuffers

The "report length"s (an USB-HID term) are defined with the "HID Terminal Descriptor" tool when creating the "USBdsc.mpas" file. The two constant values (HID_OUTPUT_REPORT_BYTES and HID_INPUT_REPORT_BYTES) are to be found in the latter.
This defines (in bytes) the size of the data packet to receive ("Output report length") and to send ("Input report length").

The user's receive and sendbuffers in the application must have the same size as the "report length"s. To achieve this, the buffers can be declared as follows:
    ReceiveBuffer: array[HID_OUTPUT_REPORT_BYTES] of byte; absolute 0x500;
    SendBuffer:    array[HID_INPUT_REPORT_BYTES]  of byte; absolute 0x540;

Make sure both USB buffers are properly located in "USB Ram" as required (with the "absolute" qualifier), see the datasheet of the PIC at hand.

2. The interrupt procedure

In the interrupt procedure of the application the HID processing procedure should be called. This procedure does all HID-USB processing based on interrupts received from the PIC's SIE (the USB engine). This is to be done like this:
procedure interrupt;
The HID initialization procedure ("HID_Enable") takes care of the enabling of the necessary interrupts.

3. Initialization

As documented, the initialization of the HID software is like
  HID_Enable(@ReceiveBuffer, @SendBuffer);
As you can see, the only two parameters are the address of the receive and sendbuffers.

4. Receiving data (PC --> PIC)

Receiving data is done like this:
  NrBytes := HID_Read;
As you can see, this routine takes no parameters (the address of the ReceiveBuffer was already provided in "HID_Enable"), and gives one result: the number of bytes received in the ReceiveBuffer.
This number of bytes can have only 2 values: So, the number of bytes received is not really "variable" as suggested by the return value of the function.

5. Sending data (PIC --> PC)

For that the following procedure exists:
  function HID_Write(writebuff: ^byte; len: byte): byte;
This procedure returns the number of bytes sent if the data write was successfull, otherwise 0. The reason of a failiure is the USB engine is not ready to accept new data to be sent (still busy with the previous one).
So, this means that the routine should be used e.g. as follows:
  repeat until HID_Write(@SendBuffer, HID_INPUT_REPORT_BYTES) > 0; 
Be carefull: this can block your software (it is waiting for HID_Write to succeed).

As you can see, two parameters are required by this function: