Major functionality update

Added support for F4 and G4 boards.
Serial aliased to SerialTinyUSB.
USB initialisation, task polling, CDC flushing, and DFU bootloader entry added.
added .txt file with board info to paste to boards.txt

Author: code-fiasco

README.md

@@ -1,29 +1,61 @@
 # TinyUSB for STM32 (Arduino)
 
-This port adds STM32F4 support to the [Adafruit TinyUSB Arduino Library](https://github.com/adafruit/Adafruit_TinyUSB_Arduino), enabling advanced USB device functionality (MIDI, HID, MSC, etc.) on STM32 microcontrollers.
+> **Note:** An earlier version of this port is integrated into the official Adafruit TinyUSB library. I will submit the updated version once it is ready and hopefully get the changes made in the stm32 core files so that manual editing of boards.txt is not required.
+
+This port adds STM32F1, STM32F4, and STM32G4 support to the [Adafruit TinyUSB Arduino Library](https://github.com/adafruit/Adafruit_TinyUSB_Arduino), enabling advanced USB device functionality (MIDI, HID, MSC, CDC, etc.) on STM32 microcontrollers.
+
+## What's New
+
+Whilst this port should still be considered experimental, it is now a lot more fleshed out than previous versions:
+
+```cpp
+// Previously required in setup():
+if (!TinyUSBDevice.isInitialized()) { TinyUSBDevice.begin(0); }
+if (TinyUSBDevice.mounted()) { TinyUSBDevice.detach(); delay(10); TinyUSBDevice.attach(); }
+
+// Previously required in loop():
+#ifdef TINYUSB_NEED_POLLING_TASK
+TinyUSBDevice.task();
+#endif
+```
+
+This version eliminates all of that. USB initialisation, task polling, CDC flushing, and DFU bootloader entry are all handled automatically — sketches work the same way as on officially supported cores like RP2040 and SAMD. `Serial` is now also automatically aliased to `SerialTinyUSB`, so no `#define` is needed in your sketch, `Serial` commands work like they should. And most importantly no need to press the BOOT and RESET buttons when uploading anymore!
+
+Support has been added and tested for three STM32 families: **F1**, **F4**, and **G4**.
 
 ## Compatibility
 
 ### Tested and Working
-- STM32F411 BlackPill (WeAct Studio)
+| Board | MCU | Family |
+|---|---|---|
+| WeAct STM32F411 BlackPill | STM32F411 | F4 |
+| STM32F103 BluePill | STM32F103 | F1 |
+| WeAct STM32G431 | STM32G431 | G4 |
 
-### Should Work (but untested)
-- Other STM32F4 series (F401, F405, F407, F446, etc.) - uses same USB peripheral
-- STM32F7 series - similar OTG_FS peripheral
+### Should Work (untested)
+- **STM32F4 series:** F401, F405, F407, F446 and other F4xx variants — same OTG_FS peripheral
+- **STM32F1 series:** Other F103 variants — same USB peripheral
+- **STM32G4 series:** G474, G491, G4A1 — same USB peripheral
 
-### Won't Work Without Modification
-- STM32F0, F1, F3 series - different USB peripheral architecture
-- STM32L series - may need different configuration
-- STM32H7 - may need clock configuration changes
+### Not Supported (yet)
+- STM32F0, F2, F3 — different USB peripheral architecture
+- STM32L, STM32H7 — would need clock configuration changes
 
 **If you test on other boards, please report your results!**
 
 ## Features
 - ✅ USB MIDI
 - ✅ USB CDC (Virtual Serial Port)
-- ✅ USB HID (Keyboard/Mouse/Gamepad)
+- ✅ USB HID (Keyboard / Mouse / Gamepad)
 - ✅ USB MSC (Mass Storage)
 - ✅ Multiple USB classes simultaneously
+- ✅ No sketch boilerplate — USB initialises and polls automatically
+- ✅ `Serial` works without any `#define` in your sketch
+- ✅ Arduino IDE "touch 1200" DFU bootloader entry
+
+## How It Works
+
+The port implements the three hooks required by the STM32 Arduino core to integrate TinyUSB as a first-class citizen. `initVariant()` is called automatically before `setup()` and handles all USB hardware and stack initialisation. `HAL_IncTick()` is overridden to signal every 1ms SysTick tick, which `yield()` and `serialEventRun()` use to service the TinyUSB task in thread context — ensuring USB events are processed reliably regardless of what the sketch is doing. `TinyUSB_Port_EnterDFU()` handles the Arduino IDE's "touch 1200" auto-reset by disconnecting from USB cleanly, writing the STM32duino bootloader magic value to a backup register, and issuing a system reset.
 
 ## Prerequisites
 1. [Arduino IDE](https://www.arduino.cc/en/software)
@@ -42,9 +74,8 @@ libraries/Adafruit_TinyUSB_Library/src/arduino/ports/
 ```
 
 ### Step 3: Edit tusb_config.h
-Open `libraries/Adafruit_TinyUSB_Library/src/tusb_config.h`
+Open `Arduino/libraries/Adafruit_TinyUSB_Library/src/tusb_config.h` and find the platform detection block (around line 30–40):
 
-Find the platform detection section (around line 30-40). You'll see a series of `#elif` statements like this:
 ```cpp
 #if defined(ARDUINO_ARCH_SAMD)
   #include "arduino/ports/samd/tusb_config_samd.h"
@@ -61,121 +92,107 @@ Find the platform detection section (around line 30-40). You'll see a series of
 #endif
 ```
 
-**Add the following lines BEFORE the `#else` statement** (not after the `#endif`!):
-```cpp
-#elif defined(ARDUINO_ARCH_STM32) || defined(ARDUINO_ARCH_ARDUINO_CORE_STM32)
-  #include "arduino/ports/stm32/tusb_config_stm32.h"
-```
+Add the following lines **before** the `#else`:
 
-Your final code should look like this:
 ```cpp
-#if defined(ARDUINO_ARCH_SAMD)
-  #include "arduino/ports/samd/tusb_config_samd.h"
-#elif defined(ARDUINO_NRF52_ADAFRUIT)
-  #include "arduino/ports/nrf/tusb_config_nrf.h"
-#elif defined(ARDUINO_ARCH_RP2040)
-  #include "arduino/ports/rp2040/tusb_config_rp2040.h"
-#elif defined(ARDUINO_ARCH_ESP32)
-  // do nothing since we force include "arduino/ports/esp32/tusb_config_esp32.h" in tusb_option.h
-#elif defined(ARDUINO_ARCH_CH32) || defined(CH32V20x) || defined(CH32V30x)
-  #include "arduino/ports/ch32/tusb_config_ch32.h"
 #elif defined(ARDUINO_ARCH_STM32) || defined(ARDUINO_ARCH_ARDUINO_CORE_STM32)
   #include "arduino/ports/stm32/tusb_config_stm32.h"
-#else
-  #error TinyUSB Arduino Library does not support your core yet
-#endif
 ```
 
-
 ### Step 4: Edit boards.txt
-Open your STM32 core's `boards.txt` file, typically located at:
+Open your STM32 core's `boards.txt`, typically at:
 ```
 Arduino15/packages/STMicroelectronics/hardware/stm32/[version]/boards.txt
 ```
 
-Add these lines to your board configuration (example shown for Generic F4):
+Find your board's section and add a TinyUSB USB menu entry. The board identifier prefix (e.g. `GenF4`, `GenF1`, `GenG4`) must match the one already used in that board's section. I have included the lines you need to add in `boards_txt_additions.txt` for ease of use. Examples for each family:
+
+**STM32F4 (e.g. Generic F4):**
+```
+GenF4.menu.usb.TinyUSB=Adafruit TinyUSB
+GenF4.menu.usb.TinyUSB.build.usb_flags={build.extra_flags} -DARDUINO_ARCH_TINYUSB
+```
+
+**STM32F1 (e.g. Generic F1):**
 ```
-GenF4.menu.usb.TinyUSBMIDI=Adafruit TinyUSB
-GenF4.menu.usb.TinyUSBMIDI.build.usb_flags={build.extra_flags} -DARDUINO_ARCH_TINYUSB
+GenF1.menu.usb.TinyUSB=Adafruit TinyUSB
+GenF1.menu.usb.TinyUSB.build.usb_flags={build.extra_flags} -DARDUINO_ARCH_TINYUSB
 ```
 
-**Note:** Adjust `GenF4` to match your specific board identifier if different.
+**STM32G4 (e.g. Generic G4):**
+```
+GenG4.menu.usb.TinyUSB=Adafruit TinyUSB
+GenG4.menu.usb.TinyUSB.build.usb_flags={build.extra_flags} -DARDUINO_ARCH_TINYUSB
+```
 
 ### Step 5: Restart Arduino IDE
 Close and reopen Arduino IDE for changes to take effect.
 
 ### Step 6: Select TinyUSB
-In Arduino IDE, go to **Tools > USB** and select **"Adafruit TinyUSB"**
+In Arduino IDE, go to **Tools > USB** and select **"Adafruit TinyUSB"**.
+
+## Usage
 
-## Usage Example
+Sketches require no USB initialisation boilerplate. `Serial` works normally. Here is a minimal CDC echo example — the entire sketch is just application code:
 
-Here's a simple USB MIDI example:
 ```cpp
-#define Serial SerialTinyUSB  //Alias to allow Serial Communication throguh TinyUSB
 #include <Adafruit_TinyUSB.h>
-#include <MIDI.h>
-
-Adafruit_USBD_MIDI usb_midi;
-MIDI_CREATE_INSTANCE(Adafruit_USBD_MIDI, usb_midi, MIDI);
 
 void setup() {
-  if (!TinyUSBDevice.isInitialized()) {
-    TinyUSBDevice.begin(0);
-  }
-  
-  usb_midi.setStringDescriptor("My STM32 MIDI Device");
-  MIDI.begin(MIDI_CHANNEL_OMNI);
+  Serial.begin(115200);
+  // optional delay
+  while (!TinyUSBDevice.mounted()) delay(1);
+  Serial.println("Hello from STM32!");
 }
 
 void loop() {
-  MIDI.read();
-  
-  // Send a MIDI note every second
-  static uint32_t last_note = 0;
-  if (millis() - last_note > 1000) {
-    MIDI.sendNoteOn(60, 127, 1);
-    delay(100);
-    MIDI.sendNoteOff(60, 0, 1);
-    last_note = millis();
+  if (Serial.available()) {
+    Serial.write(Serial.read());
   }
 }
 ```
 
-## Technical Details
+> **Note:** `while (!TinyUSBDevice.mounted()) delay(1)` is entirely optional but useful if your sketch needs to send data immediately on startup. It works correctly because `tud_task()` is serviced inside `delay()`.
 
-### Key Implementation Notes
-- **VBUS Sensing:** Disabled to allow proper enumeration on bus-powered devices
-- **USB Peripheral:** Uses STM32F4's OTG_FS controller
-- **IRQ Handler:** Forwards USB interrupts to TinyUSB stack
-- **Clock Configuration:** Assumes STM32duino core provides correct 48MHz USB clock
+## File Descriptions
 
-### File Descriptions
-- **Adafruit_TinyUSB_stm32.cpp** - Platform-specific USB initialization and IRQ handling
-- **tusb_config_stm32.h** - TinyUSB configuration for STM32F4
+- **`Adafruit_TinyUSB_stm32.cpp`** — Hardware initialisation, IRQ handlers, automatic task polling, and DFU bootloader entry for F1, F4, and G4 families
+- **`tusb_config_stm32.h`** — TinyUSB configuration and class enable flags for STM32
 
 ## Known Limitations
-- Only tested on STM32F411 (other F4 variants should work but are untested)
-- Requires the official STM32duino core (other cores may not work)
-- DFU bootloader entry not yet implemented
+- Only the F1, F4, and G4 families are currently supported — see compatibility table above
+- Requires the official STM32duino core — other STM32 cores are untested
+- DFU bootloader entry requires that your board's upload method in Arduino board settings is configured to use STM32CubeProgrammer in DFU mode
 
 ## Troubleshooting
 
-**Device not enumerating:**
-- Verify you selected "Adafruit TinyUSB" from Tools > USB menu
-- Check that USB D+ (PA12) and D- (PA11) pins are not being used for other purposes
-- Try a different USB cable (some cables are charge-only)
+**Device not enumerating / "USB device malfunctioned":**
+- Verify you selected "Adafruit TinyUSB" from Tools > USB
+- Check that USB D+ and D- pins on your board are not used for other purposes
+- Try a different USB cable (or plugging directly into the PC if you are using a hub)
+- On G4 boards, ensure no other USB stack (e.g. the STM32duino built-in CDC) is also enabled
 
 **Compilation errors:**
-- Make sure you installed the Adafruit TinyUSB library via Library Manager
-- Restart Arduino IDE after making the modifications
-- Verify file paths are correct
+- Confirm the Adafruit TinyUSB library is installed via Library Manager
+- Make sure USB support in board setting is set to `Adafruit TinyUSB`
+- Restart Arduino IDE after making changes to `tusb_config.h` or `boards.txt`
+- Verify the `stm32` folder is in the correct location under `ports/`
+
+**"Touch 1200" / DFU upload not working:**
+- Confirm your board's upload method is set to STM32CubeProgrammer (DFU)
+- Check that the correct DFU drivers are installed on your system (use [Zadig](https://zadig.akeo.ie/) on Windows if needed)
 
 ## Contributing
-Issues and pull requests welcome! If you test this on other STM32F4 boards, please report your results.
+Issues and pull requests welcome! If you test this on other STM32 boards or families, please report your results.
 
-## Credits
-- Based on the [Adafruit TinyUSB Arduino Library](https://github.com/adafruit/Adafruit_TinyUSB_Arduino)
-- Port structure inspired by existing CH32, SAMD, and RP2040 implementations
+## Hardware Support Requests
+
+Want support for a board or STM32 family not listed here? I'm happy to add it, but I can't afford to buy every STM32 dev board out there. If you send me the board (or cover the cost of it), I'll add support and test it properly.
+
+Get in touch via Ko-fi — use the Commissions feature to describe what you need: 
+**[ko-fi.com/yourname](https://ko-fi.com/yourname)**
 
-## License
-MIT License (same as TinyUSB and Adafruit TinyUSB Library)
+> ☕ General donations to keep the project going are also very welcome!
+
+## Credits
+Based on the [Adafruit TinyUSB Arduino Library](https://github.com/adafruit/Adafruit_TinyUSB_Arduino).