Add USB drive mode to TinyUSB, SingleFileDisk (#1034)

SingleFileDisk allows for exporting a file from the onboard LittleFS
filesystem to a PC through an emulated FAT drive when connected.  The
PC can open and copy the file, as well as delete it, but the PC has no
access to the main onboard LittleFS and no actual on-flash FAT
structures are used.

This is handy for things like data loggers.  They can run connected to
USB power for some time, and then connected to a PC to dowmload the CSV
log recorded.

It's almost 2023, allow LFN (long file names) on the emulated USB disk.

Reduce the disk buffer size to 64 bytes.  The buffer is statically
allocated so it's always present, even in non-USB disk mode, meaning
all apps will pay the RAM price for it.  64 bytes is slower to read
but works and saves ~1/2KB of heap for all apps.

Author: earlephilhower

cores/rp2040/RP2040USB.cpp

@@ -68,9 +68,11 @@ static int __usb_task_irq;
 #define USBD_STR_SERIAL (0x03)
 #define USBD_STR_CDC (0x04)
 
-
 #define EPNUM_HID   0x83
 
+#define USBD_MSC_EPOUT 0x03
+#define USBD_MSC_EPIN 0x84
+#define USBD_MSC_EPSIZE 64
 
 const uint8_t *tud_descriptor_device_cb(void) {
     static tusb_desc_device_t usbd_desc_device = {
@@ -89,7 +91,7 @@ const uint8_t *tud_descriptor_device_cb(void) {
         .iSerialNumber = USBD_STR_SERIAL,
         .bNumConfigurations = 1
     };
-    if (__USBInstallSerial && !__USBInstallKeyboard && !__USBInstallMouse && !__USBInstallJoystick) {
+    if (__USBInstallSerial && !__USBInstallKeyboard && !__USBInstallMouse && !__USBInstallJoystick && !__USBInstallMassStorage) {
         // Can use as-is, this is the default USB case
         return (const uint8_t *)&usbd_desc_device;
     }
@@ -103,6 +105,9 @@ const uint8_t *tud_descriptor_device_cb(void) {
     if (__USBInstallJoystick) {
         usbd_desc_device.idProduct |= 0x0100;
     }
+    if (__USBInstallMassStorage) {
+        usbd_desc_device.idProduct ^= 0x2000;
+    }
     // Set the device class to 0 to indicate multiple device classes
     usbd_desc_device.bDeviceClass = 0;
     usbd_desc_device.bDeviceSubClass = 0;
@@ -223,7 +228,7 @@ void __SetupUSBDescriptor() {
     if (!usbd_desc_cfg) {
         bool hasHID = __USBInstallKeyboard || __USBInstallMouse || __USBInstallJoystick;
 
-        uint8_t interface_count = (__USBInstallSerial ? 2 : 0) + (hasHID ? 1 : 0);
+        uint8_t interface_count = (__USBInstallSerial ? 2 : 0) + (hasHID ? 1 : 0) + (__USBInstallMassStorage ? 1 : 0);
 
         uint8_t cdc_desc[TUD_CDC_DESC_LEN] = {
             // Interface number, string index, protocol, report descriptor len, EP In & Out address, size & polling interval
@@ -238,7 +243,12 @@ void __SetupUSBDescriptor() {
             TUD_HID_DESCRIPTOR(hid_itf, 0, HID_ITF_PROTOCOL_NONE, hid_report_len, EPNUM_HID, CFG_TUD_HID_EP_BUFSIZE, 10)
         };
 
-        int usbd_desc_len = TUD_CONFIG_DESC_LEN + (__USBInstallSerial ? sizeof(cdc_desc) : 0) + (hasHID ? sizeof(hid_desc) : 0);
+        uint8_t msd_itf = interface_count - 1;
+        uint8_t msd_desc[TUD_MSC_DESC_LEN] = {
+            TUD_MSC_DESCRIPTOR(msd_itf, 0, USBD_MSC_EPOUT, USBD_MSC_EPIN, USBD_MSC_EPSIZE)
+        };
+
+        int usbd_desc_len = TUD_CONFIG_DESC_LEN + (__USBInstallSerial ? sizeof(cdc_desc) : 0) + (hasHID ? sizeof(hid_desc) : 0) + (__USBInstallMassStorage ? sizeof(msd_desc) : 0);
 
         uint8_t tud_cfg_desc[TUD_CONFIG_DESC_LEN] = {
             // Config number, interface count, string index, total length, attribute, power in mA
@@ -260,6 +270,10 @@ void __SetupUSBDescriptor() {
                 memcpy(ptr, hid_desc, sizeof(hid_desc));
                 ptr += sizeof(hid_desc);
             }
+            if (__USBInstallMassStorage) {
+                memcpy(ptr, msd_desc, sizeof(msd_desc));
+                ptr += sizeof(msd_desc);
+            }
         }
     }
 }
@@ -367,4 +381,55 @@ extern "C" void tud_hid_set_report_cb(uint8_t instance, uint8_t report_id, hid_r
     (void) bufsize;
 }
 
+extern "C" int32_t tud_msc_read10_cb(uint8_t lun, uint32_t lba, uint32_t offset, void* buffer, uint32_t bufsize) __attribute__((weak));
+extern "C" int32_t tud_msc_read10_cb(uint8_t lun, uint32_t lba, uint32_t offset, void* buffer, uint32_t bufsize) {
+    (void) lun;
+    (void) lba;
+    (void) offset;
+    (void) buffer;
+    (void) bufsize;
+    return -1;
+}
+
+extern "C" bool tud_msc_test_unit_ready_cb(uint8_t lun) __attribute__((weak));
+extern "C" bool tud_msc_test_unit_ready_cb(uint8_t lun) {
+    (void) lun;
+    return false;
+}
+
+extern "C" int32_t tud_msc_write10_cb(uint8_t lun, uint32_t lba, uint32_t offset, uint8_t* buffer, uint32_t bufsize) __attribute__((weak));
+extern "C" int32_t tud_msc_write10_cb(uint8_t lun, uint32_t lba, uint32_t offset, uint8_t* buffer, uint32_t bufsize) {
+    (void) lun;
+    (void) lba;
+    (void) offset;
+    (void) buffer;
+    (void) bufsize;
+    return -1;
+}
+
+extern "C" int32_t tud_msc_scsi_cb(uint8_t lun, uint8_t const scsi_cmd[16], void* buffer, uint16_t bufsize) __attribute__((weak));
+extern "C" int32_t tud_msc_scsi_cb(uint8_t lun, uint8_t const scsi_cmd[16], void* buffer, uint16_t bufsize) {
+    (void) lun;
+    (void) scsi_cmd;
+    (void) buffer;
+    (void) bufsize;
+    return 0;
+}
+
+extern "C" void tud_msc_capacity_cb(uint8_t lun, uint32_t* block_count, uint16_t* block_size) __attribute__((weak));
+extern "C" void tud_msc_capacity_cb(uint8_t lun, uint32_t* block_count, uint16_t* block_size) {
+    (void) lun;
+    *block_count = 0;
+    *block_size = 0;
+}
+
+extern "C" void tud_msc_inquiry_cb(uint8_t lun, uint8_t vendor_id[8], uint8_t product_id[16], uint8_t product_rev[4]) __attribute__((weak));
+extern "C" void tud_msc_inquiry_cb(uint8_t lun, uint8_t vendor_id[8], uint8_t product_id[16], uint8_t product_rev[4]) {
+    (void) lun;
+    vendor_id[0] = 0;
+    product_id[0] = 0;
+    product_rev[0] = 0;
+}
+
+
 #endif

cores/rp2040/RP2040USB.h

@@ -26,6 +26,7 @@ extern void __USBInstallSerial() __attribute__((weak));
 extern void __USBInstallKeyboard() __attribute__((weak));
 extern void __USBInstallJoystick() __attribute__((weak));
 extern void __USBInstallMouse() __attribute__((weak));
+extern void __USBInstallMassStorage() __attribute__((weak));
 
 // Big, global USB mutex, shared with all USB devices to make sure we don't
 // have multiple cores updating the TUSB state in parallel

docs/index.rst

@@ -39,6 +39,8 @@ For the latest version, always check https://github.com/earlephilhower/arduino-p
    USB (Arduino and Adafruit_TinyUSB) <usb>
    Multicore Processing <multicore>
 
+   Single File USB Drive <singlefile>
+
    FreeRTOS SMP (multicore) <freertos>
 
    WiFi (Pico-W Support) <wifi>

docs/singlefile.rst

@@ -0,0 +1,82 @@
+SingleFileDrive
+===============
+
+USB drive mode is supported through the ``SingleFileDrive`` class which
+allows the Pico to emulate a FAT-formatted USB stick while preserving the
+onboard LittleFS filesystem.  A single file can be exported this way without
+needing to use FAT as the onboard filesystem (FAT is not appropriate for
+flash-based devices without complicated wear leveling because of the update
+frequency of the FAT tables).
+
+This emulation is very simple and only allows for the reading of the single
+file, and deleting it.
+
+Callbacks, Interrupt Safety, and File Operations
+------------------------------------------------
+
+The ``SingleFileDrive`` library allows your application to get a callback
+when a PC attempts to mount or unmount the Pico as a drive.  Your app can
+also get a callback if the user attempts to delete the file (but your
+sketch does not actually need to delete the file, it's up to you).
+
+Note that when the USB drive is mounted by a PC it is not safe for your
+main sketch to make changes to the LittleFS filesystem or the file being
+exported.  So, normally, your ``onPlug`` callback will set a flag letting
+your application know not to touch the filesystem, with the ``onUnplug``
+callback clearing this flag.
+
+Also, because the USB port can be connected at any time, it is important
+to disable interrupts using ``noInterrupts()`` before writing to a file
+you will be exporting (and restoring them with ``interrupts()`` afterwards).
+It is also important to ``close()`` the file after each update, or the
+on-flash version the ``SingleFileDrive`` will attempt to export may not be
+up to date causing issues later on.
+
+See the included ``DataLoggerUSB`` sketch for an example of working with
+these limitations.
+
+Using SingleFileDrive
+---------------------
+
+Implementing the drive requires including the header file, starting LittleFS,
+defining your callbacks, and telling the library what file to export.  No
+polling or other calls are required outside of your ``setup()``.  (Note that
+the callback routines allow for a parameter to be passed to them, but in most
+cases this can be safely ignored.)
+
+.. code:: cpp
+
+        #include <LittleFS.h>
+        #include <SingleFileDrive.h>
+
+        void myPlugCB(uint32_t data) {
+            // Tell my app not to write to flash, we're connected
+        }
+
+        void myUnplugCB(uint32_t data) {
+            // I can start writing to flash again
+        }
+
+        void myDeleteDB(uint32_t data) {
+            // Maybe LittleFS.remove("myfile.txt")?  or do nothing
+        }
+
+        void setup() {
+            LittleFS.begin();
+            singleFileDrive.onPlug(myPlugCB);
+            singleFileDrive.onUnplug(myUnplugCB);
+            singleFileDrive.onDelete(myDeleteCB);
+            singleFileDrive.begin("littlefsfile.csv", "Data Recorder.csv");
+            // ... rest of setup ...
+        }
+
+        void loop() {
+            // Take some measurements, delay, etc.
+            if (okay-to-write) {
+                noInterrupts();
+                File f = LittleFS.open("littlefsfile.csv", "a");
+                f.printf("%d,%d,%d\n", data1, data2, data3);
+                f.close();
+                interrupts();
+            }
+        }

include/tusb_config.h

@@ -72,15 +72,14 @@
 //------------- CLASS -------------//
 #define CFG_TUD_HID              (2)
 #define CFG_TUD_CDC              (1)
-#define CFG_TUD_MSC              (0)
+#define CFG_TUD_MSC              (1)
 #define CFG_TUD_MIDI             (0)
 #define CFG_TUD_VENDOR           (0)
 
 #define CFG_TUD_CDC_RX_BUFSIZE  (256)
 #define CFG_TUD_CDC_TX_BUFSIZE  (256)
 
-#define CFG_TUD_MIDI_RX_BUFSIZE (64)
-#define CFG_TUD_MIDI_TX_BUFSIZE (64)
+#define CFG_TUD_MSC_EP_BUFSIZE  (64)
 
 // HID buffer size Should be sufficient to hold ID (if any) + Data
 #define CFG_TUD_HID_EP_BUFSIZE  (64)

lib/libpico-ipv6.a

@@ -5,6 +5,6 @@ maintainer=Earle F. Philhower, III <[email protected]>
 sentence=Configures requests for OTA bootloader
 paragraph=Example repository for Ethernet drivers
 category=Device Control
-url=https://github.com/earlephilhower.arduino-pico
+url=https://github.com/earlephilhower/arduino-pico
 architectures=rp2040
 dot_a_linkage=true

lib/libpico.a

@@ -0,0 +1,92 @@
+// Simple logger with USB upload to PC
+// Uses SingleFileDrive to export an onboard LittleFS file to the computer
+// The PC can open/copy the file, and then the user can delete it to restart
+
+// Released to the public domain,  2022 - Earle F. Philhower, III
+
+#include <SingleFileDrive.h>
+#include <LittleFS.h>
+
+uint32_t cnt = 0;
+bool okayToWrite = true;
+
+// Make the CSV file and give it a simple header
+void headerCSV() {
+  File f = LittleFS.open("data.csv", "w");
+  f.printf("sample,millis,temp,rand\n");
+  f.close();
+  cnt = 0;
+}
+
+// Called when the USB stick connected to a PC and the drive opened
+// Note this is from a USB IRQ so no printing to SerialUSB/etc.
+void plug(uint32_t i) {
+  (void) i;
+  okayToWrite = false;
+}
+
+// Called when the USB is ejected or removed from a PC
+// Note this is from a USB IRQ so no printing to SerialUSB/etc.
+void unplug(uint32_t i) {
+  (void) i;
+  okayToWrite = true;
+}
+
+// Called when the PC tries to delete the single file
+// Note this is from a USB IRQ so no printing to SerialUSB/etc.
+void deleteCSV(uint32_t i) {
+  (void) i;
+  LittleFS.remove("data.csv");
+  headerCSV();
+}
+
+void setup() {
+  Serial.begin();
+  delay(5000);
+
+  LittleFS.begin();
+
+  // Set up the USB disk share
+  singleFileDrive.onDelete(deleteCSV);
+  singleFileDrive.onPlug(plug);
+  singleFileDrive.onUnplug(unplug);
+  singleFileDrive.begin("data.csv", "Recorded data from the Raspberry Pi Pico.csv");
+
+  // Find the last written data
+  File f = LittleFS.open("data.csv", "r");
+  if (!f || !f.size()) {
+    cnt = 1;
+    headerCSV();
+  } else {
+    if (f.size() > 2048) {
+      f.seek(f.size() - 1024);
+    }
+    do {
+      String s = f.readStringUntil('\n');
+      sscanf(s.c_str(), "%lu,", &cnt);
+    } while (f.available());
+    f.close();
+    cnt++;
+  }
+
+  Serial.printf("Starting acquisition at %d\n", cnt);
+}
+
+void loop() {
+  float temp = analogReadTemp();
+  uint32_t hwrand = rp2040.hwrand32();
+  // Make sure the USB connect doesn't happen while we're writing!
+  noInterrupts();
+  if (okayToWrite) {
+    Serial.printf("Sampling...%lu\n", cnt);
+    // Don't want the USB to connect during an update!
+    File f = LittleFS.open("data.csv", "a");
+    if (f) {
+      f.printf("%lu,%lu,%f,%lu\n", cnt++, millis(), temp, hwrand);
+      f.close();
+    }
+  }
+  interrupts();
+
+  delay(10000);
+}

libraries/PicoOTA/library.properties

@@ -0,0 +1,22 @@
+#######################################
+# Syntax Coloring Map
+#######################################
+
+#######################################
+# Datatypes (KEYWORD1)
+#######################################
+
+SingleFileDrive	KEYWORD1
+
+#######################################
+# Methods and Functions (KEYWORD2)
+#######################################
+
+singleFileDrive KEYWORD1
+onDelete	KEYWORD1
+onPlug  KEYWORD1
+onUnplug        KEYWORD1
+
+#######################################
+# Constants (LITERAL1)
+#######################################