Description

The i_FileTrans_ReceiveFile() – function receives a file over a serial connection, typically a CAN2SER link to the PC or another dice device and writes it into the SerialFlash. The sender has to be prepared first (i_FileTrans_SendFile()) so that the receiver would now start the actual transmission process by calling i_FileTrans_ReceiveFile().
The i_FileTrans_ReceiveFile() function creates the received file in the SerialFlash if it does not exist. If it does exist then it would replace it (remove / erase first) and then re-create it. The function would try to reclaim the memory space of the previous file if possible to safe memory space. In case of an error, the file will be ‘erased’ (filled with 0xFF) but not deleted.

Syntax

i_FileTrans_ReceiveFile( op_Serial, op_SerFlash, ou32_version = 0, oac_Filename = NULL, ob_compareOnly = false);

Parameters

HardwareSerial* op_Serial: pointer to the serial interface or derived class like CAN2SER (e.g. &Serial)
SerialFlashChip* op_SerFlash: pointer to the SerialFlash object (typ. &SerialFlash)

Optional:
uint32_t ou32_version : only accept file version (0: accept any version – default)
char* oac_Filename : only accept file name (NULL: accept any file name – default)
bool ob_compareOnly : if true only compares the file with the one present in flash and does not erase / write anything (false – default)
The optional parameters can be omitted for normal operation.
ob_compareOnly (if true) provides the opportunity to compare a file that should be transmitted first before the flash-chip is touched. This can be useful to improve flash chip durability in cases where files are transferred regularly but rarely differ (e.g. status files from another device etc.)

Returns

int: 1 – success (or file is equal to the one in flash – if compareOnly mode is used)

  • 0 – error sending ‘enquiry’ signal over the interface
  • -1 – timeout – waiting for ‘start of header’ signal from sender
  • -2 – error receiving feasible header
  • -3 – error could not create the file in serial flash
  • -4 – error sending header acknowledge signal to ‘sender’
  • -5 – error during data transmission
  • -6 – error while sending final confirmation to ‘sender’
  • -7 – error file version was not right
  • -8 – error file name was not expected
  • -9 – (compareOnly) file name doesn’t exist in flash to compare it
  • -10 – (compareOnly) file received is different from the one in flash

Example Code

#include "FileTransfer.h"
#include "SerialFlash.h"
void setup()
{
  SerialFlash.begin();
  while(!Serial);
}
void loop()
{
  int i_Ret = 0;
  Serial.println("Sending receive enquiry to PC");	
  do
  {
    i_Ret = i_FileTrans_ReceiveFile(&Serial, &SerialFlash);
  }while( i_Ret != 1 );
  delay(1000);
  Serial.println("\n - DONE -");
}

Notes and Warnings

Examples can be found in the Arduino IDE menu:
File -> Examples -> DICE -> FileTransfer

See also

Find more details here:

CAN2SER – Library
SerialFlash – Library
SAMC21_CAN – Library
Device addressing