doc: add project README

README.md

@@ -0,0 +1,77 @@
+This is a [USB DFU](https://www.usb.org/document-library/device-firmware-upgrade-11-new-version-31-aug-2004) (DFU mode) implementation for [ESP32-S2](https://www.espressif.com/en/products/socs/esp32-s2) based on [tinyUSB](https://docs.tinyusb.org/en/latest/index.html).
+It allows flashing the firmware using [dfu-util](http://dfu-util.sourceforge.net/).
+
+design choice
+=============
+
+ESP-IDF
+-------
+
+The [ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/get-started/index.html) uses [tinyUSB](https://github.com/espressif/tinyusb), but only offers [few profiles](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/usb_device.html) (e.g. CDC, MSC).
+They are defined in 'esp-idf/components/tinyusb/additions', and re-use the tinyUSB device implementations.
+But there is no DFU implementation (runtime or DFU mode).
+
+TinyUSB
+-------
+
+[TinyUSB](https://github.com/hathach/tinyusb) is a generic USB stack for micro-controllers.
+It [supports](https://docs.tinyusb.org/en/latest/reference/supported.html) ESP32-S2.
+DFU is [implemented](https://github.com/hathach/tinyusb/tree/master/src/class/dfu) and there is an [example](https://github.com/hathach/tinyusb/tree/master/examples/device/dfu).
+This example can't be used for ESP32-S2 though.
+I've added freeRTOS to it so it can be used on the ESP32-S2.
+
+bootloader
+----------
+
+The ESP-IDF allows you to have a [custom](https://github.com/espressif/esp-idf/tree/master/examples/custom_bootloader) [bootloader](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-guides/bootloader.html) (2nd stage), but I was not able to add freeRTOS to it, required by the tinyUSB implementation.
+
+factory
+-------
+
+This USB DFU implementation is flashed as a factory application image.
+It will then flash the main firmware image into the [OTA0 partition](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/system/ota.html).
+Thus it requires a custom [partition table](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-guides/partition-tables.html), with a "small" factory partition, just one OTA application partition, and one OTA data partition.
+The factory partition should be 200 KB.
+This is super large for just a "bootloader" to flash firmware images, but since ESP32 often use large external flash memory, this is not too much of an issue.
+Feel free to reuse the 'partitions.csv' file as example.
+
+alternatives
+============
+
+ESP-ROM
+-------
+
+The ESP-S2 comes with a ROM bootloader that already allows you to flash over USB using the serial CDC ACM profile.
+But this method does not let you restart into the main firmware.
+The ROM bootloader USB stack even offers DFU capability, and you can flash using dfu-util.
+But this one also does not let you restart into the main firmware.
+
+To flash using USB serial (can't restart the device):
+
+~~~
+idf.py -p /dev/ttyACM0 flash
+...
+WARNING: ESP32-S2 chip was placed into download mode using GPIO0.
+esptool.py can not exit the download mode over USB. To run the app, reset the chip manually.
+To suppress this note, set --after option to 'no_reset'.
+~~~
+
+And to [flash using DFU](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-guides/dfu.html):
+
+~~~
+# generate the DFU binary (not the same as the usual flash binary)
+idf.py dfu
+dfu-util --device 303a:0002 --download build/dfu.bin
+# or
+idf.py dfu-flash
+~~~
+
+Note: after detaching, the bootloader claims for be in runtime mode, but this is still the bootloader, and not the flashed firmware.
+
+TinyUF2
+-------
+
+[TinyUF2](https://github.com/adafruit/tinyuf2) is a UF2 bootloader by Adafruit.
+It is based on TinyUSB, and supports ESP32-S2.
+It uses the DFU name (Device Firmware Upgrade), but it's not the DFU specified by USB.
+Instead it provides a MSC interface where you can copy the firmware binary file to.