USB HID Library documentation.


1. Declaration of the user's Receive and SendBuffers

The "report length"s (an USB-HID term) is defined with the file "USB_HID_ProjectItems.mpas" It defines (in bytes) the size of the data packet to receive ("HID_OUTPUT_REPORT_BYTES") and to send ("HID_INPUT_REPORT_BYTES").

The most common is that the user's receive and sendbuffers in the application have the same size as the corresponding "report length"s. To achieve this, the buffers can be declared as follows"
var 
    ReceiveBuffer: array[HID_OUTPUT_REPORT_BYTES] of byte;
    SendBuffer:    array[HID_INPUT_REPORT_BYTES]  of byte;
Important:
In all USB documentation the words "IN" and "OUT" are frequently used to indicate the direction of data transfer. Those directions are always "USB host" (e.g. PC) related. So, "IN" means data from the PIC to the host (data OUT from PIC point of view), "OUT" means data from the host to the PIC (data IN from PIC point of view).

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 "(including handling of the "internal" USB_HID send and receivebuffers) based on interrupts received from the PIC's SIE (the USB engine). This is to be done like this:

For P18:
procedure interrupt;
begin
  USB_Interrupt; // USB_HID processing procedure
end;
For P24:
procedure USB1Interrupt(); iv IVT_ADDR_USB1INTERRUPT;
begin
  USB_Interrupt;
end;
The HID initialization procedure ("InitUsb") takes care of the enabling of the necessary interrupts.

Important: There is no need to "force" extra interrupts, e.g. via a timer, the "USB_Interrupt" procedure will only do something when actually an interrupt came from the SIE (the PIC's USB engine).

3. Initialization

The initialization of the USB_HID software is like
  InitUsb;                    // Init USB_HID and start the enumeration process
  repeat until ConfiguredUsb; // wait for the completion of the USB enumeration    
As you can see, the initialisation of USB_HID and starting up of the USB enumeration procedure is done with a call to "InitUsb". This procedure does not wait for the USB enumeration process to complete.
The completeness of the enumeration process can be checked with "ConfiguredUsb": it returns true when emumeration is complete. One should wait for a complete enumeration before attempting further USB_HID activities.

4. Receiving data (PC --> PIC)

Receiving data is done like this:
  if USB_HID_Read(@ReceiveBuffer, NrBytesToReceive) then
  begin
    // process received data here
  end;
As you can see, this routine takes two parameters: the address of the user's receivebuffer and the number of bytes "to receive". The latter is in fact the number of bytes to be copied from the "internal USB_HID receivebuffer" into the user's receivebuffer. The function gives back a boolean value: "true" means that a data packet was received in the internal USB_HID buffer, and that "NrBytesToReceive" bytes were copied from it to the user's receivebuffer; "false" means that there was nothing received.
Make sure that "NrBytesToReceive" is smaller than or equal to the size of the user's receivebuffer.

Remark: the number of bytes received in the "internal USB_HID receivebuffer is always "HID_OUTPUT_REPORT_BYTES", the packet size is a constant value (a USB_HID attribute), "NrBytesToReceive" only defines how many bytes are copied from it. This is the reason why "USB_HID_Read" returns true or false and not the "number of bytes received".

5. Sending data (PIC --> PC)

Sending data is done like this:
  repeat until USB_HID_Write(@SendBuffer, NrBytesToSend); 
Be carefull: this can block your software (it is waiting for HID_Write to succeed).
To avoid this (and thus not block your software) use following code:
  if USB_HID_Write(@SendBuffer, NrBytesToSend) then
  begin
    { writing was successful }
  end else
  begin
    { writing was not successfull, try again later }
  end;

As you can see, two parameters are required by this function: the address of the sendbuffer and the number of bytes to be sent.
The second parameter only defines how many bytes from the user's sendBuffer must be copied into the "internal" HID-USB sendbuffer (which is of size "HID_INPUT_REPORT_BYTES"). The number of bytes that actually will be send is always "HID_INPUT_REPORT_BYTES", regardless of the value of the 2nd parameter.
Make sure the "NrBytesToSend" is smaller than or equal to "HID_INPUT_REPORT_BYTES".

The function "USB_HID_Write" returns "true" if success (data was accepted and will be sent), "false" if no success (data is not accepted to be sent -- the previous send operation was not finished yet, the "internal USB_HID sendbuffer is still occupied --).

Another remark: "USB_HID_Write" does not wait for the actual transmission from the PIC to the PC to happen. It only "prepares" things: it copies data from the user's "SendBuffer" into the "internal" HID-USB sendbuffer and tells it to send. After this the SIE (the PIC's USB engine) takes care of the actual send action.

6. Technical data


-------------------------------------------