You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/reference/getting_started.rst
+50-24Lines changed: 50 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,12 +5,12 @@ Getting Started
5
5
Add TinyUSB to your project
6
6
---------------------------
7
7
8
-
It is relatively simple to incorporate tinyusb to your project
8
+
To incorporate tinyusb to your project
9
9
10
10
* Copy or ``git submodule`` this repo into your project in a subfolder. Let's say it is ``your_project/tinyusb``
11
11
* Add all the ``.c`` in the ``tinyusb/src`` folder to your project
12
12
* Add ``your_project/tinyusb/src`` to your include path. Also make sure your current include path also contains the configuration file ``tusb_config.h``.
13
-
* 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 ``CFG_TUSB_MCU``, ``CFG_TUSB_OS`` since they are passed by IDE/compiler to maintain a unique configure for all boards).
13
+
* 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 ``CFG_TUSB_MCU``, ``CFG_TUSB_OS`` since they are passed by make/cmake to maintain a unique configure for all boards).
14
14
* If you use the device stack, make sure you have created/modified usb descriptors for your own need. Ultimately you need to implement all **tud descriptor** callbacks for the stack to work.
15
15
* Add ``tusb_init(rhport, role)`` call to your reset initialization code.
16
16
* Call ``tusb_int_handler(rhport, in_isr)`` in your USB IRQ Handler
@@ -75,24 +75,36 @@ The hardware code is located in ``hw/bsp`` folder, and is organized by family/bo
75
75
.. code-block:: bash
76
76
77
77
$ cd examples/device/cdc_msc
78
-
$ make BOARD=raspberry_pi_pico get-deps
78
+
$ make BOARD=feather_nrf52840_express get-deps
79
79
80
80
You only need to do this once per family. Check out `complete list of dependencies and their designated path here <dependencies.rst>`_
81
81
82
-
Build
83
-
^^^^^
82
+
Build Examples
83
+
^^^^^^^^^^^^^^
84
84
85
-
To build example, first change directory to an example folder.
85
+
Examples support make and cmake build system for most MCUs, however some MCU families such as espressif or rp2040 only support cmake. First change directory to an example folder.
86
86
87
87
.. code-block:: bash
88
88
89
89
$ cd examples/device/cdc_msc
90
90
91
-
Then compile with ``make BOARD={board_name} all`` , for example
91
+
Then compile with make or cmake
92
+
93
+
.. code-block:: bash
94
+
95
+
$ # make
96
+
$ make BOARD=feather_nrf52840_express all
97
+
98
+
$ # cmake
99
+
$ mkdir build &&cd build
100
+
$ cmake -DBOARD=raspberry_pi_pico ..
101
+
$ make
102
+
103
+
To list all available targets with cmake
92
104
93
105
.. code-block:: bash
94
106
95
-
$ make BOARD=raspberry_pi_pico all
107
+
$ cmake --build . --target help
96
108
97
109
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
98
110
@@ -104,20 +116,24 @@ Note: some examples especially those that uses Vendor class (e.g webUSB) may req
104
116
RootHub Port Selection
105
117
~~~~~~~~~~~~~~~~~~~~~~
106
118
107
-
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:
119
+
If a board has several ports, one port is chosen by default in the individual board.mk file. Use option ``RHPORT_DEVICE=x`` or ``RHPORT_HOST=x`` To choose another port. For example to select the HS port of a STM32F746Disco board, use:
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
130
+
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
117
131
118
132
.. code-block:: bash
119
133
120
-
$ make BOARD=stm32f746disco SPEED=full all
134
+
$ make BOARD=stm32f746disco RHPORT_DEVICE_SPEED=OPT_MODE_FULL_SPEED all
$ make SERIAL=/dev/ttyACM0 BOARD=feather_nrf52840_express flash
181
204
182
-
Since jlink can be used with most of the boards, there is also ``flash-jlink`` target for your convenience.
205
+
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.
183
206
184
207
.. code-block:: bash
185
208
186
209
$ make BOARD=feather_nrf52840_express flash-jlink
210
+
$ make BOARD=feather_nrf52840_express flash-openocd
211
+
212
+
$ cmake --build . --target cdc_msc-jlink
213
+
$ cmake --build . --target cdc_msc-openocd
187
214
188
215
Some board use uf2 bootloader for drag & drop in to mass storage device, uf2 can be generated with ``uf2`` target
189
216
190
217
.. code-block:: bash
191
218
192
219
$ make BOARD=feather_nrf52840_express all uf2
193
220
221
+
$ cmake --build . --target cdc_msc-uf2
222
+
194
223
IAR Support
195
-
-----------
224
+
^^^^^^^^^^^
196
225
197
226
Use project connection
198
-
^^^^^^^^^^^^^^^^^^^^^^
227
+
~~~~~~~~~~~~~~~~~~~~~~
199
228
200
229
IAR Project Connection files are provided to import TinyUSB stack into your project.
201
230
202
231
* A buildable project of your MCU need to be created in advance.
203
232
204
-
205
233
* Take example of STM32F0:
206
234
207
235
- You need ``stm32l0xx.h``, ``startup_stm32f0xx.s``, ``system_stm32f0xx.c``.
@@ -212,15 +240,13 @@ IAR Project Connection files are provided to import TinyUSB stack into your proj
212
240
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,
1. (Python3 is needed) Run ``iar_gen.py`` to generate .ipcf files of examples:
249
+
1. Run ``iar_gen.py`` to generate .ipcf files of examples:
224
250
225
251
.. code-block::
226
252
@@ -230,8 +256,8 @@ Run examples
230
256
2. Open ``Project -> Add project Connection ...``, click ``OK``, choose ``tinyusb\\examples\\(.ipcf of example)``.
231
257
For example ``C:\\tinyusb\\examples\\device\\cdc_msc\\iar_cdc_msc.ipcf``
232
258
233
-
Native CMake support (9.50.1+)
234
-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
259
+
Native CMake support
260
+
~~~~~~~~~~~~~~~~~~~~
235
261
236
262
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.
0 commit comments