diff options
Diffstat (limited to 'libmaple/usb')
| -rw-r--r-- | libmaple/usb/README | 116 |
1 files changed, 70 insertions, 46 deletions
diff --git a/libmaple/usb/README b/libmaple/usb/README index e542dde..f3970b6 100644 --- a/libmaple/usb/README +++ b/libmaple/usb/README @@ -1,9 +1,11 @@ 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. + + Initializing 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, @@ -13,56 +15,78 @@ To use it: 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. + 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. + 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. + 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. + 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 + 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. + 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. + 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. + + 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. + + - 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 + line_config commands correctly (sets baud etc) |