NetBurner 3.5.8
PDF Version
Basic

Example Path: examples/EFFS/Fat/Basic

EFFS-FAT-Basic File System Example

Overview

This program demonstrates basic file system operations for SD/MMC and Compact Flash cards using the Embedded Flash File System with File Allocation Table (EFFS-FAT) library. The application provides a comprehensive example of external flash storage management on embedded systems.

Warning
All EFFS FAT examples require that you add the Embedded Flash File System File Allocation Table (EFFS FAT) library to your project: Add a Library to a Project
This example does not set the system clock, so the date and time stamps written on the files it creates (and shown in the directory listing) will be incorrect. To set the clock so files are stamped with the correct date and time, see the HTTP example, which synchronizes the time from an NTP server at startup.

Features

The application demonstrates the following file system operations:

  • Drive Mounting: Initialize and mount external storage devices
  • Space Management: Determine used and free file space on the storage device
  • File Creation: Create new files on the external storage
  • Data Writing: Write data to files on the storage device
  • Data Reading: Read data from files on the storage device
  • Drive Unmounting: Safely unmount the storage device

Supported Storage Types

The application supports multiple storage interfaces:

  • SD/MMC Cards: Secure Digital and MultiMediaCard support
  • Compact Flash Cards: CompactFlash card support
  • Multi-drive configurations: For modules with onboard flash sockets

Hardware Compatibility

The application includes specific support for:

  • MOD5441X modules
  • SBE70LC modules
  • Other NetBurner modules with MMC/SD or CFC interfaces

Program Flow

  1. Initialization: Network stack initialization and system diagnostics
  2. File System Entry: Register the current task for file system access
  3. External Flash Initialization: Initialize the CFC or SD/MMC drive
  4. Status Display: Show file space usage statistics
  5. Directory Listing: Display existing files and directories
  6. Read/Write Operations: Perform file system read and write tests
  7. Cleanup: Unmount the file system and release resources

Important Notes

File System Access

The EFFS FAT file system is a single shared resource that any number of RTOS tasks may use at the same time. To make that safe, the library keeps a small amount of per-task state, and each task must register itself before it makes any file system call. That registration is what f_enterFS() does. Specifically:

  • It allocates this task's file system context. The library tracks a current drive and current working directory separately for every task, so one task changing directories with f_chdir() doesn't move another task out from under it. f_enterFS() creates the slot that holds this task's context; until it is called, the library has no place to store that state for the task.
  • It enrolls the task in the file system's locking. Concurrent access is coordinated with internal mutual-exclusion. A task has to be registered for that locking to apply to it, which is why calling any other f_* function before f_enterFS() is undefined and will fail.
  • It must be called exactly once per task, before any other file system call. Calling it more than once in the same task, or calling file functions before it, is an error.
  • Slots are a limited resource. By default up to 10 tasks may be registered at once (configurable). A task that no longer needs file access should call f_releaseFS() to free its slot for another task.

In this example, UserMain() is the only task that touches the file system, so it calls f_enterFS() once at startup and f_releaseFS() at the end. The Multiple Tasks example shows several tasks each calling f_enterFS() and sharing the card concurrently.

Web Server Limitations

  • For web server functionality with external storage, refer to the EFFS-HTTP example

Library Requirements

Warning
All EFFS FAT examples require adding the Embedded Flash File System File Allocation Table (EFFS FAT) library to your project.

Output

The program displays status information through the debug serial port, including:

  • Program startup messages
  • File system statistics
  • Directory contents
  • Read/write operation results
  • Program completion status

Usage

  1. Ensure your NetBurner module has the appropriate external flash interface (SD/MMC or CFC)
  2. Insert a compatible flash card into the module
  3. Build and deploy the application to your NetBurner module
  4. Monitor the debug serial output for program status and results
  5. Reset the device to repeat the demonstration

Build Configuration

The application uses preprocessor definitions to determine the storage type:

  • USE_MMC: Enable MMC/SD card support
  • USE_CFC: Enable Compact Flash card support
  • MULTI_MMC: Enable multi-drive MMC support (for specific modules)

File Structure

  • main.cpp: Main application code with UserMain() function
  • ReadMe.txt: Original documentation
  • FileSystemUtils.h: Header file for file system utility functions

Error Handling

The application includes proper error handling for:

  • File system mounting/unmounting operations
  • File access operations
  • Network initialization timeouts
  • Resource cleanup
Warning
After completing all operations, the program enters an infinite loop and must be reset to repeat the demonstration.