Device File Transfer - Documentation

The device file transfer visualizer lets you download and upload files to your Arduino device.

Our File Manager library for Arduino provides a drop-in implementation for SD cards connected to the SPI or SDMMC bus and LittleFS. LittleFS is implemented on devices such as the ESP8266 and ESP32 as part of the Espressif Arduino core, for example, to store files in the device’s flash memory without any additional hardware.

New here?

Find your way around with our getting started guides.

Device file transfer visualizer screenshot. — Use the Device File Transfer visualizer to download/upload files to your Arduino.

To use the device file transfer visualizer with your Arduino project, you’ll need to add support for the commands the visualizer sends to your sketch and setup the visualizer to match the configuration in your sketch. Both are covered below.

Preparing your Arduino sketch

Use our File Manager library for Arduino to decode and dispatch the commands MegunoLink sends from the device file transfer visualizer in your Arduino sketch.

For a quick start, open an example in the Arduino IDE: File→Examples→
MegunoLink File Manager.

The key steps for your Arduino sketch are:

install the file manager library,
include the appropriate module from the library,
register the module with our command handler library,
initialize the filesystem,
call the command handler and file manager’s process functions each time through your Arduino loop.

We’ll cover each of these steps in the sections below to build up this minimal example to add upload/download support to your Arduino sketch, here with an SD card on the SPI bus:

#include "SDFileManager.h"
#include "CommandHandler.h"

SDFileManager FileManager;

const int MaxCommands = 10;
const int MaxSerialBuffer = 60;
CommandHandler<MaxCommands, MaxSerialBuffer> Cmds;

void InitFileSystem()
{
  DeviceFileTransfer dft;
  const uint8_t SD_CHIP_SELECT_PIN = 4;
  if (SD.begin(SD_CHIP_SELECT_PIN))
  {
    Serial.println(F("SD card ready."));
  }
  else
  {
    Serial.println(F("Failed to mount SD card"));
    dft.ReportSDMountFailed();
  }
}

void setup()
{
  Serial.begin(500000);

  Cmd.AddModule(&FileManager);

  InitFileSystem();
}

void loop()
{
  Cmds.Process();
  FileManager.Process();
}

#include "SDFileManager.h"

#include "CommandHandler.h"

SDFileManager FileManager;

const int MaxCommands = 10;

const int MaxSerialBuffer = 60;

CommandHandler<MaxCommands, MaxSerialBuffer> Cmds;

void InitFileSystem()

{

DeviceFileTransfer dft;

const uint8_t SD_CHIP_SELECT_PIN = 4;

if (SD.begin(SD_CHIP_SELECT_PIN))

{

Serial.println(F("SD card ready."));

}

else

{

Serial.println(F("Failed to mount SD card"));

dft.ReportSDMountFailed();

}

void setup()

{

Serial.begin(500000);

Cmd.AddModule(&FileManager);

InitFileSystem();

}

void loop()

{

Cmds.Process();

FileManager.Process();

}

The file manager library documentation contains more detail about configuring the library behavior, including disabling file delete and clearing all files, in your Arduino sketch.

Installing the File Manager library

Install the File Manager library using the Library Manager in the Arduino IDE. Just search for “MegunoLink File Manager”.

You can also download the File Manager library directly from GitHub and copy it into your Arduino library folder.

MegunoLink Library

You’ll need to install our MegunoLink library for Arduino too. The File Manager library uses it.

Include File System Module

The File Manager library supports three storage systems: an SD card connected to the SPI bus (most devices), SDMMC bus (ESP32) or LittleFS using built-in flash memory (ESP8266 and ESP32). You’ll need to include the file and create a variable for the module that matches your configuration. The table below shows the available options.

For example, if you are using an SD card connected to the Arduino’s SPI bus you’ll need:

#include <SDFileManager.h>

SDFileManager FileManager;

#include <SDFileManager.h>

SDFileManager FileManager;

Storage	Bus	Include file	Variable
SD card	SPI	`#include "SDFileManager.h"`	`SDFileManager FileManager;`
SD card	SDMMC	`#include "SDMMCFileManager.h"`	`SDMMCFileManager FileManager;`
Internal flash	n/a	`#include "LittleFSFileManager.h"`	`LittleFSFileManager FileManager;`

Register with Command Handler

The File Manager library uses our command handler to decode and dispatch messages sent from the visualizer in MegunoLink. So you’ll need to include a command handler in your sketch and register the FileManager variable with it.

Include the library and create a command handler variable at the top of your sketch:

#include "SDFileManager.h"
#include "CommandHandler.h"

SDFileManager FileManager;

const int MaxCommands = 10;
const int MaxSerialBuffer = 60;
CommandHandler<MaxCommands, MaxSerialBuffer> Cmds;

#include "SDFileManager.h"

#include "CommandHandler.h"

SDFileManager FileManager;

const int MaxCommands = 10;

const int MaxSerialBuffer = 60;

CommandHandler<MaxCommands, MaxSerialBuffer> Cmds;

If you are going to send files from your computer to the Arduino, increase the size of the command handlers receive buffer so there is room for the file messages. The buffer size is set with the second template parameter, MaxSerialBuffer above.

Increase receive buffer size

Increase the command handler’s receive buffer size—if sending files to the Arduino.

Your Arduino will receive files faster with a larger buffer, but use more RAM—60 bytes is a good choice. You must also set the size of this buffer in MegunoLink, so it knows how to break up the file for sending.

If you are only downloading files off the Arduino, you can leave the default buffer size.

Then, in your setup function, register the FileManager with the CommandHandler:

void setup()
{
  Serial.begin(500000);

  Cmd.AddModule(&FileManager);
}

void setup()

{

Serial.begin(500000);

Cmd.AddModule(&FileManager);

}

Of course, you can register any other commands your sketch needs too by calling Cmd.AddCommand(…).

Initialize the file system

Whether you’re using an SD card connected to a SPI bus, a SDMMC bus or the LittleFS internal file system, you need to initialize it in your setup program as you would for any other sketch. The initialization code depends on the hardware you’re using to talk to the SD card. Some common examples are:

SD card on SPI bus

void InitFileSystem()
{
  DeviceFileTransfer dft;
  const uint8_t SD_CHIP_SELECT_PIN = 4;
  if (SD.begin(SD_CHIP_SELECT_PIN))
  {
    Serial.println(F("SD card ready."));
  }
  else
  {
    Serial.println(F("Failed to mount SD card"));
    dft.ReportSDMountFailed();
  }
}

void InitFileSystem()

{

DeviceFileTransfer dft;

const uint8_t SD_CHIP_SELECT_PIN = 4;

if (SD.begin(SD_CHIP_SELECT_PIN))

{

Serial.println(F("SD card ready."));

}

else

{

Serial.println(F("Failed to mount SD card"));

dft.ReportSDMountFailed();

}

SD card on SDMMC bus

void InitFileSystem()
{
#if defined(ARDUINO_ARCH_ESP32)
  // Many ESP32 boards need a pullup on the Data0Pin for
  // SD MMC interface. Implement with internal pullup. 
  const uint8_t Data0Pin = 2; 
  pinMode(Data0Pin, INPUT_PULLUP);
  delay(100);
#endif
  
  if (SD_MMC.begin())
  {
    uint8_t uCardType = SD_MMC.cardType();
    if (uCardType == CARD_NONE)
    {
      Serial.println(F("No card installed"));
    }
    else
    {
      Serial.println(F("Card ready."));
    }
  }
  else
  {
    Serial.println(F("Failed to mount SD card"));
  }
}

void InitFileSystem()

{

#if defined(ARDUINO_ARCH_ESP32)

// Many ESP32 boards need a pullup on the Data0Pin for

// SD MMC interface. Implement with internal pullup.

const uint8_t Data0Pin = 2;

pinMode(Data0Pin, INPUT_PULLUP);

delay(100);

#endif

if (SD_MMC.begin())

{

uint8_t uCardType = SD_MMC.cardType();

if (uCardType == CARD_NONE)

{

Serial.println(F("No card installed"));

}

else

{

Serial.println(F("Card ready."));

}

else

{

Serial.println(F("Failed to mount SD card"));

}

LittleFS

void InitFileSystem()
{
#if defined(ARDUINO_ARCH_ESP32)
  bool bInitialized = LittleFS.begin(true);

#elif defined(ARDUINO_ARCH_ESP8266)

  bool bInitialized = LittleFS.begin();
#else
  bool bInitialized = false;
#endif

  if (bInitialized)
  {
    Serial.println(F("Little FS ready"));
  }
  else
  {
    Serial.println(F("Failed to initialize LittleFS"));
  }
}

void InitFileSystem()

{

#if defined(ARDUINO_ARCH_ESP32)

bool bInitialized = LittleFS.begin(true);

#elif defined(ARDUINO_ARCH_ESP8266)

bool bInitialized = LittleFS.begin();

#else

bool bInitialized = false;

#endif

if (bInitialized)

{

Serial.println(F("Little FS ready"));

}

else

{

Serial.println(F("Failed to initialize LittleFS"));

}

Make sure to call InitFileSystem() from your sketch’s setup function.

void setup()
{
  Serial.begin(500000);

  Cmd.AddModule(&FileManager);

  InitFileSystem();
}

void setup()

{

Serial.begin(500000);

Cmd.AddModule(&FileManager);

InitFileSystem();

}

Call Process Functions

Inside your sketch’s loop function, call the Process method for the command handler and the file manager variables:

void loop()
{
  Cmds.Process();
  FileManager.Process();
}

void loop()

{

Cmds.Process();

FileManager.Process();

}

Calling Process on the command handler is needed to receive, decode and dispatch messages on the serial port. The file manager automatically caches open files to improve performance; its Process method closes any files left open if the connection to MegunoLink is lost part way through a file transfer.

Visualizer Setup

Select Device File Transfer from the visualizer menu or toolbox to add a new file transfer visualizer to your MegunoLink project. Drag the visualizer tab to organize the windows in your MegunoLink project and use the source selector to link the visualizer to a connection.

The visualizer is split into three lists:

Tell the device file transfer visualizer the size of your Arduino’s receive buffer if you will be sending files from MegunoLink to your Arduino.

Click to open the configuration dialog. Enter the same value you used for MaxSerialBuffer in your Arduino sketch. MegunoLink will display the file block size, the number of file bytes sent with each message to your Arduino.

Visualizer Toolbar

Use the toolbar to transfer files, configure and control the visualizer.

Tool	Description
	Connect/disconnect the selected connection. Use the drop-down to select the connection used by this visualizer.
	Choose the computer folder for sending and receiving files.
	Update the list of local files with any changes made on disk.
	Send the selected local files to the Arduino. You can also drag from the `Local files` list onto the `Transfer Queue` to send files.
	Delete the selected local files.
	Cancel the current file transfer.
	Clear any completed operations from the `Transfer Queue`.
	Clear all operations from the `Transfer Queue`, including pending operations and files being transferred.
	Request the list of available files from the Arduino.
	Download the selected files from the Arduino.
	Delete the selected files from the Arduino.
	Delete all files on the Arduino.
	Open the device file transfer visualizer configuration.