moved the usb directory to its proper home in ./libmaple

also, removed some old usb file, bootVect.h, which setup the static table for the runtime usb lib that no longer exists and was provided by the bootloader rev 1

1 files changed, 68 insertions, 0 deletions

diff --git a/libmaple/usb/README b/libmaple/usb/README
new file mode 100644
index 0000000..e542dde
--- /dev/null
+++ b/libmaple/usb/README
@@ -0,0 +1,68 @@
+The USB submodule of libmaple is responsible for:
+    initilizing the usb peripheral, scaling the peripheral clocks appropriately, 
+    enabling the interrupt channels to usb, defining the usb isr, resetting the usb
+    disc pin (used to tell the host were alive). Additionally, the usb submodule defines
+    the virtual com port usb applications that is available to all user sketches via Usb.print()
+    and others. 
+
+To use it:
+   Call Usb.init() to enable the IRQ channel, configure the clocks,
+     pull down usb_disc, and setup the vcom buffers
+   Usb.print/ln, available(), read(), write() implement the same
+     interface as Serial1/2/3
+   
+   
+Current Status:
+    Currently, the USB submodule relies on the low level core library provided by ST to access the 
+    usb peripheral registers and implement the usb transfer protocol for control endpoint transfers. 
+    The high level virtual com port application is unfortunately hard to untangle from this low level
+    dependence, and when a new USB core library is written (to nix ST dependence) changes will likely
+    have to be made to virtual com application code. Ideally, the new core library should mimick the 
+    form of MyUSB (LUFA), since this library (USB for AVR) is growing in popularity and in example 
+    applications. Additionally, the usb lib here relies on low level hardware functions that were 
+    just ripped out of the bootloader code (for simplicity) but clearly this should be replaced with 
+    direct accesses to functions provided elsewhere in libmaple.
+
+    The virtual com port serves two important purposes. 1) is allows serial data transfers between
+    user sketches an a host computer. 2) is allows the host machine to issue a system reset by 
+    asserting the DTR signal. After reset, Maple will run the DFU bootloader for a few seconds, 
+    during which the user can begin a DFU download operation ('downloads' application binary into 
+    RAM/FLASH). This without this virtual com port, it would be necessary to find an alternative means
+    to reset the chip in order to enable the bootloader.
+
+    If you would like to develop your own USB application for whatever reason (uses faster isochronous
+    enpoints for streaming audio, or implements the USB HID or Mass Storage specs for examples) then
+    ensure that you leave some hook for resetting Maple remotely in order to spin up the DFU bootloader. 
+    Please make sure to give yourself a unique vendor/product ID pair in your application, as some 
+    operating systems will assign a host-side driver based on these tags.  
+
+    It would be possible to build a compound usb device, that implements endpoints for both the virtual
+    COM port as well as some other components (mass sotrage etc.) however this turns out to be a burden 
+    from the host driver side, as windows and *nix handle compound usb devices quite differently. 
+
+    Be mindful that running the usb application isnt "free." The device must respond to periodic bus 
+    activity (every few milliseconds) by servicing an ISR. Therefore the usb application should be disabled 
+    inside of timing critical applications. In order to disconnect the device from the host, the USB_DISC
+    pin can be asserted (on Maple v1,2,3 this is GPIOC,12). Alternatively, the NVIC can be directly configured
+    to disable the USB LP/HP IRQ's
+
+    This library should exposed through usb.h, do not include any other files direcly in your application. 
+
+    The files inside of usb_lib were provided by ST and are subject to their own license, all other files were
+    written by the LeafLabs team and fall under the MIT license. 
+
+Integration with libmaple:
+    The current usb lib is ported directly from the maple bootloader code, adapted to be a virtual com rather than
+    a DFU device. That means several functions are redefined locally that could have been pulled from elsewhere
+    in libmaple. Thus, ths usb module depends absolutely zero on libmaple, it even ensures that clocks are configured
+    correctly for its operation.
+
+Todo:
+    - write custom low level usb stack to strip out any remaining dependence on ST code
+    - remove dependence on hardware.c, since any functions here really should have their
+      own analogues elsewhere inside libmaple
+    - add a high level usb application library that would allow users to make their own
+      HID/Mass Storage/Audio/Video devices.
+    - implement a Usb.link(SerialX) that forces a passthrough
+      the host computer virtual com to SerialX, and utilizes the
+      line_config commands correctly (sets baud etc)
\ No newline at end of file