////

//// These are the functions that are meant to be called by the user: ////
////

////

//// usb_init() - Initializes the USB stack, the USB peripheral and
////

attaches the unit to the usb bus. Enables

////

interrupts. Will wait in an infinite loop until

////

the device enumerates - if you are using

////

connection sense or if the processor should run

////

even if it's not connected to USB then use

////

usb_init_cs() instead.

////

////

////
////
////
////
////

////
////

//// usb_init_cs() - A smaller usb_init(), does not attach unit

////

////

to usb bus or enable interrupts. Since this does

////

////

not attach to the USB, you must periodically call

////

////

usb_task(). See usb_task() for more information.

////

////

////

//// usb_task() - If usb_init_cs() was used to initiate the USB

////

////

peripheral, usb_task() should then be called periodically ////

////

to check the connection sense pin. If the connection

////

sense pin denotes USB is connected and the USB peripheral ////

////

is not attached, this will attach the USB peripheral

////

so the PC can start the enumeration process (and it

////

will enable interrupts). If the connection sense pin

////

denotes USB is not attached and the USB peripheral is

////

running, this will reset the USB peripheral and wait

////

for USB to reconnect (and usb_enumerated() will start

////

////
////
////
////
////
////

////

returning FALSE). If connection sense macro

////

////

(USB_CABLE_IS_ATTACHED) is not defined the usb_task()

////

assumes that USB is always connected.

////

////

////

////

//// usb_attached() - Returns TRUE if the device is attached to a

////

////

USB cable. A macro that looks at the defined

////

connection sense pin. If this returns TRUE

////

it does not mean the PC has connected to it,

////

you need to use usb_enumerated() to check this. ////

////

////
////
////

////

//// usb_enumerated() - Returns TRUE if device has been enumerated

////

(configured) by host, FALSE if it has not.

////

Do not try to use the USB peripheral for

////

sending and receiving packets until you

////

are enumerated.

////

////
////
////

////
////

//// usb_wait_for_enumeration() - Sits in an infinte loop until device ////

////
////

is enumerated.

////
////

//// usb_tbe(endpoint) - Returns TRUE if the endpoint transmit buffer ////

////
////

is free and ready to accept a new packet for transmission.

////

////

//// usb_put_packet(endpoint, ptr, len, tgl) - Sends one packet to the ////
////

host. If you need to send a message that

////

////

spans more than one packet then use

////

////

usb_puts(). Fore more detailed documentation ////

////

////

see usb_hw_layer.h

////

////
////

//// usb_puts(endpoint, ptr, len, timeout) - Sends a multiple packet ////

////

message to the host. If you only need to send one packet,

////

it is more effecient to use usb_put_packet(). This is

////

documented in more detail above the prototype in USB.H.

////

////

////
////

////

//// usb_kbhit(endpoint) - Returns true if OUT endpoint contains data ////

////

from host. This will remain TRUE until

////

usb_put_packet() or usb_flush_out() used.

////

This function will return an invalid response

////

if specified endpoint is not enabled for

////

receiving data.

////

////
////
////
////

////
////

//// len = usb_get_packet(endpoint, ptr, max) - Gets one packet that ////
////

from the host/PC. usb_kbhit() must return TRUE before you ////

////

call this routine or your data may not be valid. This

////

only receives one packet, if you are trying to receive a ////

////

multi-packet message use usb_gets(). For more detailed

////

documentation see usb_hw_layer.h.

////

////

////

////
////

//// len = usb_gets(endpoint, ptr, max, timeout) - Gets multiple

////

////

packets from the host, you would use this instead

////

of usb_get_packet() if you wanted to handle multi-packet ////

////

messages. This is documented in more detail above the

////

prototype in USB.H.

////

////

////

////

////

////

////

////

********* DEFINITIONS / CONFIGURATION **********

////

////

////

//// The following definitions are declared here, but can be

////

//// overwritten in your code. Unless needed otherwise, leave

//// to default value. If confused about a definition read the
//// comments at each defintion
////

////
////

////
////

//// USB_HID_IDLE (TRUE) - Set to TRUE if your device supports

////

Set_Idle HID class request. Set to

////

False if you do not (device will

////

send a Wrong-state if computer

////

sends a Set_Idle / Get_Idle command) ////

////

NOTE: If you set to TRUE you must

////

provide your own code. See

////

usb_isr_tkn_setup_ClassInterface() in ////

////

usb.c

////

////
////
////

////
////

////
////

//// USB_HID_BOOT_PROTOCOL (FALSE) - Set to TRUE if your device

supports ////
////

Set_Protocl HID class request. Set to ////

////

False if you do not (device will

////

send a Wrong-state if computer

////

////

sends a Set_Protocl / Get_Protocol

////

////

command).

////

NOTE: If you set to TRUE you must

////

////
////

////

////

provide your own code in the

////

application that properly send boot

////

or HID packets.

////

////
////

////
////

//// USB_MAX_EP0_PACKET_LENGTH (8) - Max Packet size for Endpoint 0. ////

////

The hardware level driver (ex

////

pic18_usb.h will define this value if ////

////

not already overwritten). Increasing ////

////

this size will speed up the

////

////

enumeration process.

////

////

////

////

//// USB_EPx_RX_ENABLE (USB_ENABLE_DISABLED) - Where x is the

////

endpoint number. Change this define

////

to specify what kind of transfer method ////

////

this RX (PC to device) endpoint uses.

////

////

////

Here is the list of valid transfer methods: ////

////

USB_ENABLE_CONTROL

////

USB_ENABLE_ISOCHRONOUS

////

USB_ENABLE_BULK

////

USB_ENABLE_INTERRUPT

////

////

USB_ENABLE_DISABLED

////

////
////
////

////

Don't forget that you must specify the

////

transfer method properly in your endpoint ////

////

descriptor, too.

////

////

////

////
////

//// USB_EPx_RX_SIZE (0) - For some hardware it is important to know ////

////

how much memory to reserve for receiving

////

packets.

////

////

////
////

//// *** NOTE *** You must have both USB_EPx_RX_ENABLE defined and
////

USB_EPx_RX_SIZE defined (non 0) to enable a RX

////

endpoint.

////

////

//// *** NOTE *** Endpoint 0 is always enabled.

////

////

////

//// USB_EPx_TX_ENABLE (USB_ENABLE_DISABLED) - Where x is the

////

endpoint number. Change this define

////

to specify what kind of transfer method ////

////

this TX (device to PC) endpoint uses.

////

////

////

////

////

Here is the list of valid transfer methods: ////

////

USB_ENABLE_CONTROL

////

////

USB_ENABLE_ISOCHRONOUS

////

USB_ENABLE_BULK

////

USB_ENABLE_INTERRUPT

////

////

USB_ENABLE_DISABLED

////

////
////

////

Don't forget that you must specify the

////

transfer method properly in your endpoint ////

////

descriptor, too.

////

////

////
////

//// USB_EPx_TX_SIZE (0) - For some hardware it is important to know ////

////

how much memory to reserve for transmitting ////

////

packets.

////

////
////

//// *** NOTE *** You must have both USB_EPx_TX_ENABLE defined and
////

USB_EPx_TX_SIZE defined (non 0) to enable a TX

////

endpoint.

////

////

////

////

////

////

////

//// USB_HID_DEVICE (TRUE) - HID devices require extra code to handle ////
////

HID requests. You can disable to save

////

////

ROM space if you are not using a HID

////

////

device. If you are not using a HID

////

device you must provide your own O/S

////

(Windows) driver.

////

////
////

////
////

//// The other definitions should not be changed.

////

////

////

///////////////////////////////////////////////////////////////////////////
////

////

//// Version History:

////

////
////

//// September 24th, 2010:

////

//// Many descriptor files had the self powered bit set incorrectly ////
////

based on USB_CONFIG_BUS_POWER.

////

////
////

//// September 9th, 2010:

////

//// USB_CONFIG_HID_TX_SIZE and USB_CONFIG_HID_RX_SIZE were

backwards ////
////

in HID report descriptor of usb_desc_hid.h

////

////

////

//// September 2nd, 2010:

////

//// Problem with descriptors larger than 127 bytes on 16-bit PICs
////

(dsPIC, PIC24) resolved.

////

////

////
////

//// August 31st, 2010:

////

//// Added USB_HW_MCHP_18F46J50, USB_HW_MCHP_18F14K50 and

//// USB_HW_GENERIC_18F67J50 hardware.
////

////

////
////

//// April 28th, 2010:

////

//// USB_CON_SENSE_PIN replaced with USB_CABLE_IS_ATTACHED()

////

macro. If USB_CON_SENSE_PIN is defined, it will create

////

USB_CABLE_IS_ATTACHED() macro for you (for backwards

////

compatibility).

////

////
////
////

//// March 5th, 2009:

////

//// Cleanup for Wizard.

////

//// PIC24 Initial release.

////

////
////

//// July 13th, 2005:

////

//// usb_ep_tx_size[] and usb_ep_rx_size[] changed to 16bits

////
//// June 20th, 2005:
//// Initial 18fxx5x release

////

////

//// usb_endpoint_is_valid() prototyped.

////

////

////

//// Nov 13th, 2009:

////
////
////

////

////

////

////

//// May 13th, 2005:

////

//// Beta release, only works with 18Fxx5x hardware layer.

////

//// Now supports multiple interfaces (many defines in descriptors

//// will have to be changed, see examples)
////

////
////

//// Mar 21st, 2005:

////

//// Initial Alpha Release with PIC18Fxx5x support. (ONLY TESTED

//// WITH 18F4550)

////

////

//// usb_gets() and usb_puts() changed (see usb.c)

////

////

////

//// June 24th, 2004:

////

//// Optimization and cleanup.

////

////

The following definitions changed:

////
////

//// USB_EPx_TX_ENABLE and USB_EPx_RX_ENABLE have changed. See

usb.h ////
//// USB_CONFIG_DESCRIPTORS[] removed

////

//// USB_CONFIG_DESC_LEN changed to USB_DESC_CONFIG_LEN

////

//// USB_INTERFACE_DESC_LEN changed to USB_DESC_INTERFACE_LEN

//// USB_CLASS_DESC_LEN changed to USB_DESC_CLASS_LEN

////
////

//// USB_ENDPOINT_DESC_LEN changed to USB_DESC_ENDPOINT_LEN

//// USB_CONFIG_DESC_KEY changed to USB_DESC_CONFIG_TYPE

////
////

//// USB_INTERFACE_DESC_KEY changed to USB_DESC_INTERFACE_TYPE

//// USB_CLASS_DESC_KEY changed to USB_DESC_CLASS_TYPE

////
////

//// USB_ENDPOINT_DESC_KEY changed to USB_DESC_ENDPOINT_TYPE

//// USB_STRING_X[] arrays removed, see USB_STRING_DESC[] and
////

USB_STRING_DESC_OFFSET[]

////

////
////

//// dev_req, curr_config, status_device and getdesc_type global

////

variables moved into struct USB_stack_status

////

////

////

////

//// October 15th, 2003: Support for boot protocol added.

////

////

Set USB_HID_BOOT_PROTOCOL to TRUE to support this.

////

The array hid_protocol[] saves which protocol mode each ////

////

interface is in. It is your applications job to send

////

data that either fit the boot protocol or HID protocol. ////

////

////

////

//// May 6th, 2003: Fixed a potential stack overflow using PCM
////

//// August 2nd, 2002: Initial Public Release

////

////

//// October 29th, 2002: New definition added to USB_STATES

////

////

////

////