diff options
Diffstat (limited to 'docs/reference/getting_started.rst')
| -rw-r--r-- | docs/reference/getting_started.rst | 73 |
1 files changed, 48 insertions, 25 deletions
diff --git a/docs/reference/getting_started.rst b/docs/reference/getting_started.rst index e328757ba..3db3fa206 100644 --- a/docs/reference/getting_started.rst +++ b/docs/reference/getting_started.rst @@ -5,8 +5,7 @@ Getting Started Add TinyUSB to your project --------------------------- -It is relatively simple to incorporate tinyusb to your (existing) project - +It is relatively simple to incorporate tinyusb to your project * Copy or ``git submodule`` this repo into your project in a subfolder. Let's say it is *your_project/tinyusb* * Add all the .c in the ``tinyusb/src`` folder to your project @@ -44,43 +43,52 @@ For your convenience, TinyUSB contains a handful of examples for both host and d $ git clone https://github.com/hathach/tinyusb tinyusb $ cd tinyusb -Some TinyUSB examples also requires external submodule libraries in ``/lib`` such as FreeRTOS, Lightweight IP to build. Run following command to fetch them +Some ports will also require a port-specific SDK (e.g. RP2040) or binary (e.g. Sony Spresense) to build examples. They are out of scope for tinyusb, you should download/install it first according to its manufacturer guide. + +Dependencies +^^^^^^^^^^^^ + +The hardware code is located in ``hw/bsp`` folder, and is organized by family/boards. e.g raspberry_pi_pico is located in ``hw/bsp/rp2040/boards/raspberry_pi_pico`` where FAMILY=rp2040 and BOARD=raspberry_pi_pico. Before building, we firstly need to download dependencies such as: MCU low-level peripheral driver and external libraries e.g FreeRTOS (required by some examples). We can do that by either ways: + +1. Run ``tools/get_deps.py {FAMILY}`` script to download all dependencies for a family as follow. Note: For TinyUSB developer to download all dependencies, use FAMILY=all. .. code-block:: - $ git submodule update --init lib + $ python tools/get_deps.py rp2040 + +2. Or run the ``get-deps`` target in one of the example folder as follow. + +.. code-block:: + + $ cd examples/device/cdc_msc + $ make BOARD=raspberry_pi_pico get-deps -Some ports will also require a port-specific SDK (e.g. RP2040) or binary (e.g. Sony Spresense) to build examples. They are out of scope for tinyusb, you should download/install it first according to its manufacturer guide. +You only need to do this once per family. Check out `complete list of dependencies and their designated path here <dependencies.rst>`_ Build ^^^^^ -To build example, first change directory to an example folder. +To build example, first change directory to an example folder. .. code-block:: $ cd examples/device/cdc_msc -Before building, we need to download MCU driver submodule to provide low-level MCU peripheral's driver first. Run the ``get-deps`` target in one of the example folder as follow. You only need to do this once per mcu +Then compile with ``make BOARD={board_name} all`` , for example .. code-block:: - $ make BOARD=feather_nrf52840_express get-deps + $ make BOARD=raspberry_pi_pico all - -Some modules (e.g. RP2040 and ESP32s2) require the project makefiles to be customized using CMake. If necessary apply any setup steps for the platform's SDK. - -Then compile with ``make BOARD=[board_name] all``\ , for example +Note: some examples especially those that uses Vendor class (e.g webUSB) may requires udev permission on Linux (and/or macOS) to access usb device. It depends on your OS distro, typically copy ``99-tinyusb.rules`` and reload your udev is good to go .. code-block:: - $ make BOARD=feather_nrf52840_express all - -Note: ``BOARD`` can be found as directory name in ``hw/bsp``\ , either in its family/boards or directly under bsp (no family). -Note: some examples especially those that uses Vendor class (e.g webUSB) may requires udev permission on Linux (and/or macOS) to access usb device. It depends on your OS distro, typically copy ``/examples/device/99-tinyusb.rules`` file to /etc/udev/rules.d/ then run ``sudo udevadm control --reload-rules && sudo udevadm trigger`` is good enough. + $ cp examples/device/99-tinyusb.rules /etc/udev/rules.d/ + $ sudo udevadm control --reload-rules && sudo udevadm trigger -Port Selection -~~~~~~~~~~~~~~ +RootHub 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: @@ -118,7 +126,7 @@ To compile for debugging add ``DEBUG=1``\ , for example 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. +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. .. code-block:: @@ -127,7 +135,7 @@ Should you have an issue running example and/or submitting an bug report. You co 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: +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/>`_ @@ -170,7 +178,10 @@ Some board use uf2 bootloader for drag & drop in to mass storage device, uf2 can $ make BOARD=feather_nrf52840_express all uf2 IAR Support -^^^^^^^^^^^ +----------- + +Use project connection +^^^^^^^^^^^^^^^^^^^^^^ IAR Project Connection files are provided to import TinyUSB stack into your project. @@ -178,24 +189,24 @@ IAR Project Connection files are provided to import TinyUSB stack into your proj * Take example of STM32F0: - + - You need `stm32l0xx.h`, `startup_stm32f0xx.s`, `system_stm32f0xx.c`. - `STM32L0xx_HAL_Driver` is only needed to run examples, TinyUSB stack itself doesn't rely on MCU's SDKs. -* Open `Tools -> Configure Custom Argument Variables` (Switch to `Global` tab if you want to do it for all your projects) +* Open ``Tools -> Configure Custom Argument Variables`` (Switch to `Global` tab if you want to do it for all your projects) Click `New Group ...`, name it to `TUSB`, Click `Add Variable ...`, name it to `TUSB_DIR`, change it's value to the path of your TinyUSB stack, for example `C:\\tinyusb` Import stack only ~~~~~~~~~~~~~~~~~ -1. Open `Project -> Add project Connection ...`, click `OK`, choose `tinyusb\\tools\\iar_template.ipcf`. +1. Open ``Project -> Add project Connection ...``, click `OK`, choose `tinyusb\\tools\\iar_template.ipcf`. Run examples ~~~~~~~~~~~~ -1. (Python3 is needed) Run `iar_gen.py` to generate .ipcf files of examples: +1. (Python3 is needed) Run ``iar_gen.py`` to generate .ipcf files of examples: .. code-block:: @@ -204,3 +215,15 @@ Run examples 2. Open `Project -> Add project Connection ...`, click `OK`, choose `tinyusb\\examples\\(.ipcf of example)`. For example `C:\\tinyusb\\examples\\device\\cdc_msc\\iar_cdc_msc.ipcf` + +Native CMake support (9.50.1+) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +With 9.50.1 release, IAR added experimental native CMake support (strangely not mentioned in public release note). Now it's possible to import CMakeLists.txt then build and debug as a normal project. + +Following these steps: + +1. Add IAR compiler binary path to system ``PATH`` environment variable, such as ``C:\Program Files\IAR Systems\Embedded Workbench 9.2\arm\bin``. +2. Create new project in IAR, in Tool chain dropdown menu, choose CMake for Arm then Import ``CMakeLists.txt`` from chosen example directory. +3. Set up board option in ``Option - CMake/CMSIS-TOOLBOX - CMake``, for example :code:`-DBOARD=stm32f439nucleo -DTOOLCHAIN=iar`, **Uncheck 'Override tools in env'**. +4. (For debug only) Choose correct CPU model in ``Option - General Options - Target``, to profit register and memory view. |