From 10d5dac9137adfd6c14d96e1079f08447eacd9d8 Mon Sep 17 00:00:00 2001 From: hathach Date: Fri, 4 Sep 2020 11:20:09 +0700 Subject: update doc --- docs/boards.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/boards.md b/docs/boards.md index 1b3de29e9..309f5e5d9 100644 --- a/docs/boards.md +++ b/docs/boards.md @@ -19,7 +19,7 @@ This code base already had supported for a handful of following boards (sorted a - [DA14695 Development Kit – USB](https://www.dialog-semiconductor.com/products/da14695-development-kit-usb) - [DA1469x Development Kit – Pro](https://www.dialog-semiconductor.com/products/da14695-development-kit-pro) -### MicroChip SAMD +### MicroChip SAM - [Adafruit Circuit Playground Express](https://www.adafruit.com/product/3333) - [Adafruit Feather M0 Express](https://www.adafruit.com/product/3403) @@ -28,9 +28,10 @@ This code base already had supported for a handful of following boards (sorted a - [Adafruit ItsyBitsy M4 Express](https://www.adafruit.com/product/3800) - [Adafruit Metro M0 Express](https://www.adafruit.com/product/3505) - [Adafruit Metro M4 Express](https://www.adafruit.com/product/3382) +- [Great Scott Gadgets LUNA](https://greatscottgadgets.com/luna/) - [Microchip SAMD11 Xplained](https://www.microchip.com/developmenttools/ProductDetails/atsamd11-xpro) +- [Microchip SAMG55 Xplained Pro Evaluation Kit](https://www.microchip.com/DevelopmentTools/ProductDetails/PartNO/ATSAMG55-XPRO) - [Seeeduino Xiao](https://www.seeedstudio.com/Seeeduino-XIAO-Arduino-Microcontroller-SAMD21-Cortex-M0+-p-4426.html) -- [Great Scott Gadgets LUNA](https://greatscottgadgets.com/luna/) ### Nordic nRF5x -- cgit v1.3.1 From 25bb8830c5db7985906d2540da2a35e49edddb75 Mon Sep 17 00:00:00 2001 From: hathach Date: Sat, 12 Sep 2020 09:26:41 +0700 Subject: doc: merge example/readme.md into docs/getting_started.md --- .github/ISSUE_TEMPLATE/bug_report.md | 2 +- docs/getting_started.md | 114 +++++++++++++++++++++++++++++++---- examples/readme.md | 104 -------------------------------- 3 files changed, 103 insertions(+), 117 deletions(-) delete mode 100644 examples/readme.md (limited to 'docs') diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 5160e9f84..9f956f9d8 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -26,4 +26,4 @@ Steps to reproduce the behavior: If applicable, add screenshots, bus capture to help explain your problem. **Log** -Please provide the stack's log (uart/rtt/swo) where the issue occurred, best with comments to explain the actual events. To enable logging, add `LOG=2` to to the make command if building with stock examples or set `CFG_TUSB_DEBUG=2` in your tusb_config.h. More information can be found at [example's readme](/examples/readme.md) +Please provide the stack's log (uart/rtt/swo) where the issue occurred, best with comments to explain the actual events. To enable logging, add `LOG=2` to to the make command if building with stock examples or set `CFG_TUSB_DEBUG=2` in your tusb_config.h. More information can be found at [example's readme](/docs/getting_started.md) diff --git a/docs/getting_started.md b/docs/getting_started.md index e282b4171..8d22a3127 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -1,14 +1,6 @@ # Getting Started # -## Get - -``` -git clone git@github.com:hathach/tinyusb.git tinyusb -``` - -*examples* 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. Click to have more information on how to [build](../examples/readme.md) and run [device](../examples/device/readme.md) demos. - -## Add tinyusb to your project +## Add TinyUSB to your project It is relatively simple to incorporate tinyusb to your (existing) project @@ -37,6 +29,104 @@ int main(void) } ~~~ -[//]: # "\subpage md_boards_readme" -[//]: # "\subpage md_doxygen_started_demo" -[//]: # "\subpage md_tools_readme" +## Examples + +For your convenience, TinyUSB contains a handful of examples for both host and device with/without RTOS to quickly test the functionality as well as demonstrate how API() should be used. Most examples will work on most of [the supported Boards](boards.md). Firstly we need to `git clone` if not already + +``` +$ git clone https://github.com/hathach/tinyusb tinyusb +$ cd tinyusb +``` + +TinyUSB examples includes external repos aka submodules to provide low-level MCU peripheral's driver as well as external libraries such as FreeRTOS to compile with. Therefore we will firstly fetch those mcu driver repo by running this command in the top folder repo + +``` +$ git submodule update --init --recursive +``` + +It will takes a bit of time due to the number of supported MCUs, luckily we only need to do this once. Or if you only want to test with a specific mcu, you could only fetch its driver submodule. + +### Build + +To build example, first change directory to an example folder. + +``` +$ cd examples/device/cdc_msc +``` + +Then compile with `make BOARD=[board_name] all`, for example + +``` +$ make BOARD=feather_nrf52840_express all +``` + +#### Port Selection + +If a board has several ports, one port is chosen by default in the individual board.mk file. Use option `PORT=x` To choose another port. For example to select the HS port of a STM32F746Disco board, use: + +``` +$ make BOARD=stm32f746disco PORT=1 all +``` + +#### Port Speed + +A MCU can support multiple operational speed. By default, the example build system will use the fastest supported on the board. Use option `SPEED=full/high` e.g To force F723 operate at full instead of default high speed + +``` +$ make BOARD=stm32f746disco SPEED=full all +``` + +### Debug + +To compile for debugging add `DEBUG=1`, for example + +``` +$ make BOARD=feather_nrf52840_express DEBUG=1 all +``` + +#### Log + +Should you have an issue running example and/or submitting an bug report. You could enable TinyUSB built-in debug logging with optional `LOG=`. LOG=1 will only print out error message, LOG=2 print more information with on-going events. LOG=3 or higher is not used yet. + +``` +$ make BOARD=feather_nrf52840_express LOG=2 all +``` + +#### Logger + +By default log message is printed via on-board UART which is slow and take lots of CPU time comparing to USB speed. If your board support on-board/external debugger, it would be more efficient to use it for logging. There are 2 protocols: + +- `LOGGER=rtt`: use [Segger RTT protocol](https://www.segger.com/products/debug-probes/j-link/technology/about-real-time-transfer/) + - Cons: requires jlink as the debugger. + - Pros: work with most if not all MCUs + - Software viewer is JLink RTT Viewer/Client/Logger which is bundled with JLink driver package. +- `LOGGER=swo`: Use dedicated SWO pin of ARM Cortex SWD debug header. + - Cons: only work with ARM Cortex MCUs minus M0 + - Pros: should be compatible with more debugger that support SWO. + - Software viewer should be provided along with your debugger driver. + +``` +$ make BOARD=feather_nrf52840_express LOG=2 LOGGER=rtt all +$ make BOARD=feather_nrf52840_express LOG=2 LOGGER=swo all +``` + +### Flash + +`flash` target will use the default on-board debugger (jlink/cmsisdap/stlink/dfu) to flash the binary, please install those support software in advance. Some board use bootloader/DFU via serial which is required to pass to make command + +``` +$ make BOARD=feather_nrf52840_express flash +$ make SERIAL=/dev/ttyACM0 BOARD=feather_nrf52840_express flash +``` + +Since jlink can be used with most of the boards, there is also `flash-jlink` target for your convenience. + +``` +$ make BOARD=feather_nrf52840_express flash-jlink +``` + +Some board use uf2 bootloader for drag & drop in to mass storage device, uf2 can be generated with `uf2` target + +``` +$ make BOARD=feather_nrf52840_express all uf2 +``` diff --git a/examples/readme.md b/examples/readme.md deleted file mode 100644 index f6cd380b6..000000000 --- a/examples/readme.md +++ /dev/null @@ -1,104 +0,0 @@ -# Examples - -## Clone this repo - -``` -$ git clone https://github.com/hathach/tinyusb tinyusb -$ cd tinyusb -``` - -## Fetch submodule MCUs drivers - -TinyUSB examples includes external repos aka submodules to provide low-level MCU peripheral's driver to compile with. Therefore we will firstly fetch those mcu driver repo by running this command in the top folder repo - -``` -$ git submodule update --init --recursive -``` - -It will takes a bit of time due to the number of supported MCUs, luckily we only need to do this once. Or if you only want to test with a specific mcu, you could only update its driver submodule - -## Build - -[Here is the list of supported Boards](docs/boards.md) that should work out of the box with provided examples (hopefully). -To build example, first change directory to example folder. - -``` -$ cd examples/device/cdc_msc -``` - -Then compile with `make BOARD=[your_board] all`, for example - -``` -$ make BOARD=feather_nrf52840_express all -``` - -**Port Selection** - -If a board has several ports, one port is chosen by default in the individual board.mk file. Use option `PORT=x` To choose another port. For example to select the HS port of a STM32F746Disco board, use: - -``` -$ make BOARD=stm32f746disco PORT=1 all -``` - -**Port Speed** - -A MCU can support multiple operational speed. By default, the example build system will use the fastest supported on the board. Use option `SPEED=full/high` e.g To force F723 operate at full instead of default high speed - -``` -$ make BOARD=stm32f746disco SPEED=full all -``` - -### Debug - -To compile for debugging with debug symbols add `DEBUG=1`, for example - -``` -$ make BOARD=feather_nrf52840_express DEBUG=1 all -``` - -#### Log - -Should you have an issue running example and/or submitting an bug report. You could enable TinyUSB built-in debug logging with optional `LOG=`. LOG=1 will only print out error message, LOG=2 print more information with on-going events. LOG=3 or higher is not used yet. - -``` -$ make BOARD=feather_nrf52840_express LOG=2 all -``` - -#### Logger - -By default log message is printed via on-board UART which is slow and take lots of CPU time comparing to USB speed. If your board support on-board/external debugger, it would be more efficient to use it for logging. There are 2 protocols: - -- `LOGGER=rtt`: use [Segger RTT protocol](https://www.segger.com/products/debug-probes/j-link/technology/about-real-time-transfer/) - - Cons: requires jlink as the debugger. - - Pros: work with most if not all MCUs - - Software viewer is JLink RTT Viewer/Client/Logger which is bundled with JLink driver package. -- `LOGGER=swo`: Use dedicated SWO pin of ARM Cortex SWD debug header. - - Cons: only work with ARM Cortex MCUs minus M0 - - Pros: should be compatible with more debugger that support SWO. - - Software viewer should be provided along with your debugger driver. - -``` -$ make BOARD=feather_nrf52840_express LOG=2 LOGGER=rtt all -$ make BOARD=feather_nrf52840_express LOG=2 LOGGER=swo all -``` - -## Flash - -`flash` target will use the default on-board debugger (jlink/cmsisdap/stlink/dfu) to flash the binary, please install those support software in advance. Some board use bootloader/DFU via serial which is required to pass to make command - -``` -$ make BOARD=feather_nrf52840_express flash -$ make SERIAL=/dev/ttyACM0 BOARD=feather_nrf52840_express flash -``` - -Since jlink can be used with most of the boards, there is also `flash-jlink` target for your convenience. - -``` -$ make BOARD=feather_nrf52840_express flash-jlink -``` - -Some board use uf2 bootloader for drag & drop in to mass storage device, uf2 can be generated with `uf2` target - -``` -$ make BOARD=feather_nrf52840_express all uf2 -``` -- cgit v1.3.1 From a2379060b6d47eec6d5e9499258bc62eb5a015d7 Mon Sep 17 00:00:00 2001 From: Jean Gressmann Date: Tue, 6 Oct 2020 17:36:11 +0200 Subject: Adds D5035-01 to the list of supported boards --- docs/boards.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/boards.md b/docs/boards.md index 309f5e5d9..f49b247ac 100644 --- a/docs/boards.md +++ b/docs/boards.md @@ -4,7 +4,7 @@ The board support code is only used for self-contained examples and testing. It - One LED : for status - One Button : to get input from user - One UART : optional for device, but required for host examples - + ## Supported Boards This code base already had supported for a handful of following boards (sorted alphabetically) @@ -28,6 +28,7 @@ This code base already had supported for a handful of following boards (sorted a - [Adafruit ItsyBitsy M4 Express](https://www.adafruit.com/product/3800) - [Adafruit Metro M0 Express](https://www.adafruit.com/product/3505) - [Adafruit Metro M4 Express](https://www.adafruit.com/product/3382) +- [D5035-01](https://github.com/RudolphRiedel/USB_CAN-FD) - [Great Scott Gadgets LUNA](https://greatscottgadgets.com/luna/) - [Microchip SAMD11 Xplained](https://www.microchip.com/developmenttools/ProductDetails/atsamd11-xpro) - [Microchip SAMG55 Xplained Pro Evaluation Kit](https://www.microchip.com/DevelopmentTools/ProductDetails/PartNO/ATSAMG55-XPRO) @@ -114,7 +115,7 @@ This code base already had supported for a handful of following boards (sorted a ### TI - [MSP430F5529 USB LaunchPad Evaluation Kit](http://www.ti.com/tool/MSP-EXP430F5529LP) - + ### Tomu - [Fomu](https://www.crowdsupply.com/sutajio-kosagi/fomu) -- cgit v1.3.1 From 4e4aa26fb6155e409f8bea17515bc7b6ceb9b8cb Mon Sep 17 00:00:00 2001 From: hathach Date: Thu, 15 Oct 2020 11:57:30 +0700 Subject: add samd21 xplained pro to boards.md doc --- docs/boards.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/boards.md b/docs/boards.md index f49b247ac..59f6905ea 100644 --- a/docs/boards.md +++ b/docs/boards.md @@ -30,8 +30,9 @@ This code base already had supported for a handful of following boards (sorted a - [Adafruit Metro M4 Express](https://www.adafruit.com/product/3382) - [D5035-01](https://github.com/RudolphRiedel/USB_CAN-FD) - [Great Scott Gadgets LUNA](https://greatscottgadgets.com/luna/) -- [Microchip SAMD11 Xplained](https://www.microchip.com/developmenttools/ProductDetails/atsamd11-xpro) -- [Microchip SAMG55 Xplained Pro Evaluation Kit](https://www.microchip.com/DevelopmentTools/ProductDetails/PartNO/ATSAMG55-XPRO) +- [Microchip SAMD11 Xplained Pro](https://www.microchip.com/developmenttools/ProductDetails/atsamd11-xpro) +- [Microchip SAMD21 Xplained Pro](https://www.microchip.com/DevelopmentTools/ProductDetails/ATSAMD21-XPRO) +- [Microchip SAMG55 Xplained Pro](https://www.microchip.com/DevelopmentTools/ProductDetails/PartNO/ATSAMG55-XPRO) - [Seeeduino Xiao](https://www.seeedstudio.com/Seeeduino-XIAO-Arduino-Microcontroller-SAMD21-Cortex-M0+-p-4426.html) ### Nordic nRF5x -- cgit v1.3.1