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:
The HID initialization procedure ("HID_Enable") takes care of the enabling of the necessary interrupts.
As documented, the initialization of the HID software is like
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.
- 0: nothing received
- HID_OUTPUT_REPORT_BYTES: a "HID Report" (with a fixed size of "HID_OUTPUT_REPORT_BYTES") is received.
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:
- The address of the sendbuffer
- The number of bytes to be sent, this parameter always has to have the value "HID_INPUT_REPORT_BYTES".