diff options
Diffstat (limited to 'docs/tutorials/getting_started.rst')
| -rw-r--r-- | docs/tutorials/getting_started.rst | 176 |
1 files changed, 118 insertions, 58 deletions
diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started.rst index 432b0b682..35a9aa9bf 100644 --- a/docs/tutorials/getting_started.rst +++ b/docs/tutorials/getting_started.rst @@ -2,22 +2,22 @@ Getting Started *************** -This tutorial will guide you through setting up TinyUSB for your first project. We'll cover the basic integration steps and build your first example. +This tutorial will guide you through setting up TinyUSB for your first project. We'll cover the basic integration steps and build your first example application. Add TinyUSB to your project --------------------------- To incorporate TinyUSB into your project: -* Copy or ``git submodule`` this repository into your project in a subfolder. Let's say it is ``your_project/tinyusb`` +* Copy this repository or add it as a git submodule to a subfolder in your project. For example, place it at ``your_project/tinyusb`` * Add all the ``.c`` files in the ``tinyusb/src`` folder to your project -* Add ``your_project/tinyusb/src`` to your include path. Also make sure your current include path contains the configuration file ``tusb_config.h``. -* Make sure all required macros are defined properly in ``tusb_config.h`` (the configuration file in demo applications is sufficient, but you need to add a few more such as ``CFG_TUSB_MCU``, ``CFG_TUSB_OS`` since they are passed by make/cmake to maintain a unique configuration for all boards). -* If you use the device stack, make sure you have created/modified USB descriptors for your own needs. Ultimately you need to implement all **tud descriptor** callbacks for the stack to work. +* Add ``your_project/tinyusb/src`` to your include path. Also ensure that your include path contains the configuration file ``tusb_config.h``. +* Ensure all required macros are properly defined in ``tusb_config.h``. The configuration file from the demo applications provides a good starting point, but you'll need to add additional macros such as ``CFG_TUSB_MCU`` and ``CFG_TUSB_OS``. These are typically passed by make/cmake to maintain unique configurations for different boards. +* If you're using the device stack, ensure you have created or modified USB descriptors to meet your specific requirements. Ultimately you need to implement all **tud descriptor** callbacks for the stack to work. * Add a ``tusb_init(rhport, role)`` call to your reset initialization code. -* Call ``tusb_int_handler(rhport, in_isr)`` in your USB IRQ handler +* Call ``tusb_int_handler(rhport, in_isr)`` from your USB IRQ handler * Implement all enabled classes' callbacks. -* If you don't use any RTOS at all, you need to continuously and/or periodically call the ``tud_task()``/``tuh_task()`` functions. All of the callbacks and functionality are handled and invoked within the call of that task runner. +* If you're not using an RTOS, you must call the ``tud_task()``/``tuh_task()`` functions continuously or periodically. These task functions handle all callbacks and core functionality. .. note:: TinyUSB uses consistent naming prefixes: ``tud_`` for device stack functions and ``tuh_`` for host stack functions. See the :doc:`../reference/glossary` for more details. @@ -62,14 +62,16 @@ 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 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 them first according to the manufacturer's guide. +Some ports require additional port-specific SDKs (e.g., for RP2040) or binaries (e.g., for Sony Spresense) to build examples. These components are outside the scope of TinyUSB, so you should download and install them first according to the manufacturer's documentation. Dependencies ^^^^^^^^^^^^ -The hardware code is located in the ``hw/bsp`` folder, and is organized by family/boards. For example, raspberry_pi_pico is located in ``hw/bsp/rp2040/boards/raspberry_pi_pico`` where ``FAMILY=rp2040`` and ``BOARD=raspberry_pi_pico``. Before building, we first need to download dependencies such as: MCU low-level peripheral drivers and external libraries like FreeRTOS (required by some examples). We can do this in either of two ways: +TinyUSB separates example applications from board-specific hardware configurations. Example applications live in ``examples/device``, ``examples/host``, and ``examples/dual`` directories, while Board Support Package (BSP) configurations are stored in ``hw/bsp/FAMILY/boards/BOARD_NAME``. The BSP provides hardware abstraction including pin mappings, clock settings, linker scripts, and hardware initialization routines. For example, raspberry_pi_pico is located in ``hw/bsp/rp2040/boards/raspberry_pi_pico`` where ``FAMILY=rp2040`` and ``BOARD=raspberry_pi_pico``. When you build an example with ``BOARD=raspberry_pi_pico``, the build system automatically finds and uses the corresponding BSP. -1. Run the ``tools/get_deps.py {FAMILY}`` script to download all dependencies for a family as follows. Note: For TinyUSB developers to download all dependencies, use FAMILY=all. +Before building, you must first download dependencies including MCU low-level peripheral drivers and external libraries such as FreeRTOS (required by some examples). You can do this in either of two ways: + +1. Run the ``tools/get_deps.py {FAMILY}`` script to download all dependencies for a specific MCU family. To download dependencies for all families, use ``FAMILY=all``. .. code-block:: bash @@ -87,7 +89,7 @@ You only need to do this once per family. Check out :doc:`complete list of depen Build Examples ^^^^^^^^^^^^^^ -Examples support make and cmake build systems for most MCUs, however some MCU families such as Espressif or RP2040 only support cmake. First change directory to an example folder. +Examples support both Make and CMake build systems for most MCUs. However, some MCU families (such as Espressif and RP2040) only support CMake. First change directory to an example folder. .. code-block:: bash @@ -111,7 +113,7 @@ To list all available targets with cmake $ cmake --build . --target help -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 +Note: Some examples, especially those that use Vendor class (e.g., webUSB), may require udev permissions on Linux (and/or macOS) to access USB devices. It depends on your OS distribution, but typically copying ``99-tinyusb.rules`` and reloading udev is sufficient .. code-block:: bash @@ -132,7 +134,7 @@ If a board has several ports, one port is chosen by default in the individual bo 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 ``RHPORT_DEVICE_SPEED=OPT_MODE_FULL/HIGH_SPEED/`` or ``RHPORT_HOST_SPEED=OPT_MODE_FULL/HIGH_SPEED/`` e.g To force F723 operate at full instead of default high speed +An MCU can support multiple operational speeds. By default, the example build system uses the fastest speed supported by the board. Use the option ``RHPORT_DEVICE_SPEED=OPT_MODE_FULL_SPEED/OPT_MODE_HIGH_SPEED`` or ``RHPORT_HOST_SPEED=OPT_MODE_FULL_SPEED/OPT_MODE_HIGH_SPEED``. For example, to force the F723 to operate at full speed instead of the default high speed: .. code-block:: bash @@ -149,8 +151,36 @@ First install `linkermap tool <https://github.com/hathach/linkermap>`_ then ``li $ make BOARD=feather_nrf52840_express NO_LTO=1 all linkermap -Debug -^^^^^ +Flashing the Device +^^^^^^^^^^^^^^^^^^^ + +The ``flash`` target uses the default on-board debugger (jlink/cmsisdap/stlink/dfu) to flash the binary. Please install the supporting software in advance. Some boards use bootloader/DFU via serial, which requires passing the serial port to the make command + +.. code-block:: bash + + $ make BOARD=feather_nrf52840_express flash + $ make SERIAL=/dev/ttyACM0 BOARD=feather_nrf52840_express flash + +Since jlink/openocd can be used with most of the boards, there is also ``flash-jlink/openocd`` (make) and ``EXAMPLE-jlink/openocd`` target for your convenience. Note for stm32 board with stlink, you can use ``flash-stlink`` target as well. + +.. code-block:: bash + + $ make BOARD=feather_nrf52840_express flash-jlink + $ make BOARD=feather_nrf52840_express flash-openocd + + $ cmake --build . --target cdc_msc-jlink + $ cmake --build . --target cdc_msc-openocd + +Some boards use UF2 bootloader for drag-and-drop into a mass storage device. UF2 files can be generated with the ``uf2`` target + +.. code-block:: bash + + $ make BOARD=feather_nrf52840_express all uf2 + + $ cmake --build . --target cdc_msc-uf2 + +Debugging +^^^^^^^^^ To compile for debugging add ``DEBUG=1``\ , for example @@ -160,10 +190,10 @@ To compile for debugging add ``DEBUG=1``\ , for example $ cmake -DBOARD=feather_nrf52840_express -DCMAKE_BUILD_TYPE=Debug .. -Log -~~~ +Enable Logging +~~~~~~~~~~~~~~ -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. +If you encounter issues running examples or need to submit a bug report, you can enable TinyUSB's built-in debug logging with the optional ``LOG=`` parameter. ``LOG=1`` prints only error messages, while ``LOG=2`` prints more detailed information about ongoing events. ``LOG=3`` or higher is not used yet. .. code-block:: bash @@ -171,10 +201,10 @@ Should you have an issue running example and/or submitting an bug report. You co $ cmake -DBOARD=feather_nrf52840_express -DLOG=2 .. -Logger -~~~~~~ +Logging Performance Impact +~~~~~~~~~~~~~~~~~~~~~~~~~~ -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 messages are printed via the on-board UART, which is slow and consumes significant CPU time compared to USB speeds. If your board supports an on-board or 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/>`_ @@ -183,9 +213,9 @@ By default log message is printed via on-board UART which is slow and take lots * 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. +* ``LOGGER=swo``\ : Use dedicated SWO pin of ARM Cortex SWD debug header. - * Cons: only work with ARM Cortex MCUs minus M0 + * Cons: Only works with ARM Cortex MCUs except M0 * Pros: should be compatible with more debugger that support SWO. * Software viewer should be provided along with your debugger driver. @@ -197,49 +227,23 @@ By default log message is printed via on-board UART which is slow and take lots $ cmake -DBOARD=feather_nrf52840_express -DLOG=2 -DLOGGER=rtt .. $ cmake -DBOARD=feather_nrf52840_express -DLOG=2 -DLOGGER=swo .. -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 - -.. code-block:: bash - - $ make BOARD=feather_nrf52840_express flash - $ make SERIAL=/dev/ttyACM0 BOARD=feather_nrf52840_express flash - -Since jlink/openocd can be used with most of the boards, there is also ``flash-jlink/openocd`` (make) and ``EXAMPLE-jlink/openocd`` target for your convenience. Note for stm32 board with stlink, you can use ``flash-stlink`` target as well. - -.. code-block:: bash - - $ make BOARD=feather_nrf52840_express flash-jlink - $ make BOARD=feather_nrf52840_express flash-openocd - - $ cmake --build . --target cdc_msc-jlink - $ cmake --build . --target cdc_msc-openocd - -Some board use uf2 bootloader for drag & drop in to mass storage device, uf2 can be generated with ``uf2`` target - -.. code-block:: bash - - $ make BOARD=feather_nrf52840_express all uf2 - - $ cmake --build . --target cdc_msc-uf2 - IAR Support ^^^^^^^^^^^ +IAR Embedded Workbench is a commercial IDE and toolchain for embedded development. TinyUSB provides integration support for IAR through project connection files and native CMake support. + Use project connection ~~~~~~~~~~~~~~~~~~~~~~ IAR Project Connection files are provided to import TinyUSB stack into your project. -* A buildable project of your MCU need to be created in advance. +* A buildable project for your MCU needs to be created in advance. * Take example of STM32F0: - - You need ``stm32l0xx.h``, ``startup_stm32f0xx.s``, ``system_stm32f0xx.c``. + - You need ``stm32f0xx.h``, ``startup_stm32f0xx.s``, and ``system_stm32f0xx.c``. - - ``STM32L0xx_HAL_Driver`` is only needed to run examples, TinyUSB stack itself doesn't rely on MCU's SDKs. + - ``STM32F0xx_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) 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, @@ -279,7 +283,7 @@ Common Issues and Solutions **Build Errors** * **"arm-none-eabi-gcc: command not found"**: Install ARM GCC toolchain: ``sudo apt-get install gcc-arm-none-eabi`` -* **"Board 'X' not found"**: Check available boards in ``hw/bsp/FAMILY/boards/`` or run ``python tools/build.py -l`` +* **"Board 'X' not found"**: Check the available boards in ``hw/bsp/FAMILY/boards/`` or run ``python tools/build.py -l`` * **Missing dependencies**: Run ``python tools/get_deps.py FAMILY`` where FAMILY matches your board **Runtime Issues** @@ -288,9 +292,65 @@ Common Issues and Solutions * **Enumeration failure**: Enable logging with ``LOG=2`` and check for USB protocol errors * **Hard faults/crashes**: Verify interrupt handler setup and stack size allocation +Quick Start Examples +-------------------- + +Now that you have TinyUSB set up, you can try these examples to see it in action. + +Simple Device Example +^^^^^^^^^^^^^^^^^^^^^ + +The ``cdc_msc`` example creates a USB device with both a virtual serial port (CDC) and mass storage (MSC). This is the most commonly used example and demonstrates core device functionality. + +**What it does:** +* Appears as a serial port that echoes back any text you send +* Appears as a small USB drive with a README.TXT file +* Blinks an LED to show activity + +**Build and run:** + +.. code-block:: bash + + $ cd examples/device/cdc_msc + $ make BOARD=stm32f407disco all + $ make BOARD=stm32f407disco flash + +**Key files:** +* ``src/main.c`` - Main application with ``tud_task()`` loop +* ``src/usb_descriptors.c`` - USB device descriptors +* ``src/msc_disk.c`` - Mass storage implementation + +**Expected behavior:** Connect to your computer and you'll see both a new serial port and a small USB drive appear. + +Simple Host Example +^^^^^^^^^^^^^^^^^^^ + +The ``cdc_msc_hid`` example creates a USB host that can connect to USB devices with CDC, MSC, or HID interfaces. + +**What it does:** +* Detects and enumerates connected USB devices +* Communicates with CDC devices (like USB-to-serial adapters) +* Reads from MSC devices (like USB drives) +* Receives input from HID devices (like keyboards and mice) + +**Build and run:** + +.. code-block:: bash + + $ cd examples/host/cdc_msc_hid + $ make BOARD=stm32f407disco all + $ make BOARD=stm32f407disco flash + +**Key files:** +* ``src/main.c`` - Main application with ``tuh_task()`` loop +* ``src/cdc_app.c`` - CDC host functionality +* ``src/msc_app.c`` - Mass storage host functionality +* ``src/hid_app.c`` - HID host functionality + +**Expected behavior:** Connect USB devices to see enumeration messages and device-specific interactions in the serial output. + Next Steps ----------- +^^^^^^^^^^ -* Try the :doc:`first_device` tutorial to implement a simple USB device -* Read about :doc:`../guides/integration` for production projects * Check :doc:`../reference/boards` for board-specific information +* Explore more :doc:`../examples` for advanced use cases |