Using the PICBASIC PRO(TM) Compiler with the Microchip PIC18Fxxxx full-speed
USB devices.

The USB18 subdirectory contains the PIC18Fxxx USB libraries for the PICBASIC
PRO Compiler, as well as example programs and some documentation files.  USB
programs require several addtional files to operate (which are in the USB18
subdirectory), some of which may require modification for your particular
application.  The files in this subdirectory are:

	18F*.BAS	Device header files that use the USB libraries
	18F*.BAL	Long device header files that use the USB libraries
	CDCDESC.ASM	Descriptor file	for CDC	serial demo
	JADESC.ASM	Descriptor file	for Jan	Axelson	demo
	MOUSDESC.ASM	Descriptor file	for mouse demo
	MCHPCDC.INF	INF file for the CDC serial driver
	USB.TXT		This file
	USB18.ASM	USB assembler file
	USB18.INC	USB definitions	file
	USB18MEM.ASM	USB memory allocation file
	USBCDC.BAS	CDC serial demo	BASIC program file
	USBDESC.ASM	Include	file for descriptor file
	USBJADEM.BAS	Jan Axelson demo BASIC program file
	USBMOUSE.BAS	Mouse demo BASIC program file


USB communications is much more complicated than synchronous (Shiftin and
Shiftout) and asynchronous (Serin, Serout and so forth) communications.
There is much more to know about USB operation that can possibly be described
here.  The USB information on the Microchip web site needs to be studied.
Also, the book "USB Complete" by Jan Axelson may be helpful.



BASIC USB Programs

The PICBASIC PRO(TM) Compiler currently supports both the HID and CDC classes
of USB devices.  The CDC class allows the USB port to look like an asychronous
serial port to PC programs.

A USB program consists of the BASIC source code along with additional USB
files, including USB18.ASM, USB18MEM.ASM, USB18.INC and a USB descriptor
file.  The compiler automatically places the USB routines after the PICBASIC
PRO library code and before the BASIC program code.

There are 2 different header files provided for each USB device.  The ones in
the PBP\USB18 subdirectory automatically include the required USB files
mentioned above.  They also only allow the compiler to access a portion
of the RAM.  The remainder of the RAM is dual port and is used by the USB
peripheral.

The header files in the PBP subdirectory do not include the USB code.  This
allows the devices to be used just like any other PIC.  The reason one may
want to do this is that these PICs have more memory and can run at a faster
clip than most other PICs.  These header files are 18F2450.BAS, 18F2455.BAS,
18F2458.BAS, 18F2550.BAS, 18F2553.BAS, 18F4450.BAS, 18F4455.BAS, 18F4458.BAS,
18F4550.BAS, 18F4553.BAS, 18F65J50.BAS, 18F66J50.BAS, 18F66J55.BAS,
18F67J50.BAS, 18F85J50.BAS, 18F86J50.BAS, 18F86J55.BAS and 18F87J50.BAS.
For PBPL, there are .BAL versions of each of these files.

The USB header files for these PICs are set for a default oscillator of 20MHz.
The other settings for full-speed USB are HSPLL, USB clock is 96MHz PLL / 2
and system clock postscaler is divided by 2.  For low-speed USB operation,
the main changes are to set the system clock postscaler to divide by 4 and
change the define for UCFG_VAL in the descriptor file for the project.  The
sample project descriptor files show settings of UCFG_VAL for both full-
speed and low-speed.  With these settings, for full-speed, the PIC core runs
at 48MHz.  For low-speed, the PIC core runs at 24MHz.

One of the compiler included files is USBDESC.ASM.  This is a user modified
file that contains an include to the actual descriptor file used for the
current project.  Only one descriptor file must be selected in this file.

The header file for the device, the files USB18.ASM, USB18MEM.ASM, USB18.INC,
USBDESC.ASM and the project descriptor file, as well as any desired sample
programs, should be copied to the project source subdirectory before being
used.



A Note About Vendor IDs and Product IDs

Every USB device must have a Vendor ID and a Product ID in order to be
recognized by the PC host.  How do you obtain these numbers?

Strictly speaking, if you plan to manufacture your device, youll need a
unique combination of a Vendor ID number and a Product ID number for your
device before you can sell it.  Depending on what you are trying to do,
there may or may not be a cost involved.

If you are planning to make a number of high-volume products, you'll need to
apply for an official Vendor ID from USB Implementers Forum. There is a cost
for this, so see their web site at http://www.usb.org for details.  They
will provide you with a 16-bit Vendor ID number, which gives you the right
to sell as many as 65536 different USB designs.

If you are only experimenting with a device connected to your own PC in your
own lab, and you are not attempting to sell or distribute your USB device,
you can use an existing Vendor ID such as the one Microchip uses in its
examples, and use any convenient Product ID number that doesn't conflict
with any other USB devices that your PC recognizes.

There is a third alternative available for small commercial projects. If you
plan to manufacture your device in modest production quantities, you can
apply to Microchip for permission to use Microchip's Vendor ID, along with a
Product ID that Microchip will assign to you, free of charge for your
product.  See the Microchip web site for details.

Please do not attempt to sell or distribute your USB device without
permission to use a valid Vendor ID / Product ID combination.



Sample Programs

USBMOUSE.BAS is the Microchip mouse demo written in BASIC.  It makes the mouse
move in a small circle when connected to a PC.  MOUSDESC.ASM contains the
descriptors required by the demo program to operate.  This file is compiled
into the program automatically by PBP.  The descriptor files are named in the
file USBDESC.ASM.  This file can be edited to name another descriptor file.


USBJADEM.BAS is the Jan Axelson demo program written in BASIC.  It
communicates with a program running on the PC, USBHIDIO, that can be found on
Jan Axelson's web site at www.lvr.com.  This demo takes 2 numbers from the PC
program, increments them and sends them back.  It shows how to send data to
and from the PC.  JADESC.ASM contains the descriptors required by the demo
program to operate.  This file is compiled into the program automatically by
PBP.  The descriptor files are named in the file USBDESC.ASM.  This file must
be edited to name the descriptor file JADESC.ASM.


USBCDC.BAS is a BASIC program that demonstrates USB simulating a serial port
on a Windows PC.  Windows asks to install the appropriate driver when a CDC
device is first plugged in.  It actually might take a moment or two for
Windows to discover the device.  After that, Windows will ask for a driver
file.  The file MCHPCDC.INF in the USB18 subdirectory is the file that Windows
can be directed to when it wants the driver information file.  CDCDESC.ASM
contains the descriptors required by the demo program to operate.  This file
is compiled into the program automatically by PBP.  The descriptor files are
named in the file USBDESC.ASM.  This file must be edited to name the
descriptor file CDCDESC.ASM.



New USB Commands

Four new PBP commands have been implemented to support the PIC18Fxxxx full-
speed USB devices.  These commands are shown below:

	USBInit

USBInit needs to be one of the first statements in the program.  It will
initialize the USB portion of the PIC MCU.

	USBIn enpoint, buffer, countvar, label

USBIn gets any available USB data for the endpoint and places it in the
buffer.  Buffer must be a byte array of suitable length to contain the data.
Countvar should be set to the size of the buffer before USBIn is executed.
It will contain the number of bytes transferred to the buffer after USBIn
is executed.  Label will be jumped to if no data is available.

	USBOut endpoint, buffer, count, label

USBOut takes count number of bytes from the buffer and sends them to the USB
endpoint.  If the USB buffer does not have room for the data because of a
pending transmission, no data will be transferred and program execution will
continue at label.

	USBService

USBService needs to be executed repeatedly in the program.  Since the provided
USB code is polled rather than interrupt driven, USBService needs to be
executed at least every 10ms throughout the program.  If it is not, the device
may drop off the USB bus.

When interacting with Windows, at the beginning of the program after USBINIT,
it is required that USBSERVICE be polled at about 250 us per loop.  Even 1ms
may be too slow.  It can take up to 5 seconds to complete the initial
interaction to get to the state of usb_device_state == CONFIGURED_STATE, but
many times it will complete much more quickly.  Then, you have to continue to
poll USBSERVICE to complete the passing of the HID data to the host. Doing it
for another 0.5 seconds seems to be adequate.

See the included USB sample programs for examples of each of these commands.



PICBASIC PRO is a trademark of Microchip Technology Inc. in the U.S.A. and
other countries.
