Component: File (SD/SDHC Card) (File)

Author	Matrix Ltd.
Version	3.0
Category	File

File (SD/SDHC Card) component

File component allowing access to read and write files on a SD/SDHC card. Also compatible with micro SD/SDHC cards, please note the pin layout is subtely different for these. The component automatically detects the filesystem on the card on initialise so FAT16 and FAT32 are fully supported. When used in simulation provides read/write access to files on the local windows file system.

Component Source Code

Please click here to download the component source project: FC_Comp_Source_File_SD_FAT.fcfx

Please click here to view the component source code (Beta): FC_Comp_Source_File_SD_FAT.fcfx

Detailed description

No detailed description exists yet for this component

Examples

No additional examples

Macro reference

ReadStringFromFile

	ReadStringFromFile
Reads a string from the currently open file. Auto increments the position in the file. An empty string signifies the end of the file has been reached.
- UINT	NumBytes
Maximum number of bytes to attempt to read
- BYTE	EndChar
Ends the string if the value specified is found, default is 0
- STRING	Return

WriteByteToBuffer

	WriteByteToBuffer
Writes a single byte to the current 512 byte local sector buffer.
- UINT	Address
Address Range 0 - 511
- BYTE	Data
Data Byte to write to the buffer
- VOID	Return

MoveToNextFileSector

	MoveToNextFileSector
Attempts to move to the next sector in the file. When reading a file you would leave force next sector set to 0. When writing a file you would leave force next sector set to 1 to allow new sectors to be created as the file grows. Returns 0 for success
- BYTE	Force_Next_Sector
0 = Don't add new sector, 1 = Add new sector if we are at the end of the file
- BYTE	Return

AppendByteToFile

	AppendByteToFile
Adds a single byte to the end of the currently open file, useful for inserting the value 0 into binary file types. Returns 0 for success.
- BYTE	Data
Data to append to the end of the file
- BYTE	Return

ReadFileSector

	ReadFileSector
Overwrites local buffer with the current file sector from the disk. Used to restore the local sector buffer with the actual sector stored on the card. Return = 0 : Local buffer refreshed with current card sector Return > 0 : Error
- BYTE	Return

CloseFile

	CloseFile
Closes the current open file
- VOID	Return

ReadByteFromFile

	ReadByteFromFile
Reads a byte from the currently open file. Auto increments the position in the file. A return value of 0 may signify the end of the file has been reached (depending on the contents of the file).
- UINT	Return

DeleteFile

	DeleteFile
Searches for and deletes a file in the current folder location on the card. Default = Root Returns 0 for success.
- STRING	Filename
8.3 format filename e.g."file.txt"
- BYTE	Return

ReadByteFromIndex

	ReadByteFromIndex
Reads an arbitrary byte of data from the current open file. Return = Data byte read from the local sector buffer. Experimental and potentially slow if navigating backwards through the file.
- ULONG	Address
Contains the position of the byte to be read from the file
- BYTE	Return

CreateFile

	CreateFile
Creates a file in the current folder location on the card. Default = Root Returns 0 for success File must be opened using "Open_File" after creation before writing any data.
- STRING	Filename
8.3 format filename e.g."file.txt"
- BYTE	Return

ScanCurrentFolder

	ScanCurrentFolder
Method for retreiving file or folder names for the card to allow for dynamic file opening or playback. Does not currently simulate. 0 - Filetype found and stored into string array, 1 - End of folder reached, 2 - Filetype mismatch 3 - Empty
- UINT	Current_Idx
Contains the current pointer in the directory table. Values from 0 to 511 to completley search the current folder for a files or folders
- BYTE	Scan_Type
Sets the scan to search for Files or Folders. 0 = Scan for files, 1 = Scan for folders
- BYTE	Return

ReadByteFromScan

	ReadByteFromScan
Returns a byte of the name of the file or folder retreived from the Scan_Current_folder function. Return = ASCII byte at position Idx from the folder name or file name at position Current_Idx in the directory
- BYTE	idx
0 - 11 for a file, 0 - 7 for a folder
- BYTE	Return

OpenFolder

	OpenFolder
".." - Jumps up a directory, if at root then remains in root "root" - Jumps directly back to the root directory "foldername" - Opens folder named foldername
- STRING	Folder_Name
- BYTE	Return

ReadByteFromBuffer

	ReadByteFromBuffer
Reads a byte of data from the local sector buffer. Return = Data byte read from the local sector buffer.
- UINT	Address
0 - 511 - Contains the position of the byte to be read
- BYTE	Return

ReadFileLength

	ReadFileLength
Returns the number of bytes in the current sector that are used by the current open file. Return = 512 - Sector is filled with file data Return < 512 - Last sector of the file, Retval specifies how many bytes of data are remaining in the sector
- INT	Return

OpenFile

	OpenFile
Searches for and opens a file for reading or writing from within the current directory on the disk. Returns 0 for success.
- STRING	Filename
8.3 filename of the file we are trying to open e.g. "file.txt"
- BYTE	Return

WriteFileSector

	WriteFileSector
Overwrites the current sector on the memory card with the contents of the local sector buffer. See write_byte_to_buffer function. Return = 0 - File sector written successfully. Return > 0 - File sector write error
- BYTE	Return

SetFileIndex

	SetFileIndex
Sets the current file index and used to switch between several open file streams. Default = 0.
- BYTE	File_Index
File index ranges from 0 to (Max Concurrent Files - 1)
- VOID	Return

AppendStringToFile

	AppendStringToFile
Adds the contents of the data string parameter to the end of the currently open file. Returns 0 for success.
- STRING	Data_String
Data to append to the end of the file
- BYTE	Return

ReadFileSize

	ReadFileSize
Reads the entire size of the current file in bytes.
- ULONG	Return

UpdateFileSector

	UpdateFileSector
Updates a file sector with new data set from using WriteByteToBuffer. Note this cannot alter the size of the file.
- VOID	Return

SetTimeAndDate

	SetTimeAndDate
Sets the current time and date. Time = (Hour << 11) + (Min << 5) + (Sec >> 1) Date = (YearFrom1980 << 9) + (Month << 5) + (Day) Additional details can be found here: http://www.maverick-os.dk/FileSystemFormats/FAT16_FileSystem.html#TimeFormat
- UINT	Time
Sets the current Time in FAT Time format hhhhhmmmmmmsssss - S=Secs/2
- UINT	Date
Sets the current Date in FAT Date format yyyyyyymmmmddddd - Y=Years since 1980
- VOID	Return

Initialise

	Initialise
Attempts to communicate with the SD card and if successful sets up the file system. Returns 0 for success.
- BYTE	Return

Property reference

	Properties
	Connections
	Channel
SPI Channel selector
	MOSI
SPI Data Out Pin SDO - Also Known as Master Out Slave In (MOSI) when used in Master mode.
	MISO
SPI Data In Pin SDI - Also Known as Master In Slave Out (MISO) when used in Master mode.
	CLK
SPI Clock Pin CLK - The Clock signal is driven by the SPI master.
	CS / SS
Chip Select / Slave Select Pin Master Mode: General purpose output pin used to select the remote SPI device. Slave Mode: Hardware chip select pin input used to select the SPI device.
	Initial Prescaler
SPI initial clock divider - Frequency should be under 400khz to allow startup to work correctly.
	High Speed Prescaler
SPI high speed clock divider - Once startup is complete this is the rate that will be used to transfer data
	File System
	Max Concurrent Files
Specifies how many concurrent files can be opened at any one time. Use the SetFileIndex macro to switch between concurrent files.
	End Of File
Specifies the way the ReadByteFromFile function indicates the end of a file. 8 Bit mode - End of the file is represented by the value 0, read multiple times to confirm that the 0 is not simply data. 16 Bit mode - End of file is represented by the value 512 allowing the values 0 - 255 to represent valid data.
	Simulation
	Sim Type
Defines the simulation type. The default is to use the Windows file system to allow for reading and writing files. The alternative is to use the CAL functionality to allow the SPI transactions to be passed onto a seperate handler e.g. for logging or debugging purposes.
	File System
	Root Directory
Directory flagged as root for simulation Default: $(srcdir) is the current project source directory. Modern windows systems do not like you writing files to a hard drive root directory so a directory off the root is advised.