# usb_drv

USB driver library

Author | Albert Faber, Copyright © 2008..2021, all rights reserved.
Adapted-by | Rob Jansen
Compiler | 2.5r5

Description

    This file contains the lowl level USB driver routines. It constrols
    the USB serial interface engine, by managing the input and output transfers,
    and calling the defined callback function when required.

Sources

    http://www.usb.org ; for USB specifications
             http://www.lvr.com/usbc.htm ; a lot of information about USB
             http://www.beyondlogic.org/ ; also a nice with with useful information

Notes

    There are two options to use the USB driver:
           1) Without interrupts by frequently calling 'usb_serial_flush()'
              frequently in the main loop.
           2) Using interrupts to make timing less critical. In that case no
              calls to 'usb_serial_flush()' are needed.
              This can be activated by defining: const USB_INTERRUPT_DRIVEN = TRUE

Dependencies

No dependency found

## Summary

### Global variables/contants

### Procedures

- `usb_enable_module()`
- `usb_handle_stall()`
- `usb_setup()`
- `usb_handle_isr()`

Private

- `_usb_handle_standard_request()`
- `_usb_ints_on()`
- `_usb_handle_transaction()`
- `_usb_handle_reset()`

### Functions

- `usb_is_configured() return bit`
- `usb_get_state() return byte`

## API details

### Global variables/contants

### Procedures

- `usb_enable_module()`

      Procedure to turn on the USB device

- `usb_handle_stall()`

      Procedure can be called when the USB device has to be stalled

- `usb_setup()`

      Procedure to intialize the USB device, it will only do the setup, to enable
      the USB device, use the usb_enable() procedure

- `usb_handle_isr()`

      This is the heart of the USB library, all pending IO transfers are handled by
      this main (interrupt) service routine. The routine can be used interrupt based
      or by polling.
      When using interrupt, it will occur at least once ever 1 ms since the Start Of
      Frame (SOF) package is sent every 1 ms by the Host.

Private

- `_usb_handle_standard_request()`

      Internal procedure to handle standard USB device requests.
      it will take care of the overall state of the device
      ) performing USB buffer management
      ) controlling the SIE
      ) call the callback function if required
      The usb_sdp_buffer contains the request as given by the SETUP package.

- `_usb_ints_on()`

      Internal procedure to set the correct interrupt flags. The driver can be used
      interrupt driven or on a polling basis.

- `_usb_handle_transaction()`

      Internal procedure to handle the USB transactions
      it will take care of the overall state of the device
      ) performing USB buffer management
      ) controlling the SIE
      ) call the callback function if required
      This function is called when the TRNIF flag is set. USTAT holds the
      endpoint information.

- `_usb_handle_reset()`

      Internal procedure to reset the USB device
      Reset is initiated by the Host.

### Functions

- `usb_is_configured() return bit`

      Function returns true if the usb device has been completely configured, otherwise
      return value will be false

- `usb_get_state() return byte`

      Get the state of the USB device
      USB_STATE_POWERED -> USB device is powered up, ready to start negotiating
      USB_STATE_DEFAULT -> USB device is now negotiating
      USB_STATE_ADDRESS -> USB device now has an address
      USB_STATE_CONFIGURED -> USB device is completely configured and ready to rock and roll

## Related samples

Here are the list of samples which use this library:

16f1455 | 16f1455_usb_hid_mouse.jal
16f1455 | 16f1455_usb_hid_generic.jal
18f14k50 | 18f14k50_usb_bootloader.jal
18f14k50 | 18f14k50_usb_hid_mouse.jal
18f14k50 | 18f14k50_usb_hid_generic.jal
18f14k50 | 18f14k50_usb_bootloader_autostart.jal
18f2450 | 18f2450_usb_bootloader.jal
18f2450 | 18f2450_usb_bootloader_autostart.jal
18f2450 | 18f2450_usb_hid_generic.jal
18f2450 | 18f2450_usb_hid_mouse.jal
18f2550 | 18f2550_usb_bootloader_autostart.jal
18f2550 | 18f2550_usb_hid_mouse.jal
18f2550 | 18f2550_usb_hid_generic.jal
18f4550 | 18f4550_usb_bootloader_autostart.jal
18f4550 | 18f4550_usb_hid_mouse.jal
18f4550 | 18f4550_usb_hid_generic.jal
18f4550 | 18f4550_usb_bootloader.jal
18f67j50 | 18f67j50_usb_hid_mouse.jal
18f67j50 | 18f67j50_usb_bootloader_autostart.jal
18f67j50 | 18f67j50_usb_hid_generic.jal