Load Application From Flash Card

EFFS Load Application From Flash Card

Overview

This NetBurner application demonstrates how to update firmware from a binary image file stored on a flash card. The application uses the Extra File Descriptor (ExtraFD) mechanism to create a file stream interface that enables direct firmware programming from flash card storage.

Supported Platforms

• MOD5441X - On-board microSD card socket support
• Support for external flash card interfaces (commented options available)

Hardware Requirements

• NetBurner MOD5441X module
• MicroSD card with firmware binary file
• Serial console for monitoring update process
• Formatted flash card (FAT16/FAT32)

Application Functionality

Main Features

1. Flash Card Mounting: Automatically detects and mounts microSD card
2. Binary File Reading: Reads application binary from flash card storage
3. ExtraFD Stream Interface: Creates file descriptor from flash file pointer
4. Stream-Based Programming: Programs firmware using NetBurner's stream update mechanism
5. Automatic Reboot: Restarts system after successful firmware update

Program Flow

1. Initialization
   • Initialize network stack and file system
   • Enter EFFS file system context
   • Mount on-board flash card (microSD)
2. File System Operations
   • Display directory contents
   • Locate firmware file "AppToLoad.bin"
   • Create Extra FD from file pointer
3. Firmware Update Process
   • Read binary file through ExtraFD interface
   • Program new application to flash memory
   • Verify programming success
   • Reboot system to run new firmware

Update Process Flow

Flash Card ---> ExtraFD ---> Stream Interface ---> Flash Programming ---> Reboot
    |              |              |                     |              |
AppToLoad.bin   File Stream   Binary Reader      Application        New App
                                                   Update           Running

Key Components

Files Structure

EffsLoadAppFromFlashCard/
|-- src/
|   |-- main.cpp            # Main application logic
|   +-- FileSystemUtils.h   # File system utility functions
|-- makefile                # Build configuration
+-- README.md               # This documentation

ExtraFD Implementation

Core ExtraFD Functions:**

• fileToExtraFdRead(): Reads data from flash file into buffer
• fileToExtraFdWrite(): Write function (not implemented in this example)
• fileToExtraFdClose(): Closes flash file and releases ExtraFD

• makeFdFromFile(): Creates file descriptor from F_FILE pointer

  ExtraFD Structure:**

  IoExpandStruct fileToExtraFd = {
      .read = fileToExtraFdRead,
      .write = fileToExtraFdWrite,
      .close = fileToExtraFdClose,
      .peek = 0
  };

Stream Update Process

Key Functions:**

• GetExtraFD(): Allocates Extra File Descriptor
• ReadBinaryApplicationCodeFromStream(): Programs firmware from stream

• ForceReboot(): Restarts system after successful update

  Update Result Codes:**

• STREAM_UP_OK: Update completed successfully
• Error codes indicate specific failure reasons

File Preparation

Creating Update Files

1. Build Target Application:

   make PLATFORM=MOD5441X
   # This creates *.s19 file in project directory

2. Convert to Binary Format:

   # Use NetBurner tools or standard utilities
   objcopy -O binary target.elf AppToLoad.bin

3. Copy to Flash Card:
   • Name the file exactly "AppToLoad.bin"
   • Place in root directory of flash card
   • Ensure flash card is FAT16 or FAT32 formatted

File Requirements

• Filename: Must be exactly "AppToLoad.bin"
• Location: Root directory of flash card
• Format: Raw binary (not S-record or ELF)
• Size: Must fit in available flash memory
• Compatibility: Must be compiled for target platform

Building and Deployment

Build the updater application

Load updater to device

Required Libraries

This example requires EFFS FAT file system support:

Additional Files Required

Copy from \nburn\examples\_common\EFFS\FAT:

• FileSystemUtils.h
• FileSystemUtils.cpp
• cardtype.h (if needed)

Usage Instructions

Step-by-Step Update Process

1. Prepare Flash Card:
   • Format microSD card (FAT32 recommended)
   • Copy "AppToLoad.bin" to root directory
   • Verify file is present and readable
2. Load Updater:
   • Build and load this updater application
   • Insert prepared flash card into module
   • Connect serial console for monitoring
3. Execute Update:
   • Application will display directory contents
   • Press any key when prompted to start update
   • Monitor progress messages
   • Wait for automatic reboot (10 seconds)

Expected Console Output

Initializing the on-board Flash card...
Drive change successful
Directory listing:
AppToLoad.bin        524288
 
Type any key to program new application to flash
Opening file: "AppToLoad.bin"
Update complete, system will reboot in 10 seconds...

Error Handling

Common Error Conditions

1. Drive Mount Failure:

   drive change failed: [error code]

   • Check flash card insertion
   • Verify card formatting (FAT16/FAT32)
   • Ensure card is not corrupted
2. File Not Found:

   Failed to find file: "AppToLoad.bin"

   • Verify filename is exactly "AppToLoad.bin"
   • Check file is in root directory
   • Confirm file is not corrupted
3. Stream Update Failure:

   ERROR: Stream update failed, error code: [code]

   • Binary file may be corrupted
   • Insufficient flash memory space
   • Binary not compatible with target platform
4. ExtraFD Creation Failure:

   Extra FD create failed

   • System resource exhaustion
   • File system integrity issues

Debug Techniques

File System Verification:**

// Add debug output to verify file system state
iprintf("Current directory: %s\n", GetCurrentDirectory());
iprintf("File size: %ld bytes\n", GetFileSize("AppToLoad.bin"));

Stream Progress Monitoring:**

// Monitor update progress
int totalBytes = fdReadToEnd(fd);
iprintf("Total bytes processed: %d\n", totalBytes);

Advanced Features

Custom Update Sources

External Flash Card Support:**

// Uncomment to use external flash card socket
// int drv = OpenOffBoardFlash();  // Dev board flash socket
int drv = OpenOnBoardFlash();     // Module microSD socket

Network-Based Updates:**

// Extend ExtraFD for network sources
int networkToExtraFdRead(int fd, char *buf, int nbytes) {
    // Read from TCP socket, HTTP, etc.
    return networkRead(buf, nbytes);
}

Multi-File Updates

// Update multiple components
char *updateFiles[] = {"bootloader.bin", "application.bin", "config.bin"};
for(int i = 0; i < 3; i++) {
    UpdateFromFile(updateFiles[i]);
}

Verification and Security

// Add checksum verification
uint32_t CalculateChecksum(int fd) {
    // Implement CRC32 or similar
    return checksum;
}
 
bool VerifyUpdate(const char *filename) {
    // Compare against stored checksum
    return checksumValid;
}

Safety Considerations

Update Reliability

1. Power Supply: Ensure stable power during update process
2. Backup Strategy: Keep previous firmware version accessible
3. Verification: Implement checksum validation before programming
4. Recovery Mode: Consider implementing emergency recovery mechanism

Flash Memory Protection

// Verify sufficient space before update
uint32_t requiredSpace = GetFileSize("AppToLoad.bin");
uint32_t availableSpace = GetFlashSpaceAvailable();
if(requiredSpace > availableSpace) {
    iprintf("ERROR: Insufficient flash memory\n");
    return;
}

Update Validation

// Validate binary format before programming
bool ValidateBinaryFormat(int fd) {
    // Check for valid application headers
    // Verify target platform compatibility
    return isValid;
}

Performance Characteristics

Update Timing

• Read Speed: Limited by flash card interface (typically 1-10 MB/s)
• Programming Speed: Limited by internal flash programming rate
• Total Time: Depends on application size (typically seconds to minutes)

Memory Usage

• ExtraFD Overhead: Minimal system resource usage
• Buffer Size: Configurable read buffer size
• Flash Requirements: Must fit in available application flash space

Application Extensions

User Interface Enhancements

// Progress indicator
void DisplayUpdateProgress(int bytesProcessed, int totalBytes) {
    int percent = (bytesProcessed * 100) / totalBytes;
    iprintf("Update progress: %d%%\r", percent);
}

Remote Update Management

// Web interface for update control
void HandleUpdateCommand(char *filename) {
    StartUpdateProcess(filename);
}

Batch Updates

// Update multiple devices
void BroadcastUpdate(char *filename) {
    // Send update to multiple networked devices
}

Related Examples

• EFFS Examples: File system operations and management
• Stream Examples: Alternative stream-based programming methods
• Network Update: Over-the-air firmware update mechanisms
• Bootloader Examples: Custom bootloader implementation
• Flash Programming: Direct flash memory programming techniques