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:
procedure interrupt;
begin
USB_Interrupt; // USB_HID processing procedure
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).
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
- Full speed USB communications.
- Endpoint 0 (default pipe) packet size: 64.
- "Interrupt" data transfers.
- The maximum send and receive buffersizes are 64 bytes
- The HID "data" pipe is USB endpoint 1.
- The HID "data" interface is USB interface 0.
- No possibility provided to make other "reports" than simply a number of bytes (<= 64).
-------------------------------------------