added the skeleton dir for the usb application lib, since were still dependent on st for low level access, the entire usb

stack lives in the core application level (not in libmaple). the next project should be to include some low level usb stack in
the libmaple

1 files changed, 37 insertions, 0 deletions

diff --git a/libmaple/usb/README b/libmaple/usb/README
new file mode 100644
index 0000000..035b566
--- /dev/null
+++ b/libmaple/usb/README
@@ -0,0 +1,37 @@
+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. 
+
+    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. 
+
+    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
\ No newline at end of file