diff --git a/doxygen/getting_started.md b/doxygen/getting_started.md index 9da3327b..6f7075ea 100644 --- a/doxygen/getting_started.md +++ b/doxygen/getting_started.md @@ -26,23 +26,39 @@ tests | Unit tests for the stack tinyusb | All sources files for tinyusb stack itself. vendor | Source files from 3rd party such as freeRTOS, fatfs etc ... -*repo/demos* is the folder where all the application & project files are located. There are demos for both device and hosts. For each, there are different projects for each of supported RTOS. +*demos* is the folder where all the application & project files are located. There are demos for both device and hosts. For each, there are different projects for each of supported RTOS. ## Add tinyusb to your project It is relatively simple to incorporate tinyusb to your (existing) project -1. Copy core folder **repo/tinyusb** to your project. Let's say it is *your_project/tinyusb* +1. Copy core folder **tinyusb** to your project. Let's say it is *your_project/tinyusb* 2. Add all the .c in the core folder to your project settings (uvproj, ewp, makefile) 3. Add *your_project/tinysb* to your include path. Also make sure your current include path also contains the configuration file tusb_config.h. Or you could simply put the tusb_config.h into the tinyusb folder as well. -4. Make sure all required macros such as TUSB_CFG_MCU are all defined properly in tusb_config.h. +4. Make sure all required macros are all defined properly in tusb_config.h (configure file in demo application is sufficient, but you need to add a few more such as TUSB_CFG_MCU, TUSB_CFG_OS, TUSB_CFG_OS_TASK_PRIO since they are passed by IDE/compiler to maintain a unique configure for all demo projects). +5. If you use the device stack, make sure you have created/modified usb descriptors for your own need. Ultimately you need to fill out required pointers in tusbd_descriptor_pointers for that stack to work. +6. Add tusb_init() call to your reset initialization code. +7. Implement all enabled classes's callbacks. +8. If you dont use any RTOSes at all, you need to continuously and/or periodically call tusb_task_runner() function. Most of the callbacks and functionality are handled and invoke within the call of that task runner. +~~~{.c} +int main(void) +{ + your_init_code(); + tusb_init(); // initialize tinyusb stack + + while(1) // the mainloop + { + your_application_code(); + + tusb_task_runner(); // handle tinyusb event, task etc ... + } +} +~~~ \subpage md_boards_readme -\subpage md_doxygen_started_build_demo - -\subpage md_doxygen_started_run_demo +\subpage md_doxygen_started_demo \subpage md_doxygen_tools \ No newline at end of file diff --git a/doxygen/started_run_demo.md b/doxygen/started_demo.md similarity index 90% rename from doxygen/started_run_demo.md rename to doxygen/started_demo.md index 97427477..5e13815e 100644 --- a/doxygen/started_run_demo.md +++ b/doxygen/started_demo.md @@ -1,6 +1,6 @@ -# Run Demos # +# Demos # -For simplicity and user's convenience, there are only 2 basic application demos which are *Device* and *Host* respectively. Each application demo, however, has a few projects, each for its supported RTOS. For instance in the /demo/device you will find: +For simplicity and user's convenience, there are only 2 basic application demos which are *Device* and *Host* respectively. Each application demo, however, has a few projects, each for its supported RTOS. For instance, in addition to the *src* folder, you will also find in the /demo/device - device\_os\_none for no RTOS - device\_freertos for freeRTOS @@ -50,6 +50,7 @@ In order to run application demo, you would need - A supported toolchain: LPCXpresso, Keil, IAR. +\subpage md_doxygen_started_build_demo \subpage md_doxygen_started_device_demo diff --git a/doxygen/started_device_demo.md b/doxygen/started_device_demo.md index 915715a6..eadf3434 100644 --- a/doxygen/started_device_demo.md +++ b/doxygen/started_device_demo.md @@ -4,10 +4,77 @@ **Table of Contents** -- [LPCXpresso](#lpcxpresso) -- [Keil](#keil) -- [IAR](#iar) -- [Configure demo](#configure-demo) +- [Human Interface Device (HID)](#human-interface-device-hid) + - [Keyboard](#keyboard) + - [Mouse](#mouse) +- [Mass Storage Class Device (MSC)](#mass-storage-class-device-msc) +- [Communication Class Device (CDC)](#communication-class-device-cdc) + - [Serial](#serial) +device application code is store at *demos/device/src* containing + +File | Description +----- | ------------- +main.c | Initialization (board, stack) and a RTOS task scheduler call or just simple a indefinite loop for non OS to invoke class-specific tasks. +tusb_config.h | tinyusb stack configuration. +tusb_descriptors(c,h) | contains all the required usb descriptors for all combination of supported classes. And definition of stack-required variable *tusbd_descriptor_pointers*. +app_os_prio.h | RTOS task priority definitions +Class-specific | Application files for supported classes. + +The demo will start with the greeting of enabled classes and chosen RTOS then start to blink an LED at 1 Hz. + +## Prerequisites ## + +In order to run application demo, you would need + +- A [supported development board](../../boards/readme.md) with at least a button for mouse, keyboard demo. +- A supported toolchain: LPCXpresso, Keil, IAR. +- A decent terminal such as [Tera Term](http://en.sourceforge.jp/projects/ttssh2/) for CDC Serial. + +## Human Interface Device (HID) + +### Keyboard + +After the board get enumerated successfully, you can try to press some buttons while opening notepad. It should get some characters out accordingly. Hint: + +Notes: The very same buttons may also used by Mouse application. You can get the mouse moving and character, should you enable both. + +### Mouse + +After the board get enumerated successfully, you can try to press some buttons. The mouse's cursor should move accordingly. + +Notes: The very same buttons may also used by Keyboard application. You can get the mouse moving and character, should you enable both. + +## Mass Storage Class Device (MSC) + +This class is very simple, as soon as the demo work, you could open the demo drive. Inside, you should find a *README.TXT* file which contains a few lines of descriptions. The demo drive's format is FAT12 and only has 8KB, which is the smallest possible to work with most host OS (Windows/Linux). + +Notes: The entire disk contents ( 8KB ) is located on MCU's SRAM if possible (such as lpc43xx, lpc175x_6x). For MCU (lpc11u, lpc13u) that cannot afford that, the contents is instead on internal Flash which make the demo drive is read-only. + +## Communication Class Device (CDC) + +CDC has several subclass, currently tinyusb only supports the popular *Abstract Control Model (ACM)* + +### Serial + +The virtual COM is also as easy as MSC. Except that we need to "install" driver for the first plug if your host OS is Windows, Linux should be able to work right away. + +**Install Driver for Windows** + +Actually Windows already has the needed driver to operate with virtual serial of CDC-ACM, the *usbser*. However, since it also use Abstract Control Model for other purposes, it requires us to tell exactly which VendorID/ProductID comibination should be used as a virtual serial. The demo's src folder includes *WinCDCdriver.inf* to do just that. + +Firstly open *Device Manager*, we should find our board under "Other devices", right click on it and choose "Update Driver Software..." + +![Serial Install Driver](http://docs.tinyusb.org/images/demo_serial_driver.png) + +Then choose "Browse my computer for driver software" then navigate to the device demo's *src* and click next. Since I am nowhere near a known publisher to Microsoft, it will warn you with a scary dialog. With all your trust in me, click next and hope that nothing harmful will ever happen and we are done with the driver. + +![Serial Install Driver](http://docs.tinyusb.org/images/demo_serial_driver2.png) + +**Testing Demo** + +Connect to the "tinyusb Serial Port" with your terminal application, and start to type. You should get echo back as the CDC serial application demo is written to transmit what it received. + +![Serial Connect](http://docs.tinyusb.org/images/demo_cdc_connect.png) \ No newline at end of file diff --git a/doxygen/started_host_demo.md b/doxygen/started_host_demo.md index ce23016d..f94ca761 100644 --- a/doxygen/started_host_demo.md +++ b/doxygen/started_host_demo.md @@ -4,10 +4,44 @@ **Table of Contents** -- [LPCXpresso](#lpcxpresso) -- [Keil](#keil) -- [IAR](#iar) -- [Configure demo](#configure-demo) +- [Human Interface Device (HID)](#human-interface-device-hid) + - [Keyboard](#keyboard) + - [Mouse](#mouse) +- [Mass Storage Class Device (MSC)](#mass-storage-class-device-msc) +- [Communication Class Device (CDC)](#communication-class-device-cdc) + - [Serial](#serial) +device application code is store at *demos/device/src* containing + +File | Description +----- | ------------- +main.c | Initialization (board, stack) and a RTOS task scheduler call or just simple a indefinite loop for non OS to invoke class-specific tasks. +tusb_config.h | tinyusb stack configuration. +app_os_prio.h | RTOS task priority definitions +Class-specific | Application files for supported classes. + +The demo will start with the greeting of enabled classes and chosen RTOS then start to blink an LED at 1 Hz. + +## Prerequisites ## + +In order to run application demo, you would need + +- A [supported development board](../../boards/readme.md) with at least a button for mouse, keyboard demo. +- A supported toolchain: LPCXpresso, Keil, IAR. +- A [ANSI escape](http://en.wikipedia.org/wiki/ANSI_escape_code) supported terminal such as [Tera Term](http://en.sourceforge.jp/projects/ttssh2/) to demonstrate properly. + +## Human Interface Device (HID) + +### Keyboard + + + +### Mouse + +## Mass Storage Class Device (MSC) + +## Communication Class Device (CDC) + +### Serial diff --git a/doxygen/tools.md b/doxygen/tools.md index 50c5844d..d5c49c25 100644 --- a/doxygen/tools.md +++ b/doxygen/tools.md @@ -1,7 +1,13 @@ # Tools +This folder contain several helpful tools that will ease our USB development process. Some are small enough to be included here, some you will need to download by yourself. + ## USB Tree View It is the enhanced version of Microsoft USBView and is a very handy windows application from http://www.uwe-sieber.de for viewing usb devices and their descriptors. -![usb_tree_view.png](http://docs.tinyusb.org/images/usb_tree_view.PNG) \ No newline at end of file +![usb_tree_view.png](http://docs.tinyusb.org/images/usb_tree_view.png) + +## Tera Term + +For most demo, UART is the default/prefer way to interact with user, thus I would recommend a decent terminal such as [Tera Term](http://en.sourceforge.jp/projects/ttssh2/). Especially host demo requires a [ANSI escape](http://en.wikipedia.org/wiki/ANSI_escape_code) supported terminal to demonstrate properly. \ No newline at end of file