This is a follow-up article of my earlier project presented in “FatFS, MinIni, Shell and FreeRTOS for the NXP K22FN512“. I wanted to extend it with a USB MSD (memory stick) device: The USB storage device gets automatically mounted, and depending on a configuration (.ini) file on the memory device I can perform various actions, for example automatically copy data from the SD card to the USB device. For example the system logs data, and to get the data I insert the memory stick, it copies the data on it and automatically unmounts it, and I can remove the memory stick.

Outline

In this article I’m using the same FRDM-K22F (NXP K22FN512) as in the previous article. The use case is that the system logs some data using FatFS as file system, and I want to have an easy way to get data copied to a host (PC) system with minimal user intervention. Think about a device in the field and the service person needs to collect data from the devices. The approach is to use a USB MSD (memory stick) device which can be plugged into the USB port and to which the data will be transferred. To make it flexible and configurable, I’m using an .ini file (see “FatFS, MinIni, Shell and FreeRTOS for the NXP K22FN512“) on the memory stick which can be used to configure the actions.

For logging data I’m using the data logger I have used in “McuLog: Logging Framework for small Embedded Microcontroller Systems“.

The full source code is available on GitHub (see the links at the end of the article). It uses the Eclipse based NXP MCUXpresso IDE with the SDK and the GNU tools.

FRDM-K22F Board USB Host Mode

To use the FRDM-K22F board in USB host mode, the Jumper J22 needs to be installed. Additionally an adapter from Micro-B to Standard-A is needed for plugging in normal thumb drives:

USB MSD Host Stack

The project uses a modified USB MSD host device stack from the NXP MCUXpresso SDK:

• McuLib\FatFS\source\fsl_usb_disk: directory with the FatFS implementation for the MSD (USB disk)
• usb\host: Directory with the generic USB host stack
• source\host_msd_fatfs.c/.h: Application level callbacks of the MSD stack. Includes a command line (shell) handler

Disk Module

The ‘Disk’ module is responsible to automatically mount and unmount file systems. For an efficient implementation it uses FreeRTOS Direct Task Notification. If SD card and/or USB MSD support is used is configured through #define in platform.h. Below the interface for the disk module:

/*
 * Copyright (c) 2020, Erich Styger
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

#ifndef DISK_H_
#define DISK_H_

#include "platform.h"
#if PL_CONFIG_USE_SD_CARD || PL_CONFIG_USE_USB_MSD
#include <stdbool.h>

typedef enum {
#if PL_CONFIG_USE_SD_CARD
  DISK_EVENT_SD_CARD_INSERTED = (1<<0),
  DISK_EVENT_SD_CARD_REMOVED = (1<<1),
  DISK_EVENT_SD_CARD_REQ_MOUNT = (1<<2),
  DISK_EVENT_SD_CARD_REQ_UNMOUNT = (1<<3),
#endif
#if PL_CONFIG_USE_USB_MSD
  DISK_EVENT_USB_MSD_INSERTED = (1<<4),
  DISK_EVENT_USB_MSD_REMOVED = (1<<5),
  DISK_EVENT_USB_MSD_REQ_MOUNT = (1<<6),
  DISK_EVENT_USB_MSD_REQ_UNMOUNT = (1<<7),
#endif
} DISK_Events;

#include "McuShell.h"
uint8_t DISK_ParseCommand(const unsigned char *cmd, bool *handled, const McuShell_StdIOType *io);

#define DISK_DRIVE_SD_CARD  "0:/"
#define DISK_DRIVE_USB_MSD  "1:/"

/* checks if the device is inserted */
bool DISK_IsInserted(unsigned char *drive);

/* checks if the device is mounted and ready to use */
bool DISK_IsMounted(unsigned char *drive);

void DISK_SendEvent(DISK_Events event);

void DISK_Init(void);

#endif /* PL_CONFIG_USE_SD_CARD || PL_CONFIG_USE_USB_MSD */

#endif /* DISK_H_ */

The implementation uses ‘0’ as device for the SD card and ‘1’ for the USB memory device, but this can be easily changed if needed.
The module runs a FreeRTOS task which blocks on the notification bits so does not need any processing time if not notified.

 
/*
 * Copyright (c) 2020, Erich Styger
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

#include "platform.h"
#if PL_CONFIG_USE_SD_CARD || PL_CONFIG_USE_USB_MSD
#include "disk.h"
#include "McuLog.h"
#include "McuRTOS.h"
#include "McuFatFS.h"
#include "host_msd_fatfs.h"

static TaskHandle_t diskTaskHandle;
#if PL_CONFIG_USE_SD_CARD
  static bool DISK_sdMounted = false;
#endif
#if PL_CONFIG_USE_USB_MSD
  static bool DISK_msdMounted = false;
#endif

bool DISK_IsInserted(unsigned char *drive) {
  switch(*drive) {
  #if PL_CONFIG_USE_SD_CARD
    case '0': return McuFatFS_isDiskPresent(drive);
  #endif
  #if PL_CONFIG_USE_USB_MSD
    case '1': return DISK_msdMounted; /* no special hardware pin */
  #endif
    default: break;
  }
  return false;
}

bool DISK_IsMounted(unsigned char *drive) {
  switch(*drive) {
  #if PL_CONFIG_USE_SD_CARD
    case '0': return DISK_sdMounted;
  #endif
  #if PL_CONFIG_USE_USB_MSD
    case '1': return DISK_msdMounted;
  #endif
    default: break;
  }
  return false;
}

void DISK_SendEvent(DISK_Events event) {
  xTaskNotify(diskTaskHandle, event, eSetBits);
}

static void DiskTask(void *pv) {
  uint32_t ulNotificationValue;
  BaseType_t res;
#if PL_CONFIG_USE_SD_CARD
  static McuFatFS_FATFS fsSdCard;
#endif
#if PL_CONFIG_USE_USB_MSD
  static McuFatFS_FATFS fsUsbMSD;
#endif
  uint8_t result;
  McuFatFS_FRESULT fres;

#if PL_CONFIG_USE_SD_CARD
  DISK_sdMounted = false;
#endif
#if PL_CONFIG_USE_USB_MSD
  DISK_msdMounted = false;
#endif
  for(;;) {
    res = xTaskNotifyWait(
        0, /* do not clear anything on enter */
        0 /* dummy */
    #if PL_CONFIG_USE_SD_CARD
        |DISK_EVENT_SD_CARD_INSERTED|DISK_EVENT_SD_CARD_REMOVED
        |DISK_EVENT_SD_CARD_REQ_MOUNT|DISK_EVENT_SD_CARD_REQ_UNMOUNT
    #endif
    #if PL_CONFIG_USE_USB_MSD
        |DISK_EVENT_USB_MSD_INSERTED|DISK_EVENT_USB_MSD_REMOVED
        |DISK_EVENT_USB_MSD_REQ_MOUNT|DISK_EVENT_USB_MSD_REQ_UNMOUNT
    #endif
        ,
        &ulNotificationValue,
        portMAX_DELAY);
    if (res==pdTRUE) { /* notification received */
    #if PL_CONFIG_USE_SD_CARD
      if (ulNotificationValue&DISK_EVENT_SD_CARD_INSERTED) {
        McuLog_info("SD card inserted");
        DISK_SendEvent(DISK_EVENT_SD_CARD_REQ_MOUNT);
      }
      if (ulNotificationValue&DISK_EVENT_SD_CARD_REMOVED) {
        McuLog_info("SD card removed");
        DISK_SendEvent(DISK_EVENT_SD_CARD_REQ_UNMOUNT);
      }
      if (ulNotificationValue&DISK_EVENT_SD_CARD_REQ_MOUNT) {
        if (DISK_sdMounted) {
          McuLog_error("Mount request, but SD card is already mounted. Unmount it first.");
        } else {
          McuLog_info("SD card mount request");
          /* mount card */
          result = McuFatFS_CheckCardPresence(&DISK_sdMounted, (unsigned char*)DISK_DRIVE_SD_CARD, &fsSdCard, NULL);
          if (result==ERR_OK) {
            McuLog_info("SD card mounted successfully");
          } else {
            McuLog_error("failed mounting SD card");
          }
        }
      }
      if (ulNotificationValue&DISK_EVENT_SD_CARD_REQ_UNMOUNT) {
        McuLog_info("SD card unmount request");
        if (DISK_sdMounted) {
          /* unmount sd card */
          fres = McuFatFS_mount(NULL, (const TCHAR*)DISK_DRIVE_SD_CARD, 0);
          if (fres==FR_OK) {
            DISK_sdMounted = false;
            McuLog_info("SD card unmounted successfully");
          } else {
            McuLog_error("Failed unmounting SD card");
          }
        } else {
          McuLog_error("Unmount request, but SD card is not mounted");
        }
      }
    #endif /* PL_CONFIG_USE_SD_CARD */

    #if PL_CONFIG_USE_USB_MSD
      if (ulNotificationValue&DISK_EVENT_USB_MSD_INSERTED) {
        McuLog_info("USB MSD inserted");
        DISK_SendEvent(DISK_EVENT_USB_MSD_REQ_MOUNT);
      }
      if (ulNotificationValue&DISK_EVENT_USB_MSD_REMOVED) {
        McuLog_info("USB MSD removed");
        DISK_SendEvent(DISK_EVENT_USB_MSD_REQ_UNMOUNT);
      }
      if (ulNotificationValue&DISK_EVENT_USB_MSD_REQ_MOUNT) {
        if (DISK_msdMounted) {
          McuLog_error("Mount request, but USB MSD is already mounted. Unmount it first.");
        } else {
          McuLog_info("USB MSD mount request");
          /* mount card */
          result = USB_HostMsdCheckDiskPresence(&DISK_msdMounted, (unsigned char*)DISK_DRIVE_USB_MSD, &fsUsbMSD, NULL);
          if (result==ERR_OK) {
            McuLog_info("USB MSD mounted successfully");
          } else {
            McuLog_error("Failed mounting USB MSD");
          }
        }
      }
      if (ulNotificationValue&DISK_EVENT_USB_MSD_REQ_UNMOUNT) {
        McuLog_info("USB MSD unmount request");
        if (DISK_msdMounted) {
          /* unmount USB MSD */
          fres = McuFatFS_mount(NULL, (const TCHAR*)DISK_DRIVE_USB_MSD, 0);
          if (fres==FR_OK) {
            DISK_msdMounted = false;
            McuLog_info("USB MSD unmounted successfully");
          } else {
            McuLog_error("Failed unmounting USB MSD");
          }
        } else {
          McuLog_error("Unmount request, but USB MSD is not mounted");
        }
      }
    #endif /* PL_CONFIG_USE_USB_MSD */
    }
  }
}

static uint8_t PrintStatus(const McuShell_StdIOType *io) {
  unsigned char buf[32];

  McuShell_SendStatusStr((unsigned char*)"disk", (unsigned char*)"disk status\r\n", io->stdOut);
#if PL_CONFIG_USE_SD_CARD
  McuUtility_strcpy(buf, sizeof(buf), (unsigned char*)"\"");
  McuUtility_strcat(buf, sizeof(buf), (unsigned char*)DISK_DRIVE_SD_CARD);
  McuUtility_strcat(buf, sizeof(buf), (unsigned char*)"\", mounted: ");
  McuUtility_strcat(buf, sizeof(buf), DISK_sdMounted? (unsigned char*)"yes\r\n":(unsigned char*)"no\r\n");
  McuShell_SendStatusStr((unsigned char*)"  sd drive", buf, io->stdOut);
#endif
#if PL_CONFIG_USE_USB_MSD
  McuUtility_strcpy(buf, sizeof(buf), (unsigned char*)"\"");
  McuUtility_strcat(buf, sizeof(buf), (unsigned char*)DISK_DRIVE_USB_MSD);
  McuUtility_strcat(buf, sizeof(buf), (unsigned char*)"\", mounted: ");
  McuUtility_strcat(buf, sizeof(buf), DISK_msdMounted? (unsigned char*)"yes\r\n":(unsigned char*)"no\r\n");
  McuShell_SendStatusStr((unsigned char*)"  msd drive", buf, io->stdOut);
#endif
  return ERR_OK;
}

static uint8_t PrintHelp(const McuShell_StdIOType *io) {
  McuShell_SendHelpStr((unsigned char*)"disk", (unsigned char*)"Group of disk commands\r\n", io->stdOut);
  McuShell_SendHelpStr((unsigned char*)"  help|status", (unsigned char*)"Print help or status information\r\n", io->stdOut);
#if PL_CONFIG_USE_SD_CARD
  McuShell_SendHelpStr((unsigned char*)"  sd mount|unmount", (unsigned char*)"Mount or unmount SD card device\r\n", io->stdOut);
#endif
#if PL_CONFIG_USE_USB_MSD
  McuShell_SendHelpStr((unsigned char*)"  msd mount|unmount", (unsigned char*)"Mount or unmount USB MSD device\r\n", io->stdOut);
  return ERR_OK;
#endif
}

uint8_t DISK_ParseCommand(const unsigned char *cmd, bool *handled, const McuShell_StdIOType *io) {
  uint8_t res = ERR_OK;

  if (McuUtility_strcmp((char*)cmd, McuShell_CMD_HELP) == 0
    || McuUtility_strcmp((char*)cmd, "disk help") == 0)
  {
    *handled = TRUE;
    return PrintHelp(io);
  } else if (   (McuUtility_strcmp((char*)cmd, McuShell_CMD_STATUS)==0)
             || (McuUtility_strcmp((char*)cmd, "disk status")==0)
            )
  {
    *handled = TRUE;
    res = PrintStatus(io);
#if PL_CONFIG_USE_SD_CARD
  } else if (McuUtility_strcmp((char*)cmd, "disk sd mount")==0) {
    *handled = TRUE;
    DISK_SendEvent(DISK_EVENT_SD_CARD_REQ_MOUNT);
  } else if (McuUtility_strcmp((char*)cmd, "disk sd unmount")==0) {
    *handled = TRUE;
    DISK_SendEvent(DISK_EVENT_SD_CARD_REQ_UNMOUNT);
#endif
#if PL_CONFIG_USE_USB_MSD
  } else if (McuUtility_strcmp((char*)cmd, "disk msd mount")==0) {
    *handled = TRUE;
    DISK_SendEvent(DISK_EVENT_USB_MSD_REQ_MOUNT);
  } else if (McuUtility_strcmp((char*)cmd, "disk msd unmount")==0) {
    *handled = TRUE;
    DISK_SendEvent(DISK_EVENT_USB_MSD_REQ_UNMOUNT);
#endif
  }
  return res;
}

void DISK_Init(void) {
  BaseType_t result;

  result =xTaskCreate(DiskTask, "DiskTask", 2500/sizeof(StackType_t), NULL, tskIDLE_PRIORITY+2, &diskTaskHandle);
  if (result!=pdPASS) {
    McuLog_fatal("Failed creating DiskTask");
    for(;;) {}
  }
}
#endif /* PL_CONFIG_USE_SD_CARD || PL_CONFIG_USE_USB_MSD */

Using the command line interface the status of the system can be inspected and devices manually mounted and unmounted. It automatically detects devices plugged in (or out) and performs the needed actions and logs them:

Configuration with MinIni

To make it easy for the service person in the field, the memory stick can contain a configuration (.ini) file which configures what shall happen when the memory stick is inserted. Below is an example configuration file:

[Mount]
copyLog=yes
srcLogFile=0:\log.txt
dstLogFile=1:\log.txt
unmount=yes

With the above, after mounting the memory stick it will copy the log file. The source file name is “0:\log.txt” (on the SD card) and the destination file is “1:\log.txt” (on the thumb drive). After completion of the copy command, the memory stick is automatically unmounted so it can be removed.

The implementation of this is done in the ‘application’ task: it checks if the thumb drive is detected, then reads the .ini file and performs the actions:

 
    unsigned char srcLogFileName[32], dstLogFileName[32];

    if (DISK_IsMounted((unsigned char*)DISK_DRIVE_USB_MSD)) {
      if (ini_gets(
          (const TCHAR *)"Mount", /* section */
          (const TCHAR *)"copyLog", /* key */
          (const TCHAR *)"no",  /* default value */
          (TCHAR *)keyValueBuf, sizeof(keyValueBuf), /* key value from ini */
          (const TCHAR *)USB_MSD_INI_FILENAME /* ini file */
          )
          > 0) /* success */
      {
        if (McuUtility_strcmp((char*)keyValueBuf, (char*)"yes")==0) { /* copyLog=yes ? */
          if (
              ini_gets(
              (const TCHAR *)"Mount", /* section */
              (const TCHAR *)"srcLogFile", /* key */
              (const TCHAR *)DEFAULT_LOG_SRC_FILENAME,  /* default value */
              (TCHAR *)srcLogFileName, sizeof(srcLogFileName), /* key value from ini */
              (const TCHAR *)USB_MSD_INI_FILENAME /* ini file */
              ) > 0 /* success */
              &&
              ini_gets(
              (const TCHAR *)"Mount", /* section */
              (const TCHAR *)"dstLogFile", /* key */
              (const TCHAR *)DEFAULT_LOG_DST_FILENAME,  /* default value */
              (TCHAR *)dstLogFileName, sizeof(dstLogFileName), /* key value from ini */
              (const TCHAR *)USB_MSD_INI_FILENAME /* ini file */
              ) > 0) /* success */
          {
            /* copy log file */
           McuLog_info("Copy log file '%s' => '%s'", srcLogFileName, dstLogFileName);
           if (McuFatFS_CopyFile(srcLogFileName, dstLogFileName, NULL)!=ERR_OK) {
             McuLED_Off(led);
             for(int i=0;i<10;i++) { /* indicate error with 10 red blinks */ McuLED_Toggle(LEDS_LedRed); vTaskDelay(pdMS_TO_TICKS(500)); } McuLog_error("Copy of log file failed"); } } } } if (ini_gets( (const TCHAR *)"Mount", /* section */ (const TCHAR *)"unmount", /* key */ (const TCHAR *)"no", /* default value */ (TCHAR *)keyValueBuf, sizeof(keyValueBuf), /* key value from ini */ (const TCHAR *)USB_MSD_INI_FILENAME /* ini file */ ) > 0) /* success */
      {
        if (McuUtility_strcmp((char*)keyValueBuf, (char*)"yes")==0) { /* unmount=yes ? */
          DISK_SendEvent(DISK_EVENT_USB_MSD_REQ_UNMOUNT);
          McuLED_Off(led);
          for(int i=0;i<10;i++) { /* indicate unmount with 5 blue blinks */
            McuLED_Toggle(LEDS_LedBlue);
            vTaskDelay(pdMS_TO_TICKS(500));
          }
        }
      }

The task uses FreeRTOS Direct Task Notification to trigger disk actions like unmounting the device after finishing the copy operation. The LED on the board is used to indicate that status (e.g. blinking blue or red for a failure).

Result

Below is an example output and log: the thumb drive gets detected, the file copied to it and then automatically unmounted so it can be removed:

The example project uses around 140 KByte of FLASH memory (no optimizations) and 109 KByte with -O3. RAM is around 30 KByte, with plenty of headroom for all the task stacks. This certainly could be trimmed down depending on the features needed: the FatFS and USB stack are consuming the most of it.

Summary

I have found that using a combination of MinIni with a dual-FatFS system is very powerful: having the .ini file on the thumb drive with configuration data removes the need for an operator to ‘eject’ the thumb drive as no ‘hot-unplug’ is easily possible with FatFS.

I hope you find this useful and might be able to use the presented approach for your projects.

Happy Copying 🙂

Links

• Example on GitHub: https://github.com/ErichStyger/mcuoneclipse/tree/master/Examples/MCUXpresso/FRDM-K22F/FRDM-K22F_FatFS_SD_Card
• FatFS, MinIni, Shell and FreeRTOS for the NXP K22FN512
• Logging Framework: McuLog: Logging Framework for small Embedded Microcontroller Systems
• FreeRTOS: https://www.freertos.org/
• MinIni: https://github.com/compuphase/minIni
• Mcu Library: https://github.com/ErichStyger/McuOnEclipseLibrary
• FatFS: http://elm-chan.org/fsw/ff/00index_e.html
• MCUXpresso IDE: MCUXpresso IDE V11.1.0
• MXUXpresso SDK: https://mcuxpresso.nxp.com
• FRDM-K22F Board: USB with the Freescale FRDM-K22F Board
• SD card for the FRDM-K22F: Added Micro SD Card Socket to FRDM-K22F
• Configuration: Different Ways of Software Configuration