aboutsummaryrefslogtreecommitdiffstats
path: root/core/usb/README
blob: e542dde0557ffb89adf738ff75f916497045ffa5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
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)