• 0 - if MMC/SD card was detected and successfully initialized
• 1 - otherwise

Initializes MMC through hardware SPI interface.

Mmc_Init needs to be called before using other functions of this library.

The appropriate hardware SPI module must be previously initialized.

• Mmc_Chip_Select: Chip Select line
• Mmc_Chip_Select_Direction: Direction of the Chip Select pin

The appropriate hardware SPI module must be previously initialized. See the SPI1_Init, SPI1_Init_Advanced routines.

// MMC module connections	
var Mmc_Chip_Select : sbit at RC0_bit;
var Mmc_Chip_Select_Direction : sbit at TRISC0_bit;
// MMC module connections

error = Mmc_Init();  // Init with CS line at RC.0
var i : byte;
...
SPI1_Init();
i = Mmc_Init();

• 0 - if reading was successful
• 1 - if an error occurred

The function reads one sector (512 bytes) from MMC card.

Parameters:

• sector: MMC/SD card sector to be read.
• dbuff: buffer of minimum 512 bytes in length for data storage.

MMC/SD card must be initialized. See Mmc_Init.

// read sector 510 of the MMC/SD card
var error : byte;
    sectorNo : longint;
    dataBuffer : array[512] of byte;
...
sectorNo := 510;
error := Mmc_Read_Sector(sectorNo, dataBuffer);

• 0 - if writing was successful
• 1 - if there was an error in sending write command
• 2 - if there was an error in writing (data rejected)

The function writes 512 bytes of data to one MMC card sector.

Parameters:

• sector: MMC/SD card sector to be written to.
• dbuff: data to be written (buffer of minimum 512 bytes in length).

MMC/SD card must be initialized. See Mmc_Init.

// write to sector 510 of the MMC/SD card
var error : byte;
    sectorNo : longint;
    dataBuffer : array[512] of byte;
...
sectorNo := 510;
error := Mmc_Write_Sector(sectorNo, dataBuffer);

• 0 - if CID register was read successfully
• 1 - if there was an error while reading

The function reads 16-byte CID register.

Parameters:

• data_cid: buffer of minimum 16 bytes in length for storing CID register content.

MMC/SD card must be initialized. See Mmc_Init.

var error : byte;
    dataBuffer : array[16] of byte;
...
error := Mmc_Read_Cid(dataBuffer);

• 0 - if CSD register was read successfully
• 1 - if there was an error while reading

The function reads 16-byte CSD register.

Parameters:

• data_for_registers: buffer of minimum 16 bytes in length for storing CSD register content.

MMC/SD card must be initialized. See Mmc_Init.

var error : word;
    data_csd : array[16] of byte;
...
error := Mmc_Read_Csd(data_csd);

The function starts multi read mode, sectors are sequentially read starting from the sector given in the function argument.

• sector: starting sector number.

• 0 - if multi read start was successful.
• 1 - ir error occured.

MMC/SD card must be initialized. See Mmc_Init.

var start_sector : dword;
var error : byte;
...
error := Mmc_Multi_Read_Start(start_sector);

None.

The function reads sectors in multi read mode and places them in the buffer given as the function argument. Next function call reads the subsequent sector. Buffer size should be 512B.

• dbuff: buffer for holding the sector data.

Nothing.

MMC/SD card must be initialized. See Mmc_Init.

var ext_buffer : array[512] of byte;
...
Mmc_Multi_Read_Sector(ext_buffer);
 

None.

The function stops multi read mode sequence.

None.

• 0 - if stop was successful.
• 1 - ir error was detected.

MMC/SD card must be initialized. See Mmc_Init.

var error : byte;
...
error := Mmc_Multi_Read_Stop();

None.

• 0 - if MMC/SD card was detected and successfully initialized
• 1 - if FAT16 boot sector was not found
• 255 - if MMC/SD card was not detected

Initializes MMC/SD card, reads MMC/SD FAT16 boot sector and extracts necessary data needed by the library.

  Note : MMC/SD card has to be formatted to FAT16 file system.

• Mmc_Chip_Select: Chip Select line
• Mmc_Chip_Select_Direction: Direction of the Chip Select pin

The appropriate hardware SPI module must be previously initialized. See the SPI1_Init, SPI1_Init_Advanced routines.

// MMC module connections	
var Mmc_Chip_Select : sbit at RC0_bit;
var Mmc_Chip_Select_Direction : sbit at TRISC0_bit;
// MMC module connections

SPI1_Init();

// init the FAT library
if (Mmc_Fat_Init() = 0) then
  begin
    SPI1_Init();
  ...
  end

• 0 - if MMC/SD card was detected, successfully formated and initialized
• 1 - if FAT16 format was unsuccessful
• 255 - if MMC/SD card was not detected

Formats to FAT16 and initializes MMC/SD card.

Parameters:

• mmc_fat_label: volume label (11 characters in length). If less than 11 characters are provided, the label will be padded with spaces. If null string is passed volume will not be labeled

  Note :

• This routine can be used instead or in conjunction with Mmc_Fat_Init routine.
• If MMC/SD card already contains a valid boot sector, it will remain unchanged (except volume label field) and only FAT and ROOT tables will be erased. Also, the new volume label will be set.

The appropriate hardware SPI module must be previously initialized.

// format and initialize the FAT library
if (Mmc_Fat_QuickFormat('mikroE') = 0) then
begin
  ...
end;

• 2 - if there are no more free file handlers, currently opened file is closed in order to free space.
• 1 - if file already exists or file does not exist but a new file is created.
• 0 - if file does not exist and no new file is created.

Assigns file for file operations (read, write, delete...). All subsequent file operations will be applied on an assigned file.

Parameters:

• filename: name of the file that should be assigned for file operations. File name should be in DOS 8.3 (file_name.extension) format. The file name and extension will be automatically padded with spaces by the library if they have less than length required (i.e. "mikro.tx" -> "mikro .tx "), so the user does not have to take care of that. The file name and extension are case insensitive. The library will convert them to proper case automatically, so the user does not have to take care of that.
• file_cre_attr: file creation and attributs flags. Each bit corresponds to the appropriate file attribut:

Bit	Mask	Description
0	0x01	Read Only
1	0x02	Hidden
2	0x04	System
3	0x08	Volume Label
4	0x10	Subdirectory
5	0x20	Archive
6	0x40	Device (internal use only, never found on disk)
7	0x80	File creation flag. If file does not exist and this flag is set, a new file with specified name will be created.

  Note : Long File Names (LFN) are not supported.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

// create file with archive attribut if it does not already exist
Mmc_Fat_Assign('MIKRO007.TXT',0xA0);

Nothing.

Procedure resets the file pointer (moves it to the start of the file) of the assigned file, so that the file can be read.

Parameters:

• size: buffer to store file size to. After file has been open for reading, its size is returned through this parameter.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

var size : dword;
...
Mmc_Fat_Reset(size);

Nothing.

Reads a byte from the currently assigned file opened for reading. Upon function execution, file pointers will be set to the next character in the file.

Parameters:

• bdata: buffer to store read byte to. Upon this function execution read byte is returned through this parameter.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

The file must be opened for reading. See Mmc_Fat_Reset.

var character : byte;
...
Mmc_Fat_Read(character);

Nothing.

Opens the currently assigned file for writing. If the file is not empty its content will be erased.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

// open file for writing
Mmc_Fat_Rewrite();

Nothing.

Opens the currently assigned file for appending. Upon this function execution file pointers will be positioned after the last byte in the file, so any subsequent file writing operation will start from there.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

// open file for appending
Mmc_Fat_Append();

• 1 - if there are no assigned files
• 2 - if an error occured during deleting
• 0 - if deleting was successful

Deletes currently assigned file from MMC/SD card.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

// delete current file
if (Mmc_Fat_Delete() = 0) then

Nothing.

Writes requested number of bytes to the currently assigned file opened for writing.

Parameters:

• fdata: data to be written.
• data_len: number of bytes to be written.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

The file must be opened for writing. See Mmc_Fat_Rewrite or Mmc_Fat_Append.

var file_contents : array[42] of byte;
...
Mmc_Fat_Write(file_contents, 42); // write data to the assigned file

Nothing.

Sets the date/time stamp. Any subsequent file writing operation will write this stamp to the currently assigned file's time/date attributs.

Parameters:

• year: year attribute. Valid values: 1980-2107
• month: month attribute. Valid values: 1-12
• day: day attribute. Valid values: 1-31
• hours: hours attribute. Valid values: 0-23
• mins: minutes attribute. Valid values: 0-59
• seconds: seconds attribute. Valid values: 0-59

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

The file must be opened for writing. See Mmc_Fat_Rewrite or Mmc_Fat_Append.

Mmc_Fat_Set_File_Date(2005,9,30,17,41,0);

Nothing.

Reads time/date attributes of the currently assigned file.

Parameters:

• year: buffer to store year attribute to. Upon function execution year attribute is returned through this parameter.
• month: buffer to store month attribute to. Upon function execution month attribute is returned through this parameter.
• day: buffer to store day attribute to. Upon function execution day attribute is returned through this parameter.
• hours: buffer to store hours attribute to. Upon function execution hours attribute is returned through this parameter.
• mins: buffer to store minutes attribute to. Upon function execution minutes attribute is returned through this parameter.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

var year : word;
    month, day, hours, mins : byte;
...
Mmc_Fat_Get_File_Date(year, month, day, hours, mins);

Nothing.

Retrieves the last modification date/time for the currently selected file.

Parameters:

• year: buffer to store year of modification attribute to. Upon function execution year of modification attribute is returned through this parameter.
• month: buffer to store month of modification attribute to. Upon function execution month of modification attribute is returned through this parameter.
• day: buffer to store day of modification attribute to. Upon function execution day of modification attribute is returned through this parameter.
• hours: buffer to store hours of modification attribute to. Upon function execution hours of modification attribute is returned through this parameter.
• mins: buffer to store minutes of modification attribute to. Upon function execution minutes of modification attribute is returned through this parameter.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

var year : word;
    month, day, hours, mins : byte;
...
Mmc_Fat_Get_File_Date_Modified(year, month, day, hours, mins);

This function returns size of active file (in bytes).

This function reads size of the currently assigned file in bytes.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

var my_file_size : dword; 
...
my_file_size := Mmc_Fat_Get_File_Size();

This function returns the current file write sector.

None.

This function returns the current file write sector.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

var sector : dword;
...
sector := Mmc_Get_File_Write_Sector();

None.

• Number of the start sector for the newly created swap file, if there was enough free space on the MMC/SD card to create file of required size.
• 0 - otherwise.

This function is used to create a swap file of predefined name and size on the MMC/SD media. If a file with specified name already exists on the media, search for consecutive sectors will ignore sectors occupied by this file. Therefore, it is recommended to erase such file if it already exists before calling this function. If it is not erased and there is still enough space for a new swap file, this function will delete it after allocating new memory space for a new swap file.

The purpose of the swap file is to make reading and writing to MMC/SD media as fast as possible, by using the Mmc_Read_Sector() and Mmc_Write_Sector() functions directly, without potentially damaging the FAT system. The swap file can be considered as a "window" on the media where the user can freely write/read data. Its main purpose in the library is to be used for fast data acquisition; when the time-critical acquisition has finished, the data can be re-written into a "normal" file, and formatted in the most suitable way.

Parameters:

• sectors_cnt: number of consecutive sectors that user wants the swap file to have.
• filename: name of the file that should be assigned for file operations. File name should be in DOS 8.3 (file_name.extension) format. The file name and extension will be automatically padded with spaces by the library if they have less than length required (i.e. "mikro.tx" -> "mikro .tx "), so the user does not have to take care of that. The file name and extension are case insensitive. The library will convert them to proper case automatically, so the user does not have to take care of that.

  Also, in order to keep backward compatibility with the first version of this library, file names can be entered as UPPERCASE string of 11 bytes in length with no dot character between file name and extension (i.e. "MIKROELETXT" -> MIKROELE.TXT). In this case the last 3 characters of the string are considered to be file extension.

• file_attr: file creation and attributs flags. Each bit corresponds to the appropriate file attribut:

Bit	Mask	Description
0	0x01	Read Only
1	0x02	Hidden
2	0x04	System
3	0x08	Volume Label
4	0x10	Subdirectory
5	0x20	Archive
6	0x40	Device (internal use only, never found on disk)
7	0x80	Not used

  Note : Long File Names (LFN) are not supported.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

//-------------- Try to create a swap file with archive atribute, whose size will be at least 1000 sectors.
//               If it succeeds, it sends No. of start sector over USART
var size : dword;
...
size := Mmc_Fat_Get_Swap_File(1000, 'mikroE.txt', 0x20);
if (size <> 0) then
begin
  UART1_Write(0xAA);
  UART1_Write(Lo(size));
  UART1_Write(Hi(size));
  UART1_Write(Higher(size));
  UART1_Write(Highest(size));
  UART1_Write(0xAA);
end;

This routine is used to retrieve the cursor position within an opened file.

None.

Returns the cursor position in currently assigned file.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

var position : dword;

position := Mmc_Fat_Tell();

None.

This routine is used to set the cursor position within an opened file and returns the cursor's new position within an opened file.

• position: desired position on which we want to place the cursor.

Returns the cursor's new position in currently assigned file.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

var position : dword;

position := Mmc_Fat_Seek(1000);

If the desired cursor position exceeds file size, the cursor will be placed at the end of the file.

This function renames the currently assigned file.

• newname: new file name.

• 1 - if there are no assigned files
• 2 - if the new name in invalied
• 3 - if the file with the new name already exists
• 4 - if an error occurred during renaming
• 0 - if renaming was successful

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

The file must be previously assigned. See Mmc_Fat_Assign.

if (0 = Mmc_Fat_Rename('NEWNAME.TXT')) then 	// if rename operation was successful...
begin
...
end;

None.

This function creates a new directory.

• name: directory name.
• attrib: directory attribute.

• 0 - directory creation was successful
• 255 - if an error occurred

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

if (0 = Mmc_Fat_MakeDir('DIR_A')) then
begin  // create DIR_A directory
...
end;

None.

This function renames a directory.

• oldname: old directory name.
• newname: new directory name.

• 1 - if directory name is invalid
• 2 - if there is no directry with the old name
• 3 - if an entry with the new name already exits
• 4 - if an error occurred during renaming
• 0 - if renaming was successful

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

if (0 = Mmc_Fat_RenameDir('DIR_A', 'DIR_B')) // if rename operation was successful...
begin
...
end;

None.

This function removes directory entry from current directory.

• name: directory name.

• 1 - if directory name is invalid
• 2 - if directory name is non-existant
• 3 - if directory is not empty
• 4 - if an error occurred while writing
• 0 - if operation was successful

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

if (0 = Mmc_Fat_RemoveDir('DIR_A')) then	// if removing operation was successful...
begin
...
end;

Recursive removing is not supported, i.e. the directory must be empty before it can be removed.

This function changes the current directory to name.

• name: directory name.

• 0 - if operation was successful
• 1 - if there is no entry with given directory name
• 2 - if an entry with the given name is not a directory

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

// enter DIR_A directory
if (0 = Mmc_Fat_ChangeDir('DIR_A')) then
begin
...
end;

// go to parent directory
if (0 = Mmc_Fat_ChangeDir('..')) then
begin
...
end;

// go to root directory
if (0 = Mmc_Fat_ChangeDir('\')) then
begin
...
end;

Special directory names like "." and ".." are also supported.

This function returns information on file/directory existence.

• name: file/directory name.

• 0 - if file/directory doesn't exist
• 1 - if file/directory exists

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

status := Mmc_Fat_Exists('X_FILES.TXT');

// if process was successful...
if (0 = status) then
begin
...
end;

// if an error occurred...
if (255 = status) then	
begin
...
end;

None.

This routine displays contents of the current directory via user-defined medium (i.e. UART module, a file on FAT16 file system). The function displays character by character.

• print: function pointer to a routine which will display contents of the current directory.

• 1 - if file nema is invalid
• 2 - if file already exists
• 3 - if error occured while writing
• 0 - if operation was successful

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

type TProcedure = procedure(ch : char);

// Displaying routine
procedure PrintChar(ch : char);
begin
  UART1_Write(ch);
end;

...

Mmc_Fat_Dir(@PrintChar);

None.

This function gets next directory entry from current directory.

• d: directory entry (valid if return value equals 1), consisted of the following fields :
  
  
  Copy Code To Clipboard

  type F16_DIR = record
      name    : array[12] of char; // directory name
      attrib  : byte;              // directory attribute
      ctime   : array[6] of byte;  // create time and date
      mtime   : array[6] of byte;  // modification time and date
      size    : dword;             // directory size
      first   : word;              // directory start cluster
      sect    : dword;             // directory entry sector
      entry   : word;              // derectory entry number in the entry sector
  end;
  

• < 0 - if an error occurred
• 0 - if no more entries
• 1 - if a valid entry is returned

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

if (1 = Mmc_Fat_ReadDir('DIR_A')) then
begin
...
end;

None.

This function selects active file of currently opened files.

• fileHandle: file handle of the file which need to be activated.

• 0 - if activation was successful
• 1 - if file handle is out of scope
• 2 - if file handle is empty

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

var fhandle : short;

fhandle := Mmc_Fat_Open('X_FILES.TXT', FILE_READ, 0x01);

if (Mmc_Fat_Activate(fhandle)) = 0) then
begin

end;

Use Mmc_Fat_Open function to get file handles.

This function reads multiple bytes.

• fdata: data buffer.
• n: number of bytes to read.

Number of read bytes.

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

var data_buffer : array[512] of byte;
var no_bytes : word;
...
no_bytes := Mmc_Fat_ReadN(@data_buffer, 500);

None.

This function opens a new file.

• name: file name.
• mode: file handling mode, FILE_WRITE, FILE_READ or FILE_APPEND.
• attrib: file creation and attributes flags. Each bit corresponds to the appropriate file attribute :

Bit	Mask	Description
0	0x01	Read Only
1	0x02	Hidden
2	0x04	System
3	0x08	Volume Label
4	0x10	Subdirectory
5	0x20	Archive
6	0x40	Device (internal use only, never found on disk)
7	0x80	File creation flag. If file does not exist and this flag is set, a new file with specified name will be created.

• < 0 - if an error occurred
• file handle for opened file otherwise

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

var fhandle : short;

fhandle := Mmc_Fat_Open('X_FILES.TXT', FILE_READ, 0x01);

None.

This function closes currently opened file.

None.

• 0 - if closing was successful
• 1 - if there are no assigned files

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

if (Mmc_Fat_Close() = 0) then
begin

end;

None.

This function check if the end of file is reached.

None.

• -1 - if an error occurred
• 0 - if end of file was not reached
• 1 - if end of file was reached

MMC/SD card and MMC library must be initialized for file operations. See Mmc_Fat_Init.

if (Mmc_Fat_EOF() = 0) then
begin

end;

None.