esp32-s2_dfu/README.md

# TinyUSB

![tinyUSB_240x100](https://user-images.githubusercontent.com/249515/62646655-f9393200-b978-11e9-9c53-484862f15503.png)

[![Build Status](https://github.com/hathach/tinyusb/workflows/Build/badge.svg)](https://github.com/hathach/tinyusb/actions) [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)

TinyUSB is an open-source cross-platform USB Host/Device stack for embedded system, designed to be memory-safe with no dynamic allocation and thread-safe with all interrupt events are deferred then handled in the non-ISR task function.

![tinyusb](https://user-images.githubusercontent.com/249515/49858616-f60c9700-fe27-11e8-8627-e76936352ff7.png)

```
.
├── docs            # Documentation
├── examples        # Sample with Makefile and Segger Embedded build support
├── hw
│   ├── bsp         # Supported boards source files
│   └── mcu         # Low level mcu core & peripheral drivers
├── lib             # Sources from 3rd party such as freeRTOS, fatfs ...
├── src             # All sources files for TinyUSB stack itself.
├── test            # Unit tests for the stack
└── tools           # Files used internally
```

## Contributors

Special thanks to all the people who spent their precious time and effort to help this project so far. Check out the 
[CONTRIBUTORS.md](CONTRIBUTORS.md) file for the list of all contributors and their awesome work for the stack.

## Supported MCUs

The stack supports the following MCUs:

- **Espressif:** ESP32-S2
- **Dialog:** DA1469x
- **MicroChip:** SAMD11, SAMD21, SAMD51, SAME5x, SAMG55
- **NordicSemi:** nRF52833, nRF52840
- **Nuvoton:** NUC120, NUC121/NUC125, NUC126, NUC505
- **NXP:**
  - iMX RT Series: RT1011, RT1015, RT1021, RT1052, RT1062, RT1064
  - Kinetis: KL25
  - LPC Series: 11Uxx, 13xx, 175x_6x, 177x_8x, 18xx, 40xx, 43xx, 51Uxx, 54xxx, 55xx
- **Raspberry Pi:** RP2040
- **Sony:** CXD56
- **ST:** STM32 series: L0, F0, F1, F2, F3, F4, F7, H7 both FullSpeed and HighSpeed
- **TI:** MSP430
- **[ValentyUSB](https://github.com/im-tomu/valentyusb)** eptri

[Here is the list of supported Boards](docs/boards.md) that can be used with provided examples.

## Device Stack

Supports multiple device configurations by dynamically changing usb descriptors. Low power functions such like suspend, resume, and remote wakeup. Following device classes are supported:

- USB Audio Class 2.0 (UAC2) still work in progress
- Bluetooth Host Controller Interface (BTH HCI)
- Communication Class (CDC)
- Device Firmware Update (DFU): only Runtinme 
- Human Interface Device (HID): Generic (In & Out), Keyboard, Mouse, Gamepad etc ...
- Mass Storage Class (MSC): with multiple LUNs
- Musical Instrument Digital Interface (MIDI)
- Network with RNDIS, CDC-ECM (work in progress)
- USB Test and Measurement Class (USBTMC)
- Vendor-specific class support with generic In & Out endpoints. Can be used with MS OS 2.0 compatible descriptor to load winUSB driver without INF file.
- [WebUSB](https://github.com/WICG/webusb) with vendor-specific class

## Host Stack

**Most active development is on the Device stack. The Host stack is under rework and largely untested.**

- Human Interface Device (HID): Keyboard, Mouse, Generic
- Mass Storage Class (MSC)
- Hub currently only supports 1 level of hub (due to my laziness)

## OS Abstraction layer

TinyUSB is completely thread-safe by pushing all ISR events into a central queue, then process it later in the non-ISR context task function. It also uses semaphore/mutex to access shared resources such as CDC FIFO. Therefore the stack needs to use some of OS's basic APIs. Following OSes are already supported out of the box.

- **No OS** : Disabling USB IRQ is used as way to provide mutex
- **FreeRTOS**
- **Mynewt** Due to the newt package build system, Mynewt examples are better to be on its [own repo](https://github.com/hathach/mynewt-tinyusb-example) 

## Getting Started

[Here are the details for getting started](docs/getting_started.md) with the stack.

## Porting

Want to help add TinyUSB support for a new MCU? Read [here](docs/porting.md) for an explanation on the low-level API needed by TinyUSB.

## License

MIT license for all TinyUSB sources `src` folder, [Full license is here](LICENSE). However, each file is individually licensed especially those in `lib` and `hw/mcu` folder. Please make sure you understand all the license term for files you use in your project.

## Uses

TinyUSB is currently used by these other projects:

- [Adafruit nRF52 Arduino](https://github.com/adafruit/Adafruit_nRF52_Arduino)
- [Adafruit nRF52 Bootloader](https://github.com/adafruit/Adafruit_nRF52_Bootloader)
- [Adafruit SAMD Arduino](https://github.com/adafruit/ArduinoCore-samd)
- [CircuitPython](https://github.com/adafruit/circuitpython)
- [Espressif IDF](https://github.com/espressif/esp-idf)
- [MicroPython](https://github.com/micropython/micropython)
- [mynewt](https://mynewt.apache.org)
- [Raspberry pico-sdk](https://github.com/raspberrypi/pico-sdk)
- [TinyUF2 Bootloader](https://github.com/adafruit/tinyuf2)
- [TinyUSB Arduino Library](https://github.com/adafruit/Adafruit_TinyUSB_Arduino)
clean up files 2018-12-13 09:20:28 +01:00			`# TinyUSB`
Initial commit 2012-11-26 07:24:01 +01:00
add logo 2019-08-07 20:09:04 +02:00			`![tinyUSB_240x100](https://user-images.githubusercontent.com/249515/62646655-f9393200-b978-11e9-9c53-484862f15503.png)`

enable cdc auto flush on write() if there is enough data in the fifo 2020-11-02 10:50:46 +01:00			`[![Build Status](https://github.com/hathach/tinyusb/workflows/Build/badge.svg)](https://github.com/hathach/tinyusb/actions) [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)`
update readme 2018-12-29 08:29:59 +01:00
adding debug log function 2019-10-23 16:18:46 +02:00			`TinyUSB is an open-source cross-platform USB Host/Device stack for embedded system, designed to be memory-safe with no dynamic allocation and thread-safe with all interrupt events are deferred then handled in the non-ISR task function.`
update md 2014-03-28 11:50:30 +01:00
docs update 2018-12-12 10:35:53 +01:00			`![tinyusb](https://user-images.githubusercontent.com/249515/49858616-f60c9700-fe27-11e8-8627-e76936352ff7.png)`
update md 2014-03-28 11:50:30 +01:00
update readme 2018-12-29 08:29:59 +01:00			```
			`.`
more readme 2018-12-29 08:39:28 +01:00			`├── docs # Documentation`
			`├── examples # Sample with Makefile and Segger Embedded build support`
update readme 2018-12-29 08:29:59 +01:00			`├── hw`
more readme 2018-12-29 08:39:28 +01:00			`│ ├── bsp # Supported boards source files`
			`│ └── mcu # Low level mcu core & peripheral drivers`
			`├── lib # Sources from 3rd party such as freeRTOS, fatfs ...`
			`├── src # All sources files for TinyUSB stack itself.`
docs clean up 2019-06-10 12:50:16 +02:00			`├── test # Unit tests for the stack`
more readme 2018-12-29 08:39:28 +01:00			`└── tools # Files used internally`
update readme 2018-12-29 08:29:59 +01:00			```

add the most important file of the project: CONTRIBUTORS.md 2019-11-25 07:29:42 +01:00			`## Contributors`

Fix some style issues in the README 2020-01-10 00:34:12 +01:00			`Special thanks to all the people who spent their precious time and effort to help this project so far. Check out the`
update readme 2019-11-25 07:33:50 +01:00			`[CONTRIBUTORS.md](CONTRIBUTORS.md) file for the list of all contributors and their awesome work for the stack.`
add the most important file of the project: CONTRIBUTORS.md 2019-11-25 07:29:42 +01:00
doc update 2019-09-20 11:14:35 +02:00			`## Supported MCUs`

Fix some style issues in the README 2020-01-10 00:34:12 +01:00			`The stack supports the following MCUs:`
doc update 2019-09-20 11:14:35 +02:00
update docs for esp32s2 2020-04-07 18:01:26 +02:00			`- Espressif: ESP32-S2`
added DA14695 DK USB bsp 2020-07-01 07:47:14 +02:00			`- Dialog: DA1469x`
release 0.7.0 with changelog and doc update 2020-11-07 17:43:39 +01:00			`- MicroChip: SAMD11, SAMD21, SAMD51, SAME5x, SAMG55`
added TODO item for changelog - rewrite changelog it better later on - simplify the issue template 2020-04-19 09:02:39 +02:00			`- NordicSemi: nRF52833, nRF52840`
follow up to pr #301 rename OPT_MCU_NUC505_USB_DMA to simply USE_DMA 2020-03-17 04:40:45 +01:00			`- Nuvoton: NUC120, NUC121/NUC125, NUC126, NUC505`
update readme, contributor and doc for new port KL25 update nxp_driver 2020-12-25 17:10:57 +01:00			`- NXP:`
update doc, RT1011 verified to work, thanks to @arturo182 2019-11-23 15:59:28 +01:00			`- iMX RT Series: RT1011, RT1015, RT1021, RT1052, RT1062, RT1064`
update readme, contributor and doc for new port KL25 update nxp_driver 2020-12-25 17:10:57 +01:00			`- Kinetis: KL25`
			`- LPC Series: 11Uxx, 13xx, 175x_6x, 177x_8x, 18xx, 40xx, 43xx, 51Uxx, 54xxx, 55xx`
doc update 2021-01-22 19:12:56 +01:00			`- Raspberry Pi: RP2040`
Update README.md 2019-10-08 10:49:37 +02:00			`- Sony: CXD56`
correct HSE_VALUE in hal_conf - although it is define in CFLAGS, it is worth to correct to be consistent with other build - extract set_speed() 2020-07-02 09:57:00 +02:00			`- ST: STM32 series: L0, F0, F1, F2, F3, F4, F7, H7 both FullSpeed and HighSpeed`
update doc for MSP430 2020-03-24 06:12:38 +01:00			`- TI: MSP430`
add the most important file of the project: CONTRIBUTORS.md 2019-11-25 07:29:42 +01:00			`- [ValentyUSB](https://github.com/im-tomu/valentyusb) eptri`
doc update 2019-09-20 11:14:35 +02:00
			`[Here is the list of supported Boards](docs/boards.md) that can be used with provided examples.`

docs update 2018-12-12 10:35:53 +01:00			`## Device Stack`
adding some document to /readme.md 2013-05-07 08:36:34 +02:00
Fix some style issues in the README 2020-01-10 00:34:12 +01:00			`Supports multiple device configurations by dynamically changing usb descriptors. Low power functions such like suspend, resume, and remote wakeup. Following device classes are supported:`
clean up 2019-04-02 11:18:36 +02:00
release 0.7.0 with changelog and doc update 2020-11-07 17:43:39 +01:00			`- USB Audio Class 2.0 (UAC2) still work in progress`
			`- Bluetooth Host Controller Interface (BTH HCI)`
Add a porting doc and make a pass over the others. Fixes #5 2018-11-28 03:07:22 +01:00			`- Communication Class (CDC)`
release 0.7.0 with changelog and doc update 2020-11-07 17:43:39 +01:00			`- Device Firmware Update (DFU): only Runtinme`
support hid generic inout #58 - add report descriptor template TUD_HID_REPORT_DESC_GENERIC_INOUT - add TUD_HID_INOUT_DESCRIPTOR & TUD_HID_INOUT_DESC_LEN - add hid_generic_inout example 2019-05-02 09:30:49 +02:00			`- Human Interface Device (HID): Generic (In & Out), Keyboard, Mouse, Gamepad etc ...`
add msc multiple lun support - remove CFG_TUD_MSC_MAXLUN - add tud_msc_maxlun_cb() - add msc_dual_lun exmaple 2019-04-26 10:54:42 +02:00			`- Mass Storage Class (MSC): with multiple LUNs`
update nrfx to 1.6.2 2019-03-19 13:09:08 +01:00			`- Musical Instrument Digital Interface (MIDI)`
added TODO item for changelog - rewrite changelog it better later on - simplify the issue template 2020-04-19 09:02:39 +02:00			`- Network with RNDIS, CDC-ECM (work in progress)`
added changelog 2020-03-30 06:30:37 +02:00			`- USB Test and Measurement Class (USBTMC)`
add vendor & webusb support to doc 2019-08-01 08:31:59 +02:00			`- Vendor-specific class support with generic In & Out endpoints. Can be used with MS OS 2.0 compatible descriptor to load winUSB driver without INF file.`
			`- [WebUSB](https://github.com/WICG/webusb) with vendor-specific class`
adding some document to /readme.md 2013-05-07 08:36:34 +02:00
docs update 2018-12-12 10:35:53 +01:00			`## Host Stack`
Add a porting doc and make a pass over the others. Fixes #5 2018-11-28 03:07:22 +01:00
docs clean up 2018-12-12 10:57:10 +01:00			`Most active development is on the Device stack. The Host stack is under rework and largely untested.`
adding some document to /readme.md 2013-05-07 08:36:34 +02:00
docs update 2018-12-12 10:35:53 +01:00			`- Human Interface Device (HID): Keyboard, Mouse, Generic`
update project file 2014-03-25 10:42:34 +01:00			`- Mass Storage Class (MSC)`
Fix some style issues in the README 2020-01-10 00:34:12 +01:00			`- Hub currently only supports 1 level of hub (due to my laziness)`
adding some document to /readme.md 2013-05-07 08:36:34 +02:00
Fix some style issues in the README 2020-01-10 00:34:12 +01:00			`## OS Abstraction layer`
adding some document to /readme.md 2013-05-07 08:36:34 +02:00
Fix some style issues in the README 2020-01-10 00:34:12 +01:00			`TinyUSB is completely thread-safe by pushing all ISR events into a central queue, then process it later in the non-ISR context task function. It also uses semaphore/mutex to access shared resources such as CDC FIFO. Therefore the stack needs to use some of OS's basic APIs. Following OSes are already supported out of the box.`
adding some document to /readme.md 2013-05-07 08:36:34 +02:00
doc update 2019-09-20 11:14:35 +02:00			`- No OS : Disabling USB IRQ is used as way to provide mutex`
documenting on the way 2013-05-08 07:23:25 +02:00			`- FreeRTOS`
doc update 2019-08-01 11:22:19 +02:00			`- Mynewt Due to the newt package build system, Mynewt examples are better to be on its [own repo](https://github.com/hathach/mynewt-tinyusb-example)`
doc work, comment out \subpage command in markdown result 2014-04-17 07:02:03 +02:00
docs update 2018-12-12 10:35:53 +01:00			`## Getting Started`
documenting with markdown 2014-03-26 09:42:34 +01:00
Fix some style issues in the README 2020-01-10 00:34:12 +01:00			`[Here are the details for getting started](docs/getting_started.md) with the stack.`
adding some document to /readme.md 2013-05-07 08:36:34 +02:00
update readme 2019-04-08 08:22:08 +02:00			`## Porting`

			`Want to help add TinyUSB support for a new MCU? Read [here](docs/porting.md) for an explanation on the low-level API needed by TinyUSB.`

			`## License`

Fix some style issues in the README 2020-01-10 00:34:12 +01:00			MIT license for all TinyUSB sources `src` folder, [Full license is here](LICENSE). However, each file is individually licensed especially those in `lib` and `hw/mcu` folder. Please make sure you understand all the license term for files you use in your project.
update readme 2019-04-08 08:22:08 +02:00
docs update 2018-12-12 10:35:53 +01:00			`## Uses`
Add a porting doc and make a pass over the others. Fixes #5 2018-11-28 03:07:22 +01:00
			`TinyUSB is currently used by these other projects:`

Update README.md 2020-07-01 08:19:06 +02:00			`- [Adafruit nRF52 Arduino](https://github.com/adafruit/Adafruit_nRF52_Arduino)`
			`- [Adafruit nRF52 Bootloader](https://github.com/adafruit/Adafruit_nRF52_Bootloader)`
			`- [Adafruit SAMD Arduino](https://github.com/adafruit/ArduinoCore-samd)`
			`- [CircuitPython](https://github.com/adafruit/circuitpython)`
doc update 2021-01-22 19:12:56 +01:00			`- [Espressif IDF](https://github.com/espressif/esp-idf)`
Update README.md 2020-07-01 08:19:06 +02:00			`- [MicroPython](https://github.com/micropython/micropython)`
			`- [mynewt](https://mynewt.apache.org)`
doc update 2021-01-22 19:12:56 +01:00			`- [Raspberry pico-sdk](https://github.com/raspberrypi/pico-sdk)`
			`- [TinyUF2 Bootloader](https://github.com/adafruit/tinyuf2)`
Update README.md 2020-07-01 08:19:06 +02:00			`- [TinyUSB Arduino Library](https://github.com/adafruit/Adafruit_TinyUSB_Arduino)`