Merge pull request #109 from adafruit/support-rp2040-mbed

Support rp2040 mbed

Author: hathach

README.md

@@ -2,31 +2,55 @@
 
 [![Build Status](https://github.com/adafruit/Adafruit_TinyUSB_Arduino/workflows/Build/badge.svg)](https://github.com/adafruit/Adafruit_TinyUSB_Arduino/actions) [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
 
-This library is a Arduino-friendly version of [TinyUSB](https://github.com/hathach/tinyusb) stack. It is designed with structure and APIs that are easily integrated to existing or new Arduino Core. Supported platform including: 
+This library is a Arduino-friendly version of [TinyUSB](https://github.com/hathach/tinyusb) stack.
+It is designed with structure and APIs that are easily integrated to an Arduino Core.
 
-- [Adafruit_nRF52_Arduino](https://github.com/adafruit/Adafruit_nRF52_Arduino)
-- [Adafruit/ArduinoCore-samd](https://github.com/adafruit/ArduinoCore-samd) selectable via menu`Tools->USB Stack->TinyUSB`
-- [earlephilhower/arduino-pico](https://github.com/earlephilhower/arduino-pico) selectable via menu `Tools->USB Stack->Adafruit TinyUSB`
+## Features
 
-Current class drivers supported are
+Currently only support device mode only, supported class drivers are:
 
 - Communication (CDC): which is used to implement `Serial` monitor
 - Human Interface Device (HID): Generic (In & Out), Keyboard, Mouse, Gamepad etc ...
 - Mass Storage Class (MSC): with multiple LUNs
 - Musical Instrument Digital Interface (MIDI)
 - WebUSB with vendor specific class
 
-For supported ArduinoCore, to use this library, you only need to have `<Adafruit_TinyUSB.h>` in your sketch. If your ArduinoCore does not support TinyUSB library yet, it is rather simple to port.
+## Supported Cores
+
+There are 2 type of supported cores: with and without built-in support for TinyUSB. Built-in support provide seamless integration but requires extra code added to core's source code. Unfortunately it is not always easy or possible to make those modification.
+
+### Cores with built-in support
+
+Following core has Tinyusb as either the primary usb stack or selectable via menu `Tools->USB Stack`. You only need to include `<Adafruit_TinyUSB.h>` in your sketch to use.
+
+- [Adafruit_nRF52_Arduino](https://github.com/adafruit/Adafruit_nRF52_Arduino)
+- [adafruit/ArduinoCore-samd](https://github.com/adafruit/ArduinoCore-samd)
+- [earlephilhower/arduino-pico](https://github.com/earlephilhower/arduino-pico)
+
+### Cores without built-in support
+
+Following is cores without built-in support
+
+- **mbed_rp2040**
+
+It is still possible to use TinyUSB but with some limits such as:
+
+- `TinyUSB_Device_Init()` need to be manually called in setup()
+- `TinyUSB_Device_Task()` and/or `TinyUSB_Device_FlushCDC()` may (or not) need to be manually called in loop()
+- Use `SerialTinyUSB` name instead of Serial for serial monitor
+- And there could be more other issues, using on these cores should be considered as experimental
 
 ## Class Driver API
 
 More document to write ... 
 
 ## Porting Guide
 
-It is rather easy if you want to integrate TinyUSB lib to your ArduinoCore.
+To integrate TinyUSB library to a Arduino core, you will need to make changes to the core for built-in support and library for porting the mcu/platform.
+
+### Arduino Core Changes
 
-### ArduinoCore Changes
+If possible, making changes to core will allow it to have built-in which make it almost transparent to user sketch 
 
 1. Add this repo as submodule (or have local copy) at your ArduioCore/libraries/Adafruit_TinyUSB_Arduino (much like SPI).
 2. Since Serial as CDC is considered as part of the core, we need to have `#include "Adafruit_USBD_CDC.h"` within your `Arduino.h`. For this to work, your `platform.txt` include path need to have `"-I{runtime.platform.path}/libraries/Adafruit_TinyUSB_Arduino/src/arduino"`.

examples/Composite/hid_generic_inout_ramdisk/hid_generic_inout_ramdisk.ino

@@ -68,9 +68,9 @@ void setup()
   usb_hid.begin();
 
   Serial.begin(115200);
-  Serial.println("Waiting for USBDevice mount");
+  Serial.println("Waiting for TinyUSBDevice mount");
   // wait until device mounted
-  while( !USBDevice.mounted() ) delay(1);
+  while( !TinyUSBDevice.mounted() ) delay(1);
 
   Serial.println("Adafruit TinyUSB HID Generic In Out example");
 }

examples/Composite/mouse_external_flash/mouse_external_flash.ino

@@ -114,7 +114,7 @@ void loop()
   uint32_t const btn = (digitalRead(pin) == activeState);
 
   // Remote wakeup
-  if ( USBDevice.suspended() && btn )
+  if ( TinyUSBDevice.suspended() && btn )
   {
     // Wake up host if we are in suspend mode
     // and REMOTE_WAKEUP feature is enabled by host

examples/Composite/mouse_ramdisk/mouse_ramdisk.ino

@@ -45,6 +45,11 @@ Adafruit_USBD_MSC usb_msc;
 // the setup function runs once when you press reset or power the board
 void setup()
 {
+#if defined(ARDUINO_ARCH_MBED) && defined(ARDUINO_ARCH_RP2040)
+  // Manual begin() is required on core without built-in support for TinyUSB such as mbed rp2040
+  TinyUSB_Device_Init(0);
+#endif
+
   // Set disk vendor id, product id and revision with string up to 8, 16, 4 characters respectively
   usb_msc.setID("Adafruit", "Mass Storage", "1.0");
 
@@ -66,7 +71,7 @@ void setup()
   usb_hid.begin();
 
   Serial.begin(115200);
-  while( !USBDevice.mounted() ) delay(1);   // wait for native usb
+  while( !TinyUSBDevice.mounted() ) delay(1);   // wait for native usb
 
   Serial.println("Adafruit TinyUSB Mouse + Mass Storage (ramdisk) example");
 }
@@ -80,7 +85,7 @@ void loop()
   uint32_t const btn = (digitalRead(pin) == activeState);
 
   // Remote wakeup
-  if ( USBDevice.suspended() && btn )
+  if ( TinyUSBDevice.suspended() && btn )
   {
     // Wake up host if we are in suspend mode
     // and REMOTE_WAKEUP feature is enabled by host

examples/HID/hid_composite/hid_composite.ino

@@ -66,7 +66,7 @@ void setup()
   Serial.println("Adafruit TinyUSB HID Composite example");
 
   // wait until device mounted
-  while( !USBDevice.mounted() ) delay(1);
+  while( !TinyUSBDevice.mounted() ) delay(1);
 }
 
 void loop()
@@ -78,11 +78,11 @@ void loop()
   bool btn_pressed = (digitalRead(pin) == activeState);
 
   // Remote wakeup
-  if ( USBDevice.suspended() && btn_pressed )
+  if ( TinyUSBDevice.suspended() && btn_pressed )
   {
     // Wake up host if we are in suspend mode
     // and REMOTE_WAKEUP feature is enabled by host
-    USBDevice.remoteWakeup();
+    TinyUSBDevice.remoteWakeup();
   }
 
   /*------------- Mouse -------------*/

examples/HID/hid_composite_joy_featherwing/hid_composite_joy_featherwing.ino

@@ -77,7 +77,7 @@ void setup()
   last_x = ss.analogRead(3);
 
   // wait until device mounted
-  while( !USBDevice.mounted() ) delay(1);
+  while( !TinyUSBDevice.mounted() ) delay(1);
 }
 
 void loop()
@@ -145,10 +145,10 @@ void loop()
 
   /*------------- Remote Wakeup -------------*/
   // Remote wakeup if PC is suspended and we has user interaction with joy feather wing
-  if ( has_action && USBDevice.suspended() )
+  if ( has_action && TinyUSBDevice.suspended() )
   {
     // Wake up only works if REMOTE_WAKEUP feature is enable by host
     // Usually this is the case with Mouse/Keyboard device
-    USBDevice.remoteWakeup();
+    TinyUSBDevice.remoteWakeup();
   }
 }

examples/HID/hid_gamepad/hid_gamepad.ino

@@ -36,6 +36,11 @@ hid_gamepad_report_t    gp;     // defined in hid.h from Adafruit_TinyUSB_Arduin
 
 void setup() 
 {
+#if defined(ARDUINO_ARCH_MBED) && defined(ARDUINO_ARCH_RP2040)
+  // Manual begin() is required on core without built-in support for TinyUSB such as mbed rp2040
+  TinyUSB_Device_Init(0);
+#endif
+
   Serial.begin(115200);
 
   usb_hid.setPollInterval(2);
@@ -44,19 +49,19 @@ void setup()
   usb_hid.begin();
 
   // wait until device mounted
-  while( !USBDevice.mounted() ) delay(1);
+  while( !TinyUSBDevice.mounted() ) delay(1);
 
   Serial.println("Adafruit TinyUSB HID Gamepad example");
 }
 
 void loop() 
 { 
 //  // Remote wakeup
-//  if ( USBDevice.suspended() && btn )
+//  if ( TinyUSBDevice.suspended() && btn )
 //  {
 //    // Wake up host if we are in suspend mode
 //    // and REMOTE_WAKEUP feature is enabled by host
-//    USBDevice.remoteWakeup();
+//    TinyUSBDevice.remoteWakeup();
 //  }
 
   if ( !usb_hid.ready() ) return;

examples/HID/hid_generic_inout/hid_generic_inout.ino

@@ -41,6 +41,11 @@ Adafruit_USBD_HID usb_hid;
 // the setup function runs once when you press reset or power the board
 void setup()
 {
+#if defined(ARDUINO_ARCH_MBED) && defined(ARDUINO_ARCH_RP2040)
+  // Manual begin() is required on core without built-in support for TinyUSB such as mbed rp2040
+  TinyUSB_Device_Init(0);
+#endif
+
   usb_hid.enableOutEndpoint(true);
   usb_hid.setPollInterval(2);
   usb_hid.setReportDescriptor(desc_hid_report, sizeof(desc_hid_report));
@@ -52,7 +57,7 @@ void setup()
   Serial.begin(115200);
 
   // wait until device mounted
-  while( !USBDevice.mounted() ) delay(1);
+  while( !TinyUSBDevice.mounted() ) delay(1);
 
   Serial.println("Adafruit TinyUSB HID Generic In Out example");
 }

examples/HID/hid_keyboard/hid_keyboard.ino

@@ -40,6 +40,11 @@ uint8_t pincount = sizeof(pins)/sizeof(pins[0]);
 // the setup function runs once when you press reset or power the board
 void setup()
 {
+#if defined(ARDUINO_ARCH_MBED) && defined(ARDUINO_ARCH_RP2040)
+  // Manual begin() is required on core without built-in support for TinyUSB such as mbed rp2040
+  TinyUSB_Device_Init(0);
+#endif
+
   usb_hid.setPollInterval(2);
   usb_hid.setReportDescriptor(desc_hid_report, sizeof(desc_hid_report));
   usb_hid.setReportCallback(NULL, hid_report_callback);
@@ -58,7 +63,7 @@ void setup()
   }
 
   // wait until device mounted
-  while( !USBDevice.mounted() ) delay(1);
+  while( !TinyUSBDevice.mounted() ) delay(1);
 }
 
 
@@ -68,11 +73,11 @@ void loop()
   delay(2);
 
 //  // Remote wakeup
-//  if ( USBDevice.suspended() && btn )
+//  if ( TinyUSBDevice.suspended() && btn )
 //  {
 //    // Wake up host if we are in suspend mode
 //    // and REMOTE_WAKEUP feature is enabled by host
-//    USBDevice.remoteWakeup();
+//    TinyUSBDevice.remoteWakeup();
 //  }
 
   if ( !usb_hid.ready() ) return;

examples/HID/hid_mouse/hid_mouse.ino

@@ -43,6 +43,11 @@ Adafruit_USBD_HID usb_hid;
 // the setup function runs once when you press reset or power the board
 void setup()
 {
+#if defined(ARDUINO_ARCH_MBED) && defined(ARDUINO_ARCH_RP2040)
+  // Manual begin() is required on core without built-in support for TinyUSB such as mbed rp2040
+  TinyUSB_Device_Init(0);
+#endif
+
   // Set up button, pullup opposite to active state
   pinMode(pin, activeState ? INPUT_PULLDOWN : INPUT_PULLUP);
 
@@ -55,7 +60,7 @@ void setup()
   Serial.begin(115200);
 
   // wait until device mounted
-  while( !USBDevice.mounted() ) delay(1);
+  while( !TinyUSBDevice.mounted() ) delay(1);
 
   Serial.println("Adafruit TinyUSB HID Mouse example");
 }
@@ -72,11 +77,11 @@ void loop()
   if (!btn_pressed) return;
 
   // Remote wakeup
-  if ( USBDevice.suspended() )
+  if ( TinyUSBDevice.suspended() )
   {
     // Wake up host if we are in suspend mode
     // and REMOTE_WAKEUP feature is enabled by host
-    USBDevice.remoteWakeup();
+    TinyUSBDevice.remoteWakeup();
   }
 
   if ( usb_hid.ready() )

examples/MIDI/midi_pizza_box_dj/midi_pizza_box_dj.ino

@@ -94,7 +94,7 @@ void setup() {
   for(uint8_t i=0; i<FRAMES; i++) lvl[i] = 256;
 
   // Wait until device is enumerated properly before sending MIDI message
-  while( !USBDevice.mounted() ) delay(1);
+  while( !TinyUSBDevice.mounted() ) delay(1);
 }
 
 ///////////////////////////////////////////////////////////////////////////////

examples/MIDI/midi_test/midi_test.ino

@@ -38,6 +38,11 @@ byte note_sequence[] = {
 
 void setup()
 {
+#if defined(ARDUINO_ARCH_MBED) && defined(ARDUINO_ARCH_RP2040)
+  // Manual begin() is required on core without built-in support for TinyUSB such as mbed rp2040
+  TinyUSB_Device_Init(0);
+#endif
+
   pinMode(LED_BUILTIN, OUTPUT);
 
   //usb_midi.setStringDescriptor("TinyUSB MIDI");
@@ -56,7 +61,7 @@ void setup()
   Serial.begin(115200);
 
   // wait until device mounted
-  while( !USBDevice.mounted() ) delay(1);
+  while( !TinyUSBDevice.mounted() ) delay(1);
 }
 
 void loop()
@@ -98,13 +103,25 @@ void loop()
 void handleNoteOn(byte channel, byte pitch, byte velocity)
 {
   // Log when a note is pressed.
-  Serial.printf("Note on: channel = %d, pitch = %d, velocity - %d", channel, pitch, velocity);
-  Serial.println();
+  Serial.print("Note on: channel = ");
+  Serial.print(channel);
+
+  Serial.print(" pitch = ");
+  Serial.print(pitch);
+
+  Serial.print(" velocity = ");
+  Serial.println(velocity);
 }
 
 void handleNoteOff(byte channel, byte pitch, byte velocity)
 {
   // Log when a note is released.
-  Serial.printf("Note off: channel = %d, pitch = %d, velocity - %d", channel, pitch, velocity);
-  Serial.println();
+  Serial.print("Note off: channel = ");
+  Serial.print(channel);
+
+  Serial.print(" pitch = ");
+  Serial.print(pitch);
+
+  Serial.print(" velocity = ");
+  Serial.println(velocity);
 }

examples/MassStorage/msc_ramdisk/msc_ramdisk.ino

@@ -21,9 +21,14 @@ Adafruit_USBD_MSC usb_msc;
 // the setup function runs once when you press reset or power the board
 void setup()
 {
+#if defined(ARDUINO_ARCH_MBED) && defined(ARDUINO_ARCH_RP2040)
+  // Manual begin() is required on core without built-in support for TinyUSB such as mbed rp2040
+  TinyUSB_Device_Init(0);
+#endif
+
   // Set disk vendor id, product id and revision with string up to 8, 16, 4 characters respectively
   usb_msc.setID("Adafruit", "Mass Storage", "1.0");
-  
+
   // Set disk size
   usb_msc.setCapacity(DISK_BLOCK_NUM, DISK_BLOCK_SIZE);
 
@@ -32,7 +37,7 @@ void setup()
 
   // Set Lun ready (RAM disk is always ready)
   usb_msc.setUnitReady(true);
-  
+
   usb_msc.begin();
 
   Serial.begin(115200);
@@ -47,8 +52,8 @@ void loop()
 }
 
 // Callback invoked when received READ10 command.
-// Copy disk's data to buffer (up to bufsize) and 
-// return number of copied bytes (must be multiple of block size) 
+// Copy disk's data to buffer (up to bufsize) and
+// return number of copied bytes (must be multiple of block size)
 int32_t msc_read_cb (uint32_t lba, void* buffer, uint32_t bufsize)
 {
   uint8_t const* addr = msc_disk[lba];
@@ -58,7 +63,7 @@ int32_t msc_read_cb (uint32_t lba, void* buffer, uint32_t bufsize)
 }
 
 // Callback invoked when received WRITE10 command.
-// Process data in buffer to disk's storage and 
+// Process data in buffer to disk's storage and
 // return number of written bytes (must be multiple of block size)
 int32_t msc_write_cb (uint32_t lba, uint8_t* buffer, uint32_t bufsize)
 {